Updated support for multiple prices per Stripe product
RevenueCat has updated its Stripe Billing integration to support multi-price Stripe products. Learn how to migrate an existing Stripe config to the new model.
RevenueCat is changing how Stripe Billing catalogs map into RevenueCat. Instead of creating one Product for each Stripe product, RevenueCat can now create one Product for each Stripe price. This guide explains what changes, what you gain, and how to migrate an existing Stripe configuration. Expect to re-import your catalog, and to review anything downstream that reads product identifiers.
Multiple-price support is rolling out to Stripe Billing configurations gradually, and may not be available in your account yet. When it is, the Stripe configuration is marked Update available in your dashboard. Contact your Account Manager or our support team for more details.
What's changing
Stripe and RevenueCat both use the word "product" for different things. This guide refers to the following:
| Term | What it refers to |
|---|---|
Stripe product (prod_...) | An item in your Stripe catalog. A Stripe product can carry many prices. |
Stripe price (price_...) | A specific amount and billing interval belonging to a Stripe product. |
| RevenueCat Product | The catalog entry you map to Entitlements and add to Packages in RevenueCat. |
Previously, a RevenueCat Product mapped to a single Stripe product, and you chose a single price to use when importing. Every other price on that Stripe product was unusable in RevenueCat purchase flows (couldn't be presented in paywalls, etc.)
The new model changes the granularity of that mapping:
| Previous model | New model | |
|---|---|---|
| RevenueCat products | One product per Stripe product | One product per Stripe price |
| Product identifier | The Stripe product ID (prod_...) | The Stripe price ID (price_...) |
| Choosing a single price at import | Required | Not applicable |
Products you have already imported are not updated automatically. They keep working exactly as they do today, and both models can coexist in the same RevenueCat project until you re-import.
What the new model enables
- Full use of multi-price Stripe products. Monthly and annual, regional and currency variants, and grandfathered price points can all be sold through RevenueCat at the same time.
- Maintain your Stripe product catalog structure. You no longer need to split one Stripe product into several just to satisfy RevenueCat's one-price-per-product limit. This matters most if you already sell through Stripe and are adding RevenueCat on top of an established catalog.
- Granular entitlement mapping. Every price gets its own Product, so each one carries its own Entitlements and sits in its own Package. You can give an annual price a different Entitlement than the monthly price on the same Stripe product.
- Reporting at the price level. Charts, Scheduled Data Exports, and webhook payloads distinguish two prices on the same Stripe product instead of collapsing them together.
What changes in your integration
Product identifiers
Products created under the new model use the Stripe price ID as their product identifier. A Product that would previously have been identified as prod_ABC is now identified as price_123. This identifier is what appears in the Product Catalog, in the SDK, in Charts, and in Scheduled Data Exports.
Display names
On import, RevenueCat appends the price point and billing interval to the display name, for example US$9.99 monthly. Without this, several Products imported from the same Stripe product would be indistinguishable in the dashboard.
Importing
You no longer select a price when importing a Stripe product. Every active price on the product is available to import, and each one you select becomes its own Product.
Webhooks and integrations
The product_id field in webhook and integration payloads continues to carry the Stripe product ID (prod_...). This is an existing public API contract and is deliberately unchanged, so payload consumers that key on product_id keep working.
To identify which price a transaction is for, use the price_id field. On product change events, new_price_id carries the price being changed to. Because both prices on a product change can belong to the same Stripe product, product_id and the old product ID may be identical on those events — price_id and new_price_id are what tell them apart. See Event Types and Fields for the full payload reference.
Downstream data consumption that relies on product identifiers
If your integrations, export consumers, entitlement mappings, or internal tooling assume a Stripe product identifier begins with prod_, update them before you migrate. This is the most likely source of issues.
How to migrate an existing Stripe config
Multiple-price support is enabled per Stripe Billing configuration, not per project and not per product. You run the update yourself from the dashboard: a guided update on the configuration imports your price-based Products, then switches purchase tracking over to them.
Prerequisites
- A connected Stripe account. See Stripe Billing for connection setup.
- Supported pricing models in Stripe. Multiple-price support doesn't change which models RevenueCat can sell — see pricing model compatibility.
How the update is structured
The wizard has five steps. Two of them can't be undone:
| Step | What it does | Can it be undone? |
|---|---|---|
| 1. Overview | Explains the change and what to expect. Nothing is created or moved yet. | Nothing to undo. |
| 2. Import products | Creates one RevenueCat Product per Stripe price you select. | No. Product imports for the configuration are price-based from then on. |
| 3. Attach Entitlements | Maps the new Products to the Entitlements Customers get when they buy them. | Yes. It's also skippable, and you can change the mapping later. |
| 4. Start tracking purchases | Assigns new purchases from those prices to the new Products. | No. |
| 5. Done | Confirms tracking is on and the new Products are ready to sell. | Nothing to undo. |
You can leave the wizard after step 2 and come back later. In that state nothing changes for your Customers: the new Products sit at Not tracked, and purchases continue to be tracked on your existing Products for as long as you need.
Open the update
- Go to Project settings → Web. Stripe configurations where the update is available are marked Update available.
- Select the configuration you want to update. A banner at the top of the configuration page reads Update available for this config.
- Click Review update to open the Update Stripe integration wizard.
The wizard runs on one configuration at a time. If your project has several Stripe configurations, repeat the update for each one.
Step 1: Overview
The first step explains the change and sets expectations for the rest of the update:
- Your existing Products stay as they are.
- Existing subscriptions don't change, and stay attributed to your current Products.
- Nothing is tracked on the new Products until you explicitly start tracking in step 4.
Click Get started to continue, or Not now to close the wizard without changing anything.
Step 2: Import products
Select the Stripe prices to import as RevenueCat Products. Each Stripe product in the list expands to show its individual prices, and every price you select becomes its own Product. You can also add a free trial to a price as you import it.
Usage-based (metered) prices can't be imported. See pricing model compatibility for the models RevenueCat supports.
Click Import n products to finish the step. The new Products appear in your Product Catalog identified by their Stripe price ID, with a Not tracked status. You can import more prices later from the Product Catalog.
Step 3: Attach Entitlements
Each new Product inherits the Entitlements of the Stripe product it came from, so Customers who purchase one get the same level of access as before. Review the mapping, and use Choose entitlement to assign any Product listed under No entitlement.
Attaching Entitlements changes nothing for existing subscribers. It defines what access Customers get when they purchase one of the new Products, which is why it comes before tracking starts.
This step is reversible and can be skipped with Skip for now, but anything you skip here is flagged again in step 4. See Entitlements for how Entitlements map to Products.
Step 4: Start tracking purchases
This is the step that moves purchases onto the new Products. Before you confirm, the wizard runs a setup check against the live state of the configuration:
- Products imported — how many price-based Products exist.
- Entitlements attached — which Entitlements cover them, and how many Products are still missing one.
- Offerings — imported Products that aren't in any Offering. This is optional: they're still tracked, but they can't be purchased through RevenueCat flows until you add them to an Offering.
Nothing hard-blocks this step. If Products are missing Entitlements, the setup check warns you and asks you to acknowledge that Customers who purchase those Products won't receive any Entitlement.
Click Start tracking purchases and confirm in the dialog. From that point on:
- New purchases from those Stripe prices, and their subsequent renewals, are assigned to the new Products.
- Subscriptions that already exist stay on your current Products, renewals included. They never move.
- Entitlement and project-level metrics, including MRR and active subscriptions, are unaffected.
- Charts, integrations, and webhooks filtered by product identifier show the new Product association.
If you aren't ready, click I'll do this later to leave the configuration in the resumable state.
Step 5: Done
The final step confirms that tracking is enabled and that the new Products are available to use in Paywalls and purchase flows. Purchase volume on the new Products takes a few days to settle.
Verify a purchase end to end before opening the flow to customers, and confirm your downstream consumers handle the price_id field and the new identifier shape.
Resume an unfinished update
A configuration that has imported price-based Products but hasn't started tracking shows a Finish updating this configuration banner. Click Continue update to reopen the wizard at step 4. This banner can't be dismissed while the update is unfinished.
Once a configuration uses multiple-price support, its catalog syncing becomes price-based. Products imported under the previous model no longer receive price changes, renames, or archival from Stripe, and no error is surfaced. Import a price-based Product for everything you still sell.
Edge cases and impact to consider
Customers can purchase a Product that grants no access
A Product with no Entitlement grants no access. If you skip step 3 and start tracking anyway, Customers who purchase one of those Products pay and receive nothing. This is the single most likely thing to generate a support ticket during a migration.
Existing subscriptions aren't affected. A subscription that was purchased before you enabled tracking stays on its original Product for its entire lifetime, including every renewal, and the Entitlements that Product grants continue to apply. Only new purchases are assigned to the price-based Products.
Historical reporting splits across two identifiers
Charts and Scheduled Data Exports treat the old Product and the new price-based Products as unrelated products. Nothing aggregates them back together, and because pre-migration subscriptions keep renewing under the old identifier, the split doesn't close on a fixed date — the old Product keeps producing revenue for as long as those subscriptions live.
Any Chart, export, or query grouped by product identifier will show one commercial product under two or more identifiers. Update your saved reports to group the old and new identifiers together yourself. For exports specifically, see how Stripe identifiers appear in exports, which covers resolving a price ID back to its parent Stripe product.
Purchases for prices you didn't import
If a purchase arrives for a Stripe price that was never imported, RevenueCat creates a price-based Product for it automatically. The Product enters your catalog with no Entitlements attached, so the purchase grants no access until you map it.
Watch your catalog for Products you didn't import after enabling tracking. Every Stripe price a Customer can reach should have a Product with the right Entitlements, whether you imported it or not.
Product change events
When a subscription on a price-based Product moves to a different price — an upgrade from monthly to annual, for example — RevenueCat re-attributes it to the Product for the new price at the moment the change takes effect, and sends a product change event.
If both prices belong to the same Stripe product, product_id is identical on either side of the change. Use price_id and new_price_id to tell them apart.
Multiple currencies on one price
A Stripe price that carries several currency options imports as a single Product. The Customer is presented with the right currency at checkout based on their locale, so you don't need a separate Product, Package, or Offering per currency.
What doesn't change
Migrating doesn't affect your Stripe checkout experience, your customers' billing dates, or the amounts they're charged. It changes how RevenueCat represents your catalog internally, not what Stripe does. The Stripe feature limitations documented on the Stripe Billing page, including the supported pricing models, are unchanged.
Related
- Stripe Billing — connecting your Stripe account, importing products, and creating Offerings.
- Event Types and Fields — the full webhook payload reference, including
price_id. - Scheduled Data Exports — the export schema that carries product identifiers.