Purchases

Every project has a purchases module. It holds one catalog of what the app sells — subscriptions, one-time products, packs of credits — sold in the App Store, on Google Play and on the web through the environment's own Stripe account. And it gives one answer to "what does this customer have", whatever store they bought in: a Pro bought on the web is Pro in the iOS app.

Apps buy with each store's own machinery — StoreKit on iOS, Play Billing on Android, Stripe Checkout on the web — through Palbase's SDKs. Palbase verifies every purchase with the store, keeps it in the project's ledger, and keeps each customer's entitlements, credits and quotas current: in the apps, live, and on your server, by a read or an event.

Quick example

The app hears what the signed-in customer has, and sends them to buy on the web:

// app/pro.ts
import { createClient } from "palbase/web";

const pb = createClient({ url: "https://<ref>.palbase.studio", publishableKey: "pb_<ref>_c…" });

// Told now, and again whenever it changes: a purchase in any store, a renewal, a refund.
pb.purchases.onCustomerInfo((info) => {
  const pro = info?.entitlements["pro"]?.active === true;
  document.body.classList.toggle("pro", pro);
});

export async function buyYearly(): Promise<void> {
  const url = await pb.purchases.checkout({
    product: "pro",
    plan: "yearly",
    successUrl: "https://app.example.com/thanks",
    cancelUrl: "https://app.example.com/pricing",
  });
  location.assign(url); // Stripe Checkout
}

The server checks the entitlement where the content is served, with the secret key:

// server/pro.ts
import { createServer, isEntitled } from "palbase/server";

const palbase = createServer({ url: process.env.PALBASE_URL!, secretKey: process.env.PALBASE_SECRET_KEY! });

export async function isPro(userId: string): Promise<boolean> {
  // A user who has bought nothing reads as a customer with nothing.
  const { data } = await palbase.purchases.getCustomer({ path: { customer_id: userId } });
  return isEntitled(data, "pro");
}

The parts

The stores

Each environment connects its own stores: staging can sell through Stripe's test mode while production takes live payments.

How a purchase becomes access

1. The app buys, naming the customer to the store: StoreKit with the customer's appAccountToken, Play Billing with their obfuscated account id, Checkout with the customer's session. The SDKs do this; nothing personal goes to Apple or Google.
2. The purchase reaches Palbase. The iOS and Android apps report what the store gave them; Stripe reports its own. Nothing is taken on the device's word: an App Store transaction is checked against Apple's signature and the subscription read from Apple with the environment's key, a Play purchase is read from Play by its token, a Stripe object is read again from Stripe.
3. The ledger applies it, and the customer's entitlements, credits and quotas follow. A Google Play purchase is acknowledged once the ledger has it — the SDK never does.
4. Everyone hears it. The customer's apps are told at once (each customer has a realtime channel of their own, purchases:<ref>:<user id>, read-only), and your backend receives purchases.* events.
5. The stores keep it current. Apple's App Store Server Notifications, Google Play's real-time developer notifications and Stripe's events bring renewals, cancellations, billing issues and refunds into the ledger, with the app closed.

An entitlement already on from one store is not sold again in another: the iOS and Android SDKs answer alreadyEntitled without opening the store, and a web checkout is refused (409 already_entitled), naming the store it is managed in. A free trial is given once per customer, across every channel.

Who calls what

In a palbase/backend app the module is Palbase.purchases; from any other server it is createServer({ url, secretKey }).purchases — the same client, generated from the purchases contract, one method per operation (GET /purchases/customers/{customer_id} is getCustomer).

Test purchases

Purchases nobody pays for are test purchases: the App Store's sandbox (where TestFlight and App Review buy), Xcode's StoreKit Testing, Google Play's license testers and Stripe's test mode. Each is marked is_sandbox — in what the customer has and in the purchase events — and the environment's settings say whether they open entitlements: for everyone (the default), only for customers on an allowlist, or for nobody. App Review buys in the sandbox: on the environment a build in review uses, a test purchase that opens nothing gets the app rejected. See Customers.

Test the iOS side end to end with Test Apple Purchases.

Setting up, in order

1. Write the catalog — in Studio, Purchases › Catalog, or as a file with palbase purchases:catalog:put. Catalog
2. Connect the stores you sell in — the App Store, Google Play, Stripe.
3. Bring the stores to the catalog — plan it, read what each store will get, and confirm: palbase purchases:catalog:plan, then palbase purchases:catalog:confirm. Palbase creates the products and prices in each store.
4. Buy from the apps — iOS, Android, the web.
5. Check access where the content is served — Entitlements, Credits & Limits.
6. When the app needs them: paywalls designed in Studio, offers and coupons, and charts of what sold.

In Studio

Each environment's Purchases has these screens:

The CLI

The purchases commands cover the catalog, the stores' connections, paywalls, placements, experiments, charts and customers; the stores commands connect the App Store Connect and Google Play accounts the catalog is written with. Every one is in the CLI reference.

Related

• Catalog · App Store · Google Play · Connect Stripe · Web
• Paywalls · Offers & Coupons
• Entitlements, Credits & Limits · Customers · Charts
• Test Apple Purchases