> ## Documentation Index
> Fetch the complete documentation index at: https://bilt.me/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# In-app Payments
> Sell subscriptions inside your app — catalog, entitlements, and receipt verification handled by Bilt
Bilt's **Payments** feature lets your app sell subscriptions through the App Store without you building a billing backend. You define products in Bilt, ask the chat for a paywall, and Bilt verifies the purchases and tells your app what the user is entitled to.
## What it is
Payments is a managed in-app purchase backend for your project. It creates the subscription products in App Store Connect, verifies every purchase server-side, keeps subscription state current from Apple's notifications, and exposes the result to your app as **entitlements** — named permissions like `pro` that your screens check.
Open it from the **Payments** tab next to Preview and Database in your project, or from **Settings → Payments**.
iOS is supported end to end today. Google Play support is in progress — the catalog and entitlement model are already platform-neutral, so apps built now won't need rewriting.
## Before you start
Payments builds on your App Store Connect setup. You need all three of these before the Payments tab unlocks:
| Requirement | Where it comes from |
| ------------------------- | ---------------------------------------------------- |
| Bundle ID | [Publish to App Store](/docs/guides/publish-to-app-store) |
| App Store App ID | [Publish to App Store](/docs/guides/publish-to-app-store) |
| App Store Connect API key | [Publish to App Store](/docs/guides/publish-to-app-store) |
If any are missing, the tab shows what's left and links straight to the setup. You also need to complete **tax and banking details** in App Store Connect — Apple won't sell anything until those are filled in.
Selling digital content in an app comes with store rules about *how* you may take the money. Read [In-app purchase rules](/docs/guides/in-app-purchases) before you build a paywall — using the wrong payment path is a common first-submission rejection.
## Set it up
Open the **Payments** tab. Bilt shows the bundle ID and Apple App ID it will use, and one **Enable payments** button registers your app with the billing service.
A banner in the Catalog gives you a URL and a link to the **Distribution Info** page in App Store Connect. Set both the Production and Sandbox Server URL to that address. Without it, renewals, cancellations and refunds never reach Bilt, so entitlements go stale.
In **Catalog**, choose **Add Product** and fill in a title, billing period (monthly or annual), price and an optional description. Prices come from Apple's fixed price points; finer pricing and other currencies can be set later in App Store Connect.
The **Product ID** is generated from your bundle ID and the product title, and **can't be changed after saving** — pick the title carefully.
**Save Changes** creates or updates the subscriptions in App Store Connect and publishes the product-to-entitlement mapping to Bilt's billing backend. Subscriptions that already exist in App Store Connect appear under **Products found from App Store Connect** with a **Sync** button to pull each one into your catalog.
Prompt for it like any other feature:
> Add a paywall screen offering the Pro monthly subscription, and hide the export button unless the user has the `pro` entitlement.
Bilt already knows your catalog — product IDs and entitlement codes are passed to the agent — and wires the app to the `@biltme/iap` client.
## Entitlements
Each product maps to an entitlement code derived from its title: **Pro** becomes `pro`, **No Ads** becomes `no_ads`.
Your app checks the entitlement, never the product. That means you can rename a product, add an annual plan, or run a promotion without touching app code, and a user who bought any product granting `pro` keeps access.
## Testing before you ship
Previews and development builds run against a **mock** billing environment. Purchase, restore and entitlement gating all work — through the same backend logic as production — without a sandbox Apple Account or a real charge.
Real StoreKit purchases need a native build (TestFlight or a development build); Expo Go can't load the in-app purchase module.
## What Bilt handles
* **Server-side receipt verification** — purchase tokens are checked against Apple's certificates on Bilt's servers, not trusted from the device.
* **Subscription state** — Apple's server-to-server notifications for renewals, cancellations, refunds and billing retries are ingested and projected into entitlements automatically.
* **Restore purchases** — re-reads the device's purchases *and* reconciles what the backend already knows, covering the reinstall and new-device cases reviewers test.
* **Manage subscriptions** — one call opens Apple's native subscription sheet, satisfying the in-app cancellation requirement.
* **Purchase before sign-up** — a user who buys before signing in gets an anonymous billing identity that is merged into their account afterwards.
* **Offline retry** — a purchase made on a flaky connection is queued and re-sent across app restarts, so nobody is charged without getting access.
## Looking up a customer
The **Users** tab lists the billing users of your app. Select one to see their entitlements, subscription status with expiry and auto-renew state, and recent purchases — enough to answer "I paid and it's not working" without digging through App Store Connect.
## What's still on you
* Apple Developer enrollment, tax and banking details.
* Honest paywall copy: price, period, auto-renewal wording, and links to your terms and privacy policy.
* Submitting the products for review alongside your build.
What Apple and Google require when your app sells digital content
The bundle ID, App ID and API key setup that Payments builds on