Mobile purchase claims

Tie an App Store or Google Play purchase to the person who made it, and to the account it should fund. Allow about fifteen minutes.

A store purchase carries no browser session and no metadata field you can fill. It carries one UUID. The SDK mints that UUID, records what it stands for, and hands it to the store. When the store notifies FounderHQ, the UUID leads back to the buyer.

const prepared = await founderhq.preparePurchase({ source: "app_store" });

await founderhq.observePurchase({
  prepared,
  purchase: {
    source: "app_store",
    transactionId: transaction.id,
    originalTransactionId: transaction.originalID,
  },
});

const result = await founderhq.purchaseWithRevenueCat(() =>
  Purchases.purchasePackage(pkg),
);

await founderhq.claimSubscription({
  purchase: {
    source: "app_store",
    transactionId: transaction.id,
    originalTransactionId: transaction.originalID,
  },
  confirmation: "move_future_revenue",
});

A purchase the app did not prepare

With Revenue owner set to Organization, a store purchase without a prepared context has no account of its own. FounderHQ uses the buyer's accounts, as for a web payment:

• A buyer in exactly one account pays for that account.
• A buyer in several accounts, or in none, pays as a contact.
• A buyer that FounderHQ does not know leaves the purchase unmatched.

Renewals keep the owner of the first payment. A purchase claim for the same purchase that arrives later moves the payment, the subscription, and its MRR to the claim's account, also when FounderHQ had chosen the buyer's one account. The reverse never happens: a purchase that a prepared context or a claim names keeps its account, whatever the buyer's accounts are later. To name the account from the start, prepare the purchase (step 1) while the account is set on the SDK. See Which account gets a payment.

The RevenueCat identity rule

If you use RevenueCat, the FounderHQ UUID is the RevenueCat App User ID. Let the SDK configure and log in RevenueCat, and never call Purchases.logOut(). See Connect RevenueCat.

The same calls on every platform

From your backend

Your server can do two things with a secret key, through the Node SDK:

• accountContextToken({ account, userId, idempotencyKey }) issues short-lived proof that this person may act for this account. It moves no money.
• claimMobileSubscription({ account, userId, purchase, confirmation, idempotencyKey }) moves a subscription's future revenue to an account, with the same "move_future_revenue" confirmation and the same rules as the mobile call.

Neither call confirms the account or the membership. Declare those with upsertAccount and accountMembership. The token is issued at once, but a claim uses it only when the account is confirmed and the person is a declared member when the claim is processed. A claim that arrives before that counts as a claim without a token.

Verify

1. Make a real purchase in the app. FounderHQ tracks live purchases only.
2. In FounderHQ, open Analytics → People and open the buyer. The purchase is on their Revenue tab.
3. After a transfer claim, the next renewal counts for the account, and the earlier payments still count for the person.

Troubleshoot

The purchase has no contact

The app purchased without preparing. Call preparePurchase first, and pass the token to the store library.

"Observed purchase source does not match its preparation"

You prepared for one store and observed another. Prepare with the same source you buy with.

A RevenueCat purchase reports no transaction

Some observer and custom-completion modes return no store transaction. The SDK will not guess from entitlements. Claim it later with a verified transaction ID or purchase token.

AI agent or LLM? Read this page as markdown