native-purchases

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

In-app Purchases Made Easy

This plugin allows you to implement in-app purchases and subscriptions in your Capacitor app using native APIs.

Why Native Purchases?

The only free, battle-tested in-app purchase plugin for Capacitor with full feature parity:

StoreKit 2 (iOS) - Uses Apple's latest purchase APIs for iOS 15+
Google Play Billing 7.x (Android) - Implements the newest billing library
Complete feature set - In-app products AND subscriptions with base plans
Same JavaScript API - Compatible interface with paid alternatives
Comprehensive validation - Built-in receipt/token validation examples
Modern package management - Supports both Swift Package Manager (SPM) and CocoaPods (SPM-ready for Capacitor 8)
Production-ready - Extensive documentation, testing guides, refund handling

Perfect for apps monetizing through one-time purchases or recurring subscriptions.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/native-purchases/

Install

npm install @capgo/native-purchases
npx cap sync

📚 Testing Guides

Complete visual testing guides for both platforms:

Platform	Guide	Content
🍎 iOS	iOS Testing Guide	StoreKit Local Testing, Sandbox Testing, Developer Mode setup
🤖 Android	Android Testing Guide	Internal Testing, License Testing, Internal App Sharing

💡 Quick Start: Choose StoreKit Local Testing for iOS or Internal Testing for Android for the fastest development experience.

Android

Add this to manifest

<uses-permission android:name="com.android.vending.BILLING" />

Testing with Google Play Console

📖 Complete Android Testing Guide - Comprehensive guide covering Internal Testing, License Testing, and Internal App Sharing methods with step-by-step instructions, troubleshooting, and best practices.

For testing in-app purchases on Android:

Upload your app to Google Play Console (internal testing track is sufficient)
Create test accounts in Google Play Console:
- Go to Google Play Console
- Navigate to "Setup" > "License testing"
- Add Gmail accounts to "License testers" list
Install the app from Google Play Store on a device signed in with a test account
Test purchases will be free and won't charge real money

iOS

Add the "In-App Purchase" capability to your Xcode project:

Open your project in Xcode
Select your app target
Go to "Signing & Capabilities" tab
Click the "+" button to add a capability
Search for and add "In-App Purchase"

⚠️ App Store Requirement: You MUST display product names and prices using data from the plugin (product.title, product.priceString). Hardcoded values will cause App Store rejection.

📖 Complete iOS Testing Guide - Comprehensive guide covering both Sandbox and StoreKit local testing methods with step-by-step instructions, troubleshooting, and best practices.

Testing with Sandbox

For testing in-app purchases on iOS:

Create a sandbox test user in App Store Connect:
- Go to App Store Connect
- Navigate to "Users and Access" > "Sandbox Testers"
- Create a new sandbox tester account
On your iOS device, sign out of your regular Apple ID in Settings > App Store
Install and run your app
When prompted for Apple ID during purchase testing, use your sandbox account credentials

Usage

Import the plugin in your TypeScript file:

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

⚠️ Important: In-App vs Subscription Purchases

There are two types of purchases with different requirements:

Purchase Type	productType	planIdentifier	Use Case
In-App Purchase	`PURCHASE_TYPE.INAPP`	❌ Not needed	One-time purchases (premium features, remove ads, etc.)
Subscription	`PURCHASE_TYPE.SUBS`	✅ REQUIRED (Android only)	Recurring purchases (monthly/yearly subscriptions)

Key Rules:

✅ In-App Products: Use productType: PURCHASE_TYPE.INAPP, no planIdentifier needed on any platform
✅ Subscriptions on Android: Must use productType: PURCHASE_TYPE.SUBS AND planIdentifier: "your-plan-id" (the Base Plan ID from Google Play Console)
✅ Subscriptions on iOS: Use productType: PURCHASE_TYPE.SUBS, planIdentifier is optional and ignored
❌ Missing planIdentifier for Android subscriptions will cause purchase failures

About planIdentifier (Android-specific): The planIdentifier parameter is only required for Android subscriptions. It should be set to the Base Plan ID that you configure in the Google Play Console when creating your subscription product. For example, if you create a monthly subscription with base plan ID "monthly-plan" in Google Play Console, you would use planIdentifier: "monthly-plan" when purchasing that subscription.

iOS does not use this parameter - subscriptions on iOS only require the product identifier.

Complete Example: Get Product Info and Purchase

Here's a complete example showing how to get product information and make purchases for both in-app products and subscriptions:

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

class PurchaseManager {
  // In-app product (one-time purchase)
  private premiumProductId = 'com.yourapp.premium_features';
  
  // Subscription products (require planIdentifier on Android)
  private monthlySubId = 'com.yourapp.premium.monthly';
  private monthlyPlanId = 'monthly-plan';  // Base plan ID from Google Play Console (Android only)

  private yearlySubId = 'com.yourapp.premium.yearly';
  private yearlyPlanId = 'yearly-plan';    // Base plan ID from Google Play Console (Android only)

  async initializeStore() {
    try {
      // 1. Check if billing is supported
      const { isBillingSupported } = await NativePurchases.isBillingSupported();
      if (!isBillingSupported) {
        throw new Error('Billing not supported on this device');
      }

      // 2. Get product information (REQUIRED by Apple - no hardcoded prices!)
      await this.loadProducts();
      
    } catch (error) {
      console.error('Store initialization failed:', error);
    }
  }

  async loadProducts() {
    try {
      // Load in-app products
      const { product: premiumProduct } = await NativePurchases.getProduct({
        productIdentifier: this.premiumProductId,
        productType: PURCHASE_TYPE.INAPP
      });
      
      // Load subscription products  
      const { products: subscriptions } = await NativePurchases.getProducts({
        productIdentifiers: [this.monthlySubId, this.yearlySubId],
        productType: PURCHASE_TYPE.SUBS
      });
      
      console.log('Products loaded:', {
        premium: premiumProduct,
        subscriptions: subscriptions
      });
      
      // Display products with dynamic info from store
      this.displayProducts(premiumProduct, subscriptions);
      
    } catch (error) {
      console.error('Failed to load products:', error);
      throw error;
    }
  }

  displayProducts(premiumProduct: any, subscriptions: any[]) {
    // ✅ CORRECT: Use dynamic product info (required by Apple)
    
    // Display one-time purchase
    document.getElementById('premium-title')!.textContent = premiumProduct.title;
    document.getElementById('premium-price')!.textContent = premiumProduct.priceString;
    
    // Display subscriptions
    subscriptions.forEach(sub => {
      const element = document.getElementById(`sub-${sub.identifier}`);
      if (element) {
        element.textContent = `${sub.title} - ${sub.priceString}`;
      }
    });
    
    // ❌ WRONG: Never hardcode prices - Apple will reject your app
    // document.getElementById('premium-price')!.textContent = '$9.99';
  }

  // Purchase one-time product (no planIdentifier needed)
  async purchaseInAppProduct() {
    try {
      console.log('Starting in-app purchase...');
      
      const result = await NativePurchases.purchaseProduct({
        productIdentifier: this.premiumProductId,
        productType: PURCHASE_TYPE.INAPP,
        quantity: 1
      });
      
      console.log('In-app purchase successful!', result.transactionId);
      await this.handleSuccessfulPurchase(result.transactionId, 'premium');
      
    } catch (error) {
      console.error('In-app purchase failed:', error);
      this.handlePurchaseError(error);
    }
  }

  // Purchase subscription (planIdentifier REQUIRED for Android)
  async purchaseMonthlySubscription() {
    try {
      console.log('Starting subscription purchase...');

      const result = await NativePurchases.purchaseProduct({
        productIdentifier: this.monthlySubId,
        planIdentifier: this.monthlyPlanId,    // REQUIRED for Android subscriptions, ignored on iOS
        productType: PURCHASE_TYPE.SUBS,       // REQUIRED for subscriptions
        quantity: 1
      });

      console.log('Subscription purchase successful!', result.transactionId);
      await this.handleSuccessfulPurchase(result.transactionId, 'monthly');

    } catch (error) {
      console.error('Subscription purchase failed:', error);
      this.handlePurchaseError(error);
    }
  }

  // Purchase yearly subscription (planIdentifier REQUIRED for Android)
  async purchaseYearlySubscription() {
    try {
      console.log('Starting yearly subscription purchase...');

      const result = await NativePurchases.purchaseProduct({
        productIdentifier: this.yearlySubId,
        planIdentifier: this.yearlyPlanId,     // REQUIRED for Android subscriptions, ignored on iOS
        productType: PURCHASE_TYPE.SUBS,       // REQUIRED for subscriptions
        quantity: 1
      });

      console.log('Yearly subscription successful!', result.transactionId);
      await this.handleSuccessfulPurchase(result.transactionId, 'yearly');

    } catch (error) {
      console.error('Yearly subscription failed:', error);
      this.handlePurchaseError(error);
    }
  }

  async handleSuccessfulPurchase(transactionId: string, purchaseType: string) {
    // 1. Grant access to premium features
    localStorage.setItem('premium_active', 'true');
    localStorage.setItem('purchase_type', purchaseType);
    
    // 2. Update UI
    const statusText = purchaseType === 'premium' ? 'Premium Unlocked' : `${purchaseType} Subscription Active`;
    document.getElementById('subscription-status')!.textContent = statusText;
    
    // 3. Optional: Verify purchase on your server
    await this.verifyPurchaseOnServer(transactionId);
  }

  handlePurchaseError(error: any) {
    // Handle different error scenarios
    if (error.message.includes('User cancelled')) {
      console.log('User cancelled the purchase');
    } else if (error.message.includes('Network')) {
      alert('Network error. Please check your connection and try again.');
    } else {
      alert('Purchase failed. Please try again.');
    }
  }

  async verifyPurchaseOnServer(transactionId: string) {
    try {
      // Send transaction to your server for verification
      const response = await fetch('/api/verify-purchase', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ transactionId })
      });
      
      const result = await response.json();
      console.log('Server verification:', result);
    } catch (error) {
      console.error('Server verification failed:', error);
    }
  }

  async restorePurchases() {
    try {
      await NativePurchases.restorePurchases();
      console.log('Purchases restored successfully');

      // Check if user has active premium after restore
      const product = await this.getProductInfo();
      // Update UI based on restored purchases

    } catch (error) {
      console.error('Failed to restore purchases:', error);
    }
  }

  async openSubscriptionManagement() {
    try {
      await NativePurchases.manageSubscriptions();
      console.log('Opened subscription management page');
    } catch (error) {
      console.error('Failed to open subscription management:', error);
    }
  }
}

// Usage in your app
const purchaseManager = new PurchaseManager();

// Initialize when app starts
purchaseManager.initializeStore();

// Attach to UI buttons
document.getElementById('buy-premium-button')?.addEventListener('click', () => {
  purchaseManager.purchaseInAppProduct();
});

document.getElementById('buy-monthly-button')?.addEventListener('click', () => {
  purchaseManager.purchaseMonthlySubscription();
});

document.getElementById('buy-yearly-button')?.addEventListener('click', () => {
  purchaseManager.purchaseYearlySubscription();
});

document.getElementById('restore-button')?.addEventListener('click', () => {
  purchaseManager.restorePurchases();
});

document.getElementById('manage-subscriptions-button')?.addEventListener('click', () => {
  purchaseManager.openSubscriptionManagement();
});

Quick Examples

Get Multiple Products

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Get in-app products (one-time purchases)
const getInAppProducts = async () => {
  try {
    const { products } = await NativePurchases.getProducts({
      productIdentifiers: [
        'com.yourapp.premium_features',
        'com.yourapp.remove_ads',
        'com.yourapp.extra_content'
      ],
      productType: PURCHASE_TYPE.INAPP
    });
    
    products.forEach(product => {
      console.log(`${product.title}: ${product.priceString}`);
    });
    
    return products;
  } catch (error) {
    console.error('Error getting in-app products:', error);
  }
};

// Get subscription products
const getSubscriptions = async () => {
  try {
    const { products } = await NativePurchases.getProducts({
      productIdentifiers: [
        'com.yourapp.premium.monthly',
        'com.yourapp.premium.yearly'
      ],
      productType: PURCHASE_TYPE.SUBS
    });
    
    products.forEach(product => {
      console.log(`${product.title}: ${product.priceString}`);
    });
    
    return products;
  } catch (error) {
    console.error('Error getting subscriptions:', error);
  }
};

Simple Purchase Flow

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Simple one-time purchase (in-app product)
const buyInAppProduct = async () => {
  try {
    // Check billing support
    const { isBillingSupported } = await NativePurchases.isBillingSupported();
    if (!isBillingSupported) {
      alert('Purchases not supported on this device');
      return;
    }

    // Get product (for price display)
    const { product } = await NativePurchases.getProduct({
      productIdentifier: 'com.yourapp.premium_features',
      productType: PURCHASE_TYPE.INAPP
    });

    // Confirm with user (showing real price from store)
    const confirmed = confirm(`Purchase ${product.title} for ${product.priceString}?`);
    if (!confirmed) return;

    // Make purchase (no planIdentifier needed for in-app)
    const result = await NativePurchases.purchaseProduct({
      productIdentifier: 'com.yourapp.premium_features',
      productType: PURCHASE_TYPE.INAPP,
      quantity: 1,
      appAccountToken: uuidToken // Optional: User identifier in UUID format
                                 // iOS: Must be valid UUID (required by StoreKit 2)
                                 // Android: UUID works, or any obfuscated string (max 64 chars)
                                 // RECOMMENDED: Use UUID v5 for cross-platform compatibility
                                 // Example: uuidv5(userId, APP_NAMESPACE)
    });

    alert('Purchase successful! Transaction ID: ' + result.transactionId);
    
    // iOS will also return receipt data for validation
    if (result.receipt) {
      // Send to your backend for validation
      await validateReceipt(result.receipt);
    }
    
  } catch (error) {
    alert('Purchase failed: ' + error.message);
  }
};

// Simple subscription purchase (requires planIdentifier)
const buySubscription = async () => {
  try {
    // Check billing support
    const { isBillingSupported } = await NativePurchases.isBillingSupported();
    if (!isBillingSupported) {
      alert('Purchases not supported on this device');
      return;
    }

    // Get subscription product (for price display)
    const { product } = await NativePurchases.getProduct({
      productIdentifier: 'com.yourapp.premium.monthly',
      productType: PURCHASE_TYPE.SUBS
    });

    // Confirm with user (showing real price from store)
    const confirmed = confirm(`Subscribe to ${product.title} for ${product.priceString}?`);
    if (!confirmed) return;

    // Make subscription purchase (planIdentifier REQUIRED for Android, ignored on iOS)
    const result = await NativePurchases.purchaseProduct({
      productIdentifier: 'com.yourapp.premium.monthly',
      planIdentifier: 'monthly-plan',           // REQUIRED for Android subscriptions, ignored on iOS
      productType: PURCHASE_TYPE.SUBS,          // REQUIRED for subscriptions
      quantity: 1,
      appAccountToken: uuidToken                // Optional: User identifier in UUID format
                                                // iOS: Must be valid UUID (required by StoreKit 2)
                                                // Android: UUID works, or any obfuscated string (max 64 chars)
                                                // RECOMMENDED: Use UUID v5 for cross-platform compatibility
                                                // Example: uuidv5(userId, APP_NAMESPACE)
    });

    alert('Subscription successful! Transaction ID: ' + result.transactionId);
    
    // iOS will also return receipt data for validation
    if (result.receipt) {
      // Send to your backend for validation
      await validateReceipt(result.receipt);
    }
    
  } catch (error) {
    alert('Subscription failed: ' + error.message);
  }
};

Check if billing is supported

Before attempting to make purchases, check if billing is supported on the device: We only support Storekit 2 on iOS (iOS 15+) and google play on Android

const checkBillingSupport = async () => {
  try {
    const { isBillingSupported } = await NativePurchases.isBillingSupported();
    if (isBillingSupported) {
      console.log('Billing is supported on this device');
    } else {
      console.log('Billing is not supported on this device');
    }
  } catch (error) {
    console.error('Error checking billing support:', error);
  }
};

Manage Subscriptions

Allow users to manage their subscriptions directly from your app. This opens the platform's native subscription management page:

import { NativePurchases } from '@capgo/native-purchases';

const openSubscriptionSettings = async () => {
  try {
    await NativePurchases.manageSubscriptions();
    // On iOS: Opens the App Store subscription management page
    // On Android: Opens the Google Play subscription management page
  } catch (error) {
    console.error('Error opening subscription management:', error);
  }
};

This is particularly useful for:

Allowing users to cancel or modify their subscriptions
Viewing subscription renewal dates
Changing subscription plans
Managing billing information

Using appAccountToken for Fraud Detection and User Linking

The appAccountToken parameter is an optional but highly recommended security feature that helps both you and the platform stores detect fraud and link purchases to specific users in your app.

What is appAccountToken?

An identifier (max 64 characters) that uniquely associates transactions with user accounts in your app. It serves two main purposes:

Fraud Detection: Google Play and Apple use this to detect irregular activity, such as many devices making purchases on the same account within a brief timeframe
User Linking: Links purchases to specific in-game characters, avatars, or in-app profiles that initiated the purchase

Platform-Specific Requirements

IMPORTANT: iOS and Android have different format requirements:

Platform	Format Requirement	Maps To
iOS	Must be a valid UUID (e.g., `"550e8400-e29b-41d4-a716-446655440000"`)	Apple StoreKit 2's `appAccountToken` parameter
Android	Any obfuscated string (max 64 chars)	Google Play's `ObfuscatedAccountId`

iOS Specific:

Apple's StoreKit 2 requires the appAccountToken to be in UUID format
The plugin validates and converts the string to UUID before passing to StoreKit
If the format is invalid, the token will be ignored

Android Specific:

Google recommends using encryption or one-way hash
Storing PII in cleartext will result in purchases being blocked by Google Play

Critical Security Requirements

DO NOT use Personally Identifiable Information (PII) in cleartext:

❌ WRONG: appAccountToken: '[email protected]'
❌ WRONG: appAccountToken: 'john.doe'
✅ CORRECT (iOS & Android): appAccountToken: uuidv5(userId, NAMESPACE)
✅ CORRECT (Android only): appAccountToken: hash(userId).substring(0, 64)

For cross-platform compatibility, using UUID format is recommended for both platforms.

Implementation Example

// RECOMMENDED: Use UUID v5 for cross-platform compatibility (works on both iOS and Android)
import { v5 as uuidv5 } from 'uuid'; // npm install uuid

// Generate a deterministic UUID from user ID
function generateAppAccountToken(userId: string): string {
  // Use a consistent namespace UUID for your app (generate once and keep constant)
  const APP_NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';

  // Generate deterministic UUID - same userId always produces same UUID
  const uuid = uuidv5(userId, APP_NAMESPACE);

  return uuid; // e.g., "550e8400-e29b-41d4-a716-446655440000"
}

// ALTERNATIVE: For Android-only apps (SHA-256 hash)
function generateAppAccountTokenAndroidOnly(userId: string): string {
  // This works on Android but will be ignored on iOS (not UUID format)
  const hash = crypto.createHash('sha256')
    .update(userId)
    .digest('hex')
    .substring(0, 64); // Ensure max 64 chars

  return hash;
}

// ALTERNATIVE: HMAC with secret key for Android-only apps
function generateSecureAppAccountTokenAndroidOnly(userId: string, secretKey: string): string {
  // This works on Android but will be ignored on iOS (not UUID format)
  const hmac = crypto.createHmac('sha256', secretKey)
    .update(userId)
    .digest('hex')
    .substring(0, 64);

  return hmac;
}

// Use in your purchase flow (cross-platform)
const userId = 'user-12345'; // Your internal user ID
const appAccountToken = generateAppAccountToken(userId);

await NativePurchases.purchaseProduct({
  productIdentifier: 'com.yourapp.premium',
  productType: PURCHASE_TYPE.INAPP,
  appAccountToken: appAccountToken // UUID format works on both iOS and Android
});

// Later, retrieve purchases for this user
const { purchases } = await NativePurchases.getPurchases({
  appAccountToken: appAccountToken
});

Why UUID v5 is Recommended:

✅ Works on both iOS (required) and Android (accepted)
✅ Deterministic: Same user ID always produces the same UUID
✅ Secure: No PII exposure
✅ Standard format: Widely supported
✅ Reversible mapping: You can store the mapping in your backend

Best Practices

Use UUID v5 for cross-platform apps - Works on both iOS (required) and Android (accepted)
Keep your namespace UUID constant - Generate once and hardcode it in your app
Store the mapping - Keep a record of userId → appAccountToken in your backend for reverse lookup
Use during purchase - Include it when calling purchaseProduct()
Use for queries - Use it when calling getPurchases() to filter by user
Deterministic generation - Same user should always get the same token
Max 64 characters - UUID format is 36 characters, well within the limit

Benefits

Fraud Prevention: Platforms can detect suspicious patterns
Multi-device Support: Link purchases across devices for the same user
User Management: Query purchases for specific users
Analytics: Better insights into user purchasing behavior

Understanding Transaction Properties

When you inspect purchases using getPurchases() or restorePurchases(), you receive an array of Transaction objects. Understanding which properties are available and reliable for different scenarios is crucial for proper implementation.

Transaction Properties by Platform & Product Type

Here's a comprehensive breakdown of which properties you can expect and rely on:

Property	iOS IAP	iOS Subscription	Android IAP	Android Subscription	Notes
`transactionId`	✅ Always	✅ Always	✅ Always	✅ Always	Primary identifier for the transaction
`receipt`	✅ Always	✅ Always	❌ Never	❌ Never	iOS only - base64 receipt for validation
`productIdentifier`	✅ Always	✅ Always	✅ Always	✅ Always	Product ID purchased
`purchaseDate`	✅ Always	✅ Always	✅ Always	✅ Always	ISO 8601 format
`productType`	✅ Always	✅ Always	✅ Always	✅ Always	"inapp" or "subs"
`ownershipType`	✅ Always	✅ Always	❌ Never	❌ Never	iOS only - "purchased" or "familyShared" (iOS 15.0+, StoreKit 2)
`environment`	✅ iOS 16+	✅ iOS 16+	❌ Never	❌ Never	iOS only - "Sandbox", "Production", or "Xcode" (iOS 16.0+ only, not available on iOS 15)
`quantity`	✅ Always	✅ Always	✅ Always 1	✅ Always 1	iOS supports multiple, Android always 1
`appAccountToken`	✅ If provided	✅ If provided	✅ If provided	✅ If provided	Set if passed during purchase
`isActive`	❌ Not set	✅ Always	❌ Not set	❌ Not set	iOS subscriptions ONLY - calculated as expiration > now
`willCancel`	❌ Not set	✅ Always	✅ Always null	✅ Always null	iOS: subscription renewal status; Android: always null
`originalPurchaseDate`	❌ Not set	✅ Always	❌ Not set	❌ Not set	iOS subscriptions ONLY
`expirationDate`	❌ Not set	✅ Always	❌ Not set	❌ Not set	iOS subscriptions ONLY
`purchaseState`	❌ Not set	❌ Not set	✅ Always	✅ Always	Android ONLY - "PURCHASED", "PENDING", "0" (numeric)
`orderId`	❌ Not set	❌ Not set	✅ Always	✅ Always	Android ONLY
`purchaseToken`	❌ Not set	❌ Not set	✅ Always	✅ Always	Android ONLY - for validation
`isAcknowledged`	❌ Not set	❌ Not set	✅ Always	✅ Always	Android ONLY

Validating Purchases: Platform-Specific Best Practices

iOS In-App Purchases (One-Time)

const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.INAPP
});

// Example response for iOS IAP:
// {
//   "transactionId": "2000001043762129",
//   "receipt": "base64EncodedReceiptData...",
//   "productIdentifier": "com.yourapp.premium",
//   "purchaseDate": "2025-10-28T06:03:19Z",
//   "productType": "inapp"
// }

purchases.forEach(purchase => {
  // For iOS IAP, the mere presence in the list generally indicates a valid purchase
  // However, for security, you should validate the receipt on your server

  if (purchase.productIdentifier === 'com.yourapp.premium') {
    // Option 1: Basic client-side check (not recommended for production)
    if (purchase.receipt && purchase.transactionId) {
      grantPremiumAccess();
    }

    // Option 2: Server-side validation (RECOMMENDED)
    validateReceiptOnServer(purchase.receipt).then(isValid => {
      if (isValid) {
        grantPremiumAccess();
      }
    });
  }
});

Key Points for iOS IAP:

✅ If a purchase appears in getPurchases(), it's generally valid
❌ isActive is NOT set for one-time IAP purchases (only for subscriptions)
❌ expirationDate and originalPurchaseDate are NOT set for IAP
🔒 Always validate the receipt on your server for production apps
⚠️ Refunded purchases may still appear but will fail server validation

Android In-App Purchases (One-Time)

const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.INAPP
});

// Example response for Android IAP:
// {
//   "transactionId": "GPA.1234-5678-9012-34567",
//   "productIdentifier": "com.yourapp.premium",
//   "purchaseDate": "2025-10-28T06:03:19Z",
//   "purchaseState": "PURCHASED",
//   "orderId": "GPA.1234-5678-9012-34567",
//   "purchaseToken": "long-token-string...",
//   "isAcknowledged": true,
//   "productType": "inapp"
// }

purchases.forEach(purchase => {
  // For Android IAP, ALWAYS check purchaseState
  const isValidPurchase =
    purchase.purchaseState === 'PURCHASED' &&
    purchase.isAcknowledged === true;

  if (purchase.productIdentifier === 'com.yourapp.premium' && isValidPurchase) {
    grantPremiumAccess();

    // For extra security, validate on server (RECOMMENDED)
    validatePurchaseTokenOnServer(purchase.purchaseToken);
  }
});

Key Points for Android IAP:

✅ ALWAYS check purchaseState === "PURCHASED" or purchaseState === "1" - this is critical
✅ Check isAcknowledged === true (this plugin auto-acknowledges)
❌ isActive is NOT set on Android (for either IAP or subscriptions)
❌ expirationDate and originalPurchaseDate are NOT set on Android
🔒 For production, validate purchaseToken on your server with Google Play API

iOS Subscriptions

const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS
});

// Example response for active iOS subscription:
// {
//   "transactionId": "2000001043762130",
//   "receipt": "base64EncodedReceiptData...",
//   "productIdentifier": "com.yourapp.premium.monthly",
//   "purchaseDate": "2025-10-28T06:03:19Z",
//   "originalPurchaseDate": "2025-09-28T06:03:19Z",
//   "expirationDate": "2025-11-28T06:03:19Z",
//   "isActive": true,
//   "willCancel": false,
//   "productType": "subs",
//   "isTrialPeriod": false,
//   "isInIntroPricePeriod": false
// }

purchases.forEach(purchase => {
  // Check if subscription is currently active
  const isSubscriptionActive = purchase.isActive === true;

  // Alternative: Check expiration date
  const expirationDate = new Date(purchase.expirationDate);
  const isActiveByDate = expirationDate > new Date();

  // Check if user has cancelled (still active until expiration)
  const willAutoRenew = purchase.willCancel === false;

  if (isSubscriptionActive) {
    grantSubscriptionAccess();

    if (willAutoRenew) {
      console.log('Subscription will renew on', purchase.expirationDate);
    } else {
      console.log('Subscription cancelled, expires on', purchase.expirationDate);
    }
  }
});

Key Points for iOS Subscriptions:

✅ isActive is reliable for subscriptions
✅ expirationDate can be used to check validity
✅ willCancel tells you if subscription will auto-renew
⚠️ Even cancelled subscriptions show isActive: true until expiration
🔒 Validate receipt on server to detect refunds/revocations

Android Subscriptions

const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS
});

// Example response for active Android subscription:
// {
//   "transactionId": "GPA.1234-5678-9012-34568",
//   "productIdentifier": "com.yourapp.premium.monthly",
//   "purchaseDate": "2025-10-28T06:03:19Z",
//   "originalPurchaseDate": "2025-09-28T06:03:19Z",
//   "expirationDate": "2025-11-28T06:03:19Z",
//   "isActive": true,
//   "purchaseState": "PURCHASED",
//   "orderId": "GPA.1234-5678-9012-34568",
//   "purchaseToken": "long-token-string...",
//   "isAcknowledged": true,
//   "productType": "subs",
//   "isTrialPeriod": false
// }

purchases.forEach(purchase => {
  // Check if subscription is active using multiple signals
  const isActiveSubscription =
    purchase.purchaseState === 'PURCHASED' &&
    purchase.isActive === true &&
    purchase.isAcknowledged === true;

  // Alternative: Check expiration date
  const expirationDate = new Date(purchase.expirationDate);
  const isActiveByDate = expirationDate > new Date();

  if (isActiveSubscription || isActiveByDate) {
    grantSubscriptionAccess();
  }
});

Key Points for Android Subscriptions:

✅ Check purchaseState === "PURCHASED" or purchaseState === "1"
❌ isActive is NOT set on Android (even for subscriptions)
❌ expirationDate is NOT set on Android - must query Google Play API
❌ originalPurchaseDate is NOT set on Android
✅ willCancel is ALWAYS set to null on Android
🔒 For subscription status and expiration, query Google Play Developer API on your server

Handling Refunds and Cancellations

Understanding how refunds and cancellations affect your transaction data is critical for proper access control.

iOS Refund Behavior

What happens when a user requests a refund:

For In-App Purchases (IAP):
- The transaction may still appear in getPurchases() and restorePurchases()
- isActive is NOT set for IAP purchases (only for subscriptions)
- The receipt will NOT disappear from the device
- ✅ SOLUTION: Validate the receipt with Apple's servers - refunded transactions will be marked as invalid
For Subscriptions:
- The transaction will still appear in purchase history
- isActive will be set to false (subscriptions only set this field)
- expirationDate will be set to the refund date (in the past)
- ✅ SOLUTION: Check isActive === false OR expirationDate < now OR validate receipt on server

Example: Detecting iOS refunds

async function checkIOSPurchaseValidity(purchase: Transaction) {
  // Client-side check (not foolproof)
  if (purchase.isActive === false) {
    console.log('Purchase appears to be refunded or expired');
    return false;
  }

  // Server-side validation (RECOMMENDED)
  const validationResult = await fetch('https://your-server.com/validate-receipt', {
    method: 'POST',
    body: JSON.stringify({
      receipt: purchase.receipt,
      productId: purchase.productIdentifier
    })
  }).then(r => r.json());

  if (!validationResult.isValid || validationResult.isRefunded) {
    console.log('Receipt validation failed - purchase refunded or invalid');
    return false;
  }

  return true;
}

Sandbox vs Production Behavior:

✅ Refund behavior is consistent between sandbox and production
⚠️ Sandbox refunds are processed instantly, production may take hours/days
✅ Receipt validation works the same in both environments

Android Refund Behavior

What happens when a user requests a refund:

For In-App Purchases (IAP):
- The transaction typically disappears entirely from getPurchases()
- Google Play removes refunded purchases from the purchase history
- No receipt or transaction will be returned
- ✅ SOLUTION: If a previously-seen purchase is no longer in the list, it was likely refunded
For Subscriptions:
- The transaction may disappear OR
- isActive will be set to false
- purchaseState may be undefined or the transaction won't be returned at all
- ✅ SOLUTION: Track purchases on your server and listen for Google Play real-time developer notifications

Example: Detecting Android refunds

// Store previously seen purchases in local storage or your database
const previousPurchases = getPreviouslyStoredPurchases();

const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.INAPP
});

// Check for missing purchases (likely refunded)
previousPurchases.forEach(oldPurchase => {
  const stillExists = purchases.find(
    p => p.transactionId === oldPurchase.transactionId
  );

  if (!stillExists) {
    console.log(`Purchase ${oldPurchase.productIdentifier} no longer exists - likely refunded`);
    revokePremiumAccess(oldPurchase.productIdentifier);
  }
});

// Check current purchases for validity
purchases.forEach(purchase => {
  const isValid =
    purchase.purchaseState === 'PURCHASED' &&
    purchase.isAcknowledged === true;

  if (!isValid) {
    console.log('Invalid purchase state detected');
    // Don't grant access
  }
});

// Store current purchases for next comparison
storePurchases(purchases);

Sandbox vs Production Behavior:

⚠️ Sandbox test accounts can make unlimited "purchases" without payment
⚠️ Sandbox refunds are instant - purchase disappears immediately
⚠️ Production refunds may take several hours before purchase disappears
✅ Testing refunds in production requires real money and real refund requests

IMPORTANT: Without Server-Side Validation:

If you're not using a backend validator (not recommended for production), here's what to expect:

Scenario	iOS Behavior	Android Behavior
User requests IAP refund	Transaction may still appear in `restorePurchases()`, check `isActive`	Transaction disappears from `getPurchases()`
User cancels subscription	`willCancel: true`, still active until expiration	Transaction remains, check `isActive` and `expirationDate`
Subscription expires naturally	`isActive: false`, `expirationDate` in past	Transaction disappears OR `isActive: false`
User refunds subscription	Transaction remains with `isActive: false`	Transaction may disappear

RECOMMENDATION: Always implement server-side validation

Listen to Apple's App Store Server Notifications (iOS)
Listen to Google Play Real-Time Developer Notifications (Android)
Validate receipts/tokens on your server before granting access
See the Backend Validation section for implementation

Sandbox vs Production Differences

iOS: Sandbox vs Production

Similarities:

✅ Transaction structure is identical
✅ All properties return the same data format
✅ receipt validation works (use sandbox Apple endpoint)
✅ Refund behavior is consistent

Differences:

Aspect	Sandbox	Production
Payment processing	Instant, no real money	Real payment, takes seconds
Receipt validation endpoint	`https://sandbox.itunes.apple.com/verifyReceipt`	`https://buy.itunes.apple.com/verifyReceipt`
Subscription duration	Compressed (1 week = 5 minutes)	Real duration (1 week = 7 days)
Refund processing	Instant (via StoreKit Testing)	Takes hours/days, must contact Apple
Test user requirements	Sandbox Apple ID required	Real Apple ID
Transaction IDs	Real format, unique per test	Real format, unique per purchase
`receipt` data	Valid test receipt	Valid production receipt

Testing Refunds in Sandbox:

Use StoreKit Configuration file (local testing) for instant refunds
Or sandbox testing with sandbox Apple ID
Refunds are instant and can be tested repeatedly
Receipt validation will show refunded status immediately

Android: Sandbox vs Production

Similarities:

✅ Transaction structure is identical
✅ All properties return the same data format
✅ Purchase state values are the same

Differences:

Aspect	License Testing (Sandbox)	Production
Payment processing	No payment required	Real payment required
Purchase token validation	Works with Google Play API	Works with Google Play API
Transaction IDs	Test format: `GPA.1234-...`	Real format: `GPA.1234-...`
Refund processing	Instant (test account only)	Takes hours, appears as purchase disappearing
Test user requirements	Gmail added to license testers	Real Google account
`purchaseState` values	Same as production	Same as sandbox
Refund detection	Purchase disappears immediately	Purchase disappears after hours/days

Testing Refunds in Android Sandbox:

License testers can make unlimited purchases without payment
Refunds are instant - purchase disappears from getPurchases() immediately
Use Internal Testing track for most realistic testing
Real refunds in production require real purchases and real refund requests via Google Play

Key Difference:

In sandbox/test, refunded purchases disappear instantly
In production, refunded purchases may remain visible for hours before disappearing
Always implement server-side validation with Google Play Developer API to catch refunds reliably

Recommended Access Control Logic

Based on the above, here's the recommended approach for each platform and product type:

import { NativePurchases, PURCHASE_TYPE, Transaction } from '@capgo/native-purchases';
import { Capacitor } from '@capacitor/core';

async function checkUserAccess(productId: string, productType: PURCHASE_TYPE): Promise<boolean> {
  try {
    const { purchases } = await NativePurchases.getPurchases({ productType });
    const purchase = purchases.find(p => p.productIdentifier === productId);

    if (!purchase) {
      return false; // No purchase found
    }

    const platform = Capacitor.getPlatform();

    if (platform === 'ios') {
      // iOS Logic
      if (productType === PURCHASE_TYPE.INAPP) {
        // For IAP: presence in list + receipt validation
        // Note: isActive is NOT set for iOS IAP
        if (!purchase.receipt) return false;

        // IMPORTANT: Validate receipt on server for production
        const isValid = await validateReceiptOnServer(purchase.receipt);
        return isValid;

      } else {
        // For subscriptions: check isActive and expiration
        // iOS subscriptions ALWAYS have isActive and expirationDate
        if (purchase.isActive === false) return false;
        if (purchase.expirationDate) {
          const expiration = new Date(purchase.expirationDate);
          if (expiration < new Date()) return false;
        }
        return true;
      }

    } else if (platform === 'android') {
      // Android Logic
      if (productType === PURCHASE_TYPE.INAPP) {
        // For IAP: check purchase state and acknowledgment
        // Note: Android does NOT set isActive, expirationDate, or originalPurchaseDate
        const isValid =
          (purchase.purchaseState === 'PURCHASED' || purchase.purchaseState === '1') &&
          purchase.isAcknowledged === true;

        if (!isValid) return false;

        // IMPORTANT: Validate purchaseToken on server for production
        await validatePurchaseTokenOnServer(purchase.purchaseToken);
        return true;

      } else {
        // For subscriptions: check purchase state only
        // Android does NOT set isActive, expirationDate, or originalPurchaseDate
        // You MUST use Google Play Developer API on your server to get subscription details
        const isValidState =
          (purchase.purchaseState === 'PURCHASED' || purchase.purchaseState === '1') &&
          purchase.isAcknowledged === true;

        if (!isValidState) return false;

        // CRITICAL: Validate subscription status on server with Google Play API
        // The Purchase object doesn't include expiration dates
        const serverStatus = await validateAndGetSubscriptionStatus(purchase.purchaseToken);
        return serverStatus.isActive && serverStatus.expirationDate > new Date();
      }
    }

    return false;
  } catch (error) {
    console.error('Error checking user access:', error);
    return false;
  }
}

// Example usage
async function grantAccessBasedOnPurchase() {
  // Check for premium IAP
  const hasPremium = await checkUserAccess(
    'com.yourapp.premium',
    PURCHASE_TYPE.INAPP
  );

  // Check for active subscription
  const hasSubscription = await checkUserAccess(
    'com.yourapp.premium.monthly',
    PURCHASE_TYPE.SUBS
  );

  if (hasPremium || hasSubscription) {
    unlockPremiumFeatures();
  }
}

Critical Takeaways:

✅ For iOS IAP: isActive is NOT set - validate receipt on server
✅ For iOS Subscriptions: isActive and expirationDate ARE set - use them!
✅ For Android IAP: Check purchaseState === "PURCHASED" (or "1")
✅ For Android Subscriptions: isActive and expirationDate are NOT set - must use Google Play API on server
✅ For Refunds: iOS purchases may linger (validate server-side), Android purchases disappear
🔒 Always implement server-side validation for production apps

API Reference

Core Methods

// Check if in-app purchases are supported
await NativePurchases.isBillingSupported();

// Get single product information
await NativePurchases.getProduct({ productIdentifier: 'product_id' });

// Get multiple products
await NativePurchases.getProducts({ productIdentifiers: ['id1', 'id2'] });

// Purchase a product
await NativePurchases.purchaseProduct({
  productIdentifier: 'product_id',
  quantity: 1
});

// Restore previous purchases
await NativePurchases.restorePurchases();

// Open subscription management page
await NativePurchases.manageSubscriptions();

// Get plugin version
await NativePurchases.getPluginVersion();

Important Notes

Apple Requirement: Always display product names and prices from StoreKit data, never hardcode them
Error Handling: Implement proper error handling for network issues and user cancellations
Server Verification: Always verify purchases on your server for security
Testing: Use the comprehensive testing guides for both iOS and Android platforms

Backend Validation

It's crucial to validate receipts on your server to ensure the integrity of purchases. Here's an example of how to implement backend validation using a Cloudflare Worker:

Cloudflare Worker Setup Create a new Cloudflare Worker and follow the instructions in folder (validator)[/validator/README.md]

Then in your app, modify the purchase function to validate the receipt on the server:

import { Capacitor } from '@capacitor/core';
import { NativePurchases, PURCHASE_TYPE, Product, Transaction } from '@capgo/native-purchases';
import axios from 'axios'; // Make sure to install axios: npm install axios

class Store {
  // ... (previous code remains the same)

  // Purchase in-app product
  async purchaseProduct(productId: string) {
    try {
      const transaction = await NativePurchases.purchaseProduct({
        productIdentifier: productId,
        productType: PURCHASE_TYPE.INAPP
      });
      console.log('In-app purchase successful:', transaction);
      
      // Immediately grant access to the purchased content
      await this.grantAccess(productId);
      
      // Initiate server-side validation asynchronously
      this.validatePurchaseOnServer(transaction).catch(console.error);
      
      return transaction;
    } catch (error) {
      console.error('Purchase failed:', error);
      throw error;
    }
  }

  // Purchase subscription (requires planIdentifier)
  async purchaseSubscription(productId: string, planId: string) {
    try {
      const transaction = await NativePurchases.purchaseProduct({
        productIdentifier: productId,
        planIdentifier: planId,              // REQUIRED for subscriptions
        productType: PURCHASE_TYPE.SUBS      // REQUIRED for subscriptions
      });
      console.log('Subscription purchase successful:', transaction);
      
      // Immediately grant access to the subscription content
      await this.grantAccess(productId);
      
      // Initiate server-side validation asynchronously
      this.validatePurchaseOnServer(transaction).catch(console.error);
      
      return transaction;
    } catch (error) {
      console.error('Subscription purchase failed:', error);
      throw error;
    }
  }

  private async grantAccess(productId: string) {
    // Implement logic to grant immediate access to the purchased content
    console.log(`Granting access to ${productId}`);
    // Update local app state, unlock features, etc.
  }

  private async validatePurchaseOnServer(transaction: Transaction) {
    const serverUrl = 'https://your-server-url.com/validate-purchase';
    try {
      const response = await axios.post(serverUrl, {
        transactionId: transaction.transactionId,
        platform: Capacitor.getPlatform(),
        // Include any other relevant information
      });

      console.log('Server validation response:', response.data);
      // The server will handle the actual validation with the Cloudflare Worker
    } catch (error) {
      console.error('Error in server-side validation:', error);
      // Implement retry logic or notify the user if necessary
    }
  }
}

// Usage examples
const store = new Store();
await store.initialize();

try {
  // Purchase in-app product (one-time purchase)
  await store.purchaseProduct('premium_features');
  console.log('In-app purchase completed successfully');
  
  // Purchase subscription (requires planIdentifier)
  await store.purchaseSubscription('premium_monthly', 'monthly-plan');
  console.log('Subscription completed successfully');
} catch (error) {
  console.error('Purchase failed:', error);
}

Now, let's look at how the server-side (Node.js) code might handle the validation:

import express from 'express';
import axios from 'axios';

const app = express();
app.use(express.json());

const CLOUDFLARE_WORKER_URL = 'https://your-cloudflare-worker-url.workers.dev';

app.post('/validate-purchase', async (req, res) => {
  const { transactionId, platform } = req.body;

  try {
    const endpoint = platform === 'ios' ? '/apple' : '/google';
    const validationResponse = await axios.post(`${CLOUDFLARE_WORKER_URL}${endpoint}`, {
      receipt: transactionId
    });

    const validationResult = validationResponse.data;

    // Process the validation result
    if (validationResult.isValid) {
      // Update user status in the database
      // await updateUserStatus(userId, 'paid');
      
      // Log the successful validation
      console.log(`Purchase validated for transaction ${transactionId}`);
      
      // You might want to store the validation result for future reference
      // await storeValidationResult(userId, transactionId, validationResult);
    } else {
      // Handle invalid purchase
      console.warn(`Invalid purchase detected for transaction ${transactionId}`);
      // You might want to flag this for further investigation
      // await flagSuspiciousPurchase(userId, transactionId);
    }

    // Always respond with a success to the app
    // This ensures the app doesn't block the user's access
    res.json({ success: true });
  } catch (error) {
    console.error('Error validating purchase:', error);
    // Still respond with success to the app
    res.json({ success: true });
    // You might want to log this error or retry the validation later
    // await logValidationError(userId, transactionId, error);
  }
});

// Start the server
app.listen(3000, () => console.log('Server running on port 3000'));

Key points about this approach:

The app immediately grants access after a successful purchase, ensuring a smooth user experience.
The app initiates server-side validation asynchronously, not blocking the user's access.
The server handles the actual validation by calling the Cloudflare Worker.
The server always responds with success to the app, even if validation fails or encounters an error.
The server can update the user's status in the database, log results, and handle any discrepancies without affecting the user's immediate experience.

Comments on best practices:

// After successful validation:
// await updateUserStatus(userId, 'paid');

// It's crucial to not block or revoke access immediately if validation fails
// Instead, flag suspicious transactions for review:
// if (!validationResult.isValid) {
//   await flagSuspiciousPurchase(userId, transactionId);
// }

// Implement a system to periodically re-check flagged purchases
// This could be a separate process that runs daily/weekly

// Consider implementing a grace period for new purchases
// This allows for potential delays in server communication or store processing
// const GRACE_PERIOD_DAYS = 3;
// if (daysSincePurchase < GRACE_PERIOD_DAYS) {
//   grantAccess = true;
// }

// For subscriptions, regularly check their status with the stores
// This ensures you catch any cancelled or expired subscriptions
// setInterval(checkSubscriptionStatuses, 24 * 60 * 60 * 1000); // Daily check

// Implement proper error handling and retry logic for network failures
// This is especially important for the server-to-Cloudflare communication

// Consider caching validation results to reduce load on your server and the stores
// const cachedValidation = await getCachedValidation(transactionId);
// if (cachedValidation) return cachedValidation;

This approach balances immediate user gratification with proper server-side validation, adhering to Apple and Google's guidelines while still maintaining the integrity of your purchase system.

API

restorePurchases()
getAppTransaction()
isEntitledToOldBusinessModel(...)
purchaseProduct(...)
getProducts(...)
getProduct(...)
isBillingSupported()
getPluginVersion()
getPurchases(...)
manageSubscriptions()
acknowledgePurchase(...)
addListener('transactionUpdated', ...)
addListener('transactionVerificationFailed', ...)
removeAllListeners()
Interfaces
Enums

restorePurchases()

restorePurchases() => Promise<void>

Restores a user's previous and links their appUserIDs to any user's also using those .

getAppTransaction()

getAppTransaction() => Promise<{ appTransaction: AppTransaction; }>

Gets the App Transaction information, which provides details about when the user originally downloaded or purchased the app.

This is useful for implementing business model changes where you want to grandfather users who originally downloaded an earlier version of the app.

Use Case Example: If your app was originally free but you're adding a subscription, you can use originalAppVersion to check if users downloaded before the subscription was added and give them free access.

Platform Notes:

iOS: Requires iOS 16.0+. Uses StoreKit 2's AppTransaction</a>.shared.
Android: Uses Google Play's install referrer data when available.

Returns: Promise<{ appTransaction: AppTransaction; }>

Since: 7.16.0

isEntitledToOldBusinessModel(...)

isEntitledToOldBusinessModel(options: { targetVersion: string; }) => Promise<{ isOlderVersion: boolean; originalAppVersion: string; }>

Compares the original app version from the App Transaction against a target version to determine if the user is entitled to features from an earlier business model.

This is a utility method that performs the version comparison natively, which can be more reliable than JavaScript-based comparison for semantic versioning.

Use Case: Check if the user's original download version is older than a specific version to determine if they should be grandfathered into free features.

Param	Type	Description
`options`	`{ targetVersion: string; }`	- The comparison options

Returns: Promise<{ isOlderVersion: boolean; originalAppVersion: string; }>

Since: 7.16.0

purchaseProduct(...)

purchaseProduct(options: { productIdentifier: string; planIdentifier?: string; productType?: PURCHASE_TYPE; quantity?: number; appAccountToken?: string; isConsumable?: boolean; autoAcknowledgePurchases?: boolean; }) => Promise<Transaction>

Started purchase process for the given product.

Param	Type	Description
`options`	`{ productIdentifier: string; planIdentifier?: string; productType?: PURCHASE_TYPE; quantity?: number; appAccountToken?: string; isConsumable?: boolean; autoAcknowledgePurchases?: boolean; }`	- The product to purchase

Returns: Promise<Transaction>

getProducts(...)

getProducts(options: { productIdentifiers: string[]; productType?: PURCHASE_TYPE; }) => Promise<{ products: Product[]; }>

Gets the product info associated with a list of product identifiers.

Param	Type	Description
`options`	`{ productIdentifiers: string[]; productType?: PURCHASE_TYPE; }`	- The product identifiers you wish to retrieve information for

Returns: Promise<{ products: Product[]; }>

getProduct(...)

getProduct(options: { productIdentifier: string; productType?: PURCHASE_TYPE; }) => Promise<{ product: Product; }>

Gets the product info for a single product identifier.

Param	Type	Description
`options`	`{ productIdentifier: string; productType?: PURCHASE_TYPE; }`	- The product identifier you wish to retrieve information for

Returns: Promise<{ product: Product; }>

isBillingSupported()

isBillingSupported() => Promise<{ isBillingSupported: boolean; }>

Check if billing is supported for the current device.

Returns: Promise<{ isBillingSupported: boolean; }>

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version

Returns: Promise<{ version: string; }>

getPurchases(...)

getPurchases(options?: { productType?: PURCHASE_TYPE | undefined; appAccountToken?: string | undefined; } | undefined) => Promise<{ purchases: Transaction[]; }>

Gets all the user's purchases (both in-app purchases and subscriptions). This method queries the platform's purchase history for the current user.

Param	Type	Description
`options`	`{ productType?: PURCHASE_TYPE; appAccountToken?: string; }`	- Optional parameters for filtering purchases

Returns: Promise<{ purchases: Transaction[]; }>

Since: 7.2.0

manageSubscriptions()

manageSubscriptions() => Promise<void>

Opens the platform's native subscription management page. This allows users to view, modify, or cancel their subscriptions.

iOS: Opens the App Store subscription management page for the current app
Android: Opens the Google Play subscription management page

Since: 7.10.0

acknowledgePurchase(...)

acknowledgePurchase(options: { purchaseToken: string; }) => Promise<void>

Manually acknowledge/finish a purchase transaction.

This method is only needed when you set autoAcknowledgePurchases: false in purchaseProduct().

Platform Behavior:

Android: Acknowledges the purchase with Google Play. Must be called within 3 days or the purchase will be refunded.
iOS: Finishes the transaction with StoreKit 2. Unfinished transactions remain in the queue and may block future purchases.

Acknowledgment Options:

1. Client-side (this method): Call from your app after validation

await NativePurchases.acknowledgePurchase({
  purchaseToken: transaction.purchaseToken  // Android: purchaseToken, iOS: transactionId
});

2. Server-side (Android only, recommended for security): Use Google Play Developer API v3

Endpoint: POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge
Requires OAuth 2.0 authentication with appropriate scopes
See: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products/acknowledge
For subscriptions: Use /purchases/subscriptions/{subscriptionId}/tokens/{token}:acknowledge instead
Note: iOS has no server-side finish API

When to use manual acknowledgment:

Server-side validation: Verify the purchase with your backend before acknowledging
Entitlement delivery: Ensure user receives content/features before acknowledging
Multi-step workflows: Complete all steps before final acknowledgment
Security: Prevent client-side manipulation by handling acknowledgment server-side (Android only)

Param	Type	Description
`options`	`{ purchaseToken: string; }`	- The purchase to acknowledge

Since: 7.14.0

addListener('transactionUpdated', ...)

addListener(eventName: 'transactionUpdated', listenerFunc: (transaction: Transaction) => void) => Promise<PluginListenerHandle>

Listen for StoreKit transaction updates delivered by Apple's Transaction.updates. Fires on app launch if there are unfinished transactions, and for any updates afterward. iOS only.

Param	Type
`eventName`	`'transactionUpdated'`
`listenerFunc`	`(transaction: Transaction) => void`

Returns: Promise<PluginListenerHandle>

addListener('transactionVerificationFailed', ...)

addListener(eventName: 'transactionVerificationFailed', listenerFunc: (payload: TransactionVerificationFailedEvent) => void) => Promise<PluginListenerHandle>

Listen for StoreKit transaction verification failures delivered by Apple's Transaction.updates. Fires when the verification result is unverified. iOS only.

Param	Type
`eventName`	`'transactionVerificationFailed'`
`listenerFunc`	`(payload: TransactionVerificationFailedEvent) => void`