RevenueCat setup

Only apps that sell something need this. When they do, payments are where launches stall: a legal form nobody signed, a product one field short of complete, a key that was never uploaded, a paywall missing a link. The work itself is small; the order matters, and half the steps are the owner's.

references/revenuecat-reference.md is the full, sourced reference (checked October 2026): the ordered checklist with who can do each step, every Apple and RevenueCat API call with request shapes, the working implementation from an existing app, testing, the failure table, and App Review's paywall rules. Its "unverified" marks are honest: the API route for submitting products was read from the spec, not run. This file is the route through it.

0. Decide, with the owner, before creating anything

Product IDs can never be reused once created, even after deletion, and Family Sharing cannot be turned off once on. So get one short confirmation first:

• What is sold: monthly and yearly subscription, a lifetime unlock, or both. One entitlement (say pro) unless there is a real reason for tiers.
• Product IDs, as a scheme that leaves room: <bundle>.pro.monthly, <bundle>.pro.yearly, <bundle>.pro.lifetime.
• Prices in USD (Apple derives the other countries), and whether there is a free trial.
• Who is entitled when one person pays: only them, or their household or team (a server decision, see section 9 of the reference).

Propose all of this yourself from the ASO research (what rivals charge is in the competitor table); the owner only has to say yes or change a number.

1. Start the owner's steps on day one

These have waiting time measured in days, and nothing paid works until they are done, not even in a test build:

Assume none of them is done unless the owner profile or a check says so (../app-launch/references/owner-inputs.md), and ask in the day-one message of the launch. Keys are handed over by the owner uploading them on the site that needs them; they are not pasted into chat or copied by an agent.

Later, once a test build exists, two more owner steps: a sandbox Apple account on a registered iPhone to test with, and one screenshot of the paywall for the products' review screenshot.

Paths such as ../app-store-connect/scripts/asc.mjs are relative to this skill's folder; run commands from the app's repository root with the script's absolute path.

2. Build against the Test Store while Apple catches up

A new RevenueCat project comes with a Test Store: products, offerings and purchases that work at once, with no Apple setup. It replaces the StoreKit configuration file, which needs Xcode. So the paywall can be built and tried on the same day:

1. Create the project and the iOS app (bundle ID exact, case-sensitive), Test Store products, the entitlement, an offering marked current, packages ($rc_monthly, $rc_annual, $rc_lifetime), and attach products to both the entitlement and the packages. All through the REST API v2 or the MCP server (section 7 of the reference has the calls; create bodies take lookup_key).
2. Add the code: npx expo install react-native-purchases react-native-purchases-ui expo-dev-client. No config plugin is needed. Follow the reference implementation (section 2): configure the SDK when the signed-in user is known and with the server's user id, never call logOut() when accounts are mandatory, present the RevenueCat paywall, and treat the server as the source of truth with the SDK as a change signal.
3. Keys per build profile: the Test Store key only in the development profile; the real appl_ key in every profile that reaches TestFlight or the store. The SDK deliberately crashes a release build that carries the Test Store key, so check the EAS environment of each profile.
4. Purchases do not run in Expo Go. A development build on a real iPhone is needed, which means a registered device: an owner step.

3. Real products in App Store Connect

Through the API (section 3 of the reference): subscription group and its localization, each subscription with its localizations (display name and description), availability, prices, the optional introductory offer, billing grace period on. Each product must end in READY_TO_SUBMIT.

The piece that is always left for last is the review screenshot: a capture of the paywall, required per product, which cannot exist until the paywall renders. A product without it stays in "Missing Metadata". Ask the owner for one screenshot of the paywall from the test build, then upload it.

Then register the App Store products in RevenueCat, attach them to the same entitlement and packages, and set Apple's server notifications to RevenueCat's URL (settable through Apple's API).

4. The paywall App Review will accept

RevenueCat's paywall editor gives the layout and the localized prices. It does not add the things reviewers reject for; those are placed by you:

• the plan's name, its length in words, and the full price actually billed, as the largest price on screen;
• what the user gets;
• a Restore purchases button;
• working links to Terms of Use and Privacy Policy, on the paywall;
• a visible close button, with no delay;
• for a trial: its length and the price after it, shown only to eligible users, and never as a toggle.

And in the listing: the privacy policy URL, the Terms link in every localized description (Apple's standard EULA link if there is no custom one), and a sentence saying which features need the purchase. Section 10 of the reference has the wording of the rules and what has been rejected.

5. Test for real

The Test Store proves the code; only Apple's sandbox proves the configuration. Before any submission, on a TestFlight build with the appl_ key: the offering loads with Apple's prices, a purchase unlocks the entitlement, the app still has it after a restart, restore works on a second install, the server received the webhook. Sandbox purchases show in RevenueCat only with "View Sandbox Data" on. This needs the owner's phone and a sandbox Apple account; say exactly what to tap and what should happen.

If the offering is empty, go down the list in section 9 of the reference in order. The top causes are the agreement, banking or tax not Active, a product missing a price or localization, and the wrong key in the build.

6. Submit the products with the app

The first product of each type must go to review together with an app version, and a new subscription together with its group. Miss this and the app can be approved with a paywall that sells nothing.

• In the web interface: each product > Add for Review > choose the version. This is a browser task (../app-launch/references/computer-use.md), and the final "Submit" stays with the owner.
• Through the API (version 4.4.1 and later) products can be added as items of the same review submission as the version; this route is unverified. If you use it, read the submission's items back before telling the owner it is ready.

In the review notes say where the paywall is, which features it unlocks, and the product IDs. After approval, RevenueCat advises about a day before relying on the products in production.

Variants

• One-time purchase only (a lifetime unlock): no subscription group, no renewal handling, no trial. Still needs the agreement, the key, restore, and submission with the first version. Section 12.1.
• Paid upfront, nothing to buy inside: no RevenueCat at all. The Paid Apps Agreement, bank and tax, and a price (../app-store-connect/scripts/asc.mjs price 4.99). Section 12.2.

What to report

What exists now on each side (Apple products and their states, RevenueCat objects), what was tested and how, and what was not: a paywall no one has bought from in sandbox is untested, and the owner should hear that in those words.