Skip to main content
Capgo logo
Back to plugins
@capgo/native-purchases
Tutorial
by github.com/Cap-go

Native Purchases

Implement native in-app purchases, subscriptions, and iOS StoreKit commitment billing plans with a simple API

Downloads/week

155.5k

GitHub Stars

42

Guide

Tutorial on Native Purchases

Using @capgo/native-purchases

In-app Subscriptions Made Easy.

Install

bun add @capgo/native-purchases
bunx cap sync

What This Plugin Exposes

  • restorePurchases - Restores a user's previous and links their appUserIDs to any user's also using those .
  • getAppTransaction - Gets the App Transaction information, which provides details about when the user originally downloaded or purchased the app.
  • isEntitledToOldBusinessModel - 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.
  • getProducts - Loads store product metadata, including supported iOS subscription pricing terms.
  • purchaseProduct - Starts the purchase process for the selected product and billing plan.

Example Usage

restorePurchases

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

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

await NativePurchases.restorePurchases();

getAppTransaction

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

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

const { appTransaction } = await NativePurchases.getAppTransaction();

// Check if user downloaded before version 2.0.0 (when subscription was added)
if (compareVersions(appTransaction.originalAppVersion, '2.0.0') < 0) {
  // User gets free access - they downloaded before subscriptions
  grantFreeAccess();
}

isEntitledToOldBusinessModel

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.

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

// Check if user downloaded before version 2.0.0/build 42 (when subscription was added)
const result = await NativePurchases.isEntitledToOldBusinessModel({
  targetVersion: '2.0.0',
  targetBuildNumber: '42'
});

if (result.isOlderVersion) {
  console.log(`User downloaded v${result.originalAppVersion}, granting free access`);
  grantFreeAccess();
}

purchaseProduct

Start the purchase process for the given product. For Android subscriptions, pass the Google Play base plan ID as planIdentifier. For supported iOS subscriptions that offer monthly billing with a 12-month commitment, pass billingPlanType: 'monthly'.

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

await NativePurchases.purchaseProduct({
  productIdentifier: 'com.example.premium.monthly',
  planIdentifier: 'monthly-plan',
  productType: PURCHASE_TYPE.SUBS,
});

iOS monthly commitment subscriptions

On supported iOS versions, StoreKit can expose a monthly billing plan with a 12-month commitment through pricingTerms. Show these terms on your paywall before purchase:

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

const { products } = await NativePurchases.getProducts({
  productIdentifiers: ['com.example.premium.yearly'],
  productType: PURCHASE_TYPE.SUBS,
});

const yearlyProduct = products.find(
  (product) => product.identifier === 'com.example.premium.yearly',
);
const monthlyCommitment = yearlyProduct?.pricingTerms?.find(
  (term) => term.billingPlanType === 'monthly',
);

if (yearlyProduct && monthlyCommitment) {
  console.log('Monthly price:', monthlyCommitment.billingDisplayPrice);
  console.log('Total commitment:', monthlyCommitment.commitmentInfo?.priceString);

  const transaction = await NativePurchases.purchaseProduct({
    productIdentifier: yearlyProduct.identifier,
    productType: PURCHASE_TYPE.SUBS,
    billingPlanType: 'monthly',
  });

  console.log('Billing plan:', transaction.billingPlanType);
  console.log('Commitment ends:', transaction.commitmentInfo?.expirationDate);
}

Full Reference