Catalog Management

Catalog Management

Manage the Android product catalog across two surfaces: the Google Play Console (source of truth for products) and the RevenueCat dashboard (entitlements, offerings, targeting). You do not call the Google Play Developer monetization.subscriptions or monetization.onetimeproducts endpoints from your app or backend.

Phase 1: Understand

Read this phase before you touch anything.

Why two surfaces

Play Console holds the billable SKU. RevenueCat decides which SKU gets surfaced to which user and under which entitlement key.

What changes without an app update

When your app calls awaitOfferings(), it fetches whatever the RevenueCat dashboard has configured. Offering edits, package swaps, and targeting rules propagate on the next app launch. No binary release is required.

When to use the REST API

If you need to automate catalog edits from a backend (for example, seeding dozens of offerings across environments), use the RevenueCat REST API for products, entitlements, and offerings. You still do not talk to Google directly. Play Console remains the product source of truth.

Phase 2: Plan

Before you make a change, decide:

1. Is this a new product, or a repackaging of an existing one?
   • New product: start in Play Console.
   • Repackaging (new offering, new targeting, new entitlement mapping): stay in RevenueCat.
2. Which entitlement does the product unlock? If you do not have a matching entitlement, create one first.
3. Which offering and package identifier? Decide the package identifier (for example $rc_monthly, $rc_annual) so your paywall code keeps working.
4. Does targeting need to change? If different users should see different offerings, plan the placement name and the targeting rule (country, app version, platform, custom attribute).

Phase 3: Execute

The end to end flow for adding a new subscription product.

Step 1: Add the product in the Play Console

1. Open Play Console -> your app -> Monetize -> Products -> Subscriptions.
2. Click Create subscription.
3. Set the product ID (for example premium_monthly), name, and description.
4. Add a base plan (billing period, renewal type, price).
5. Optionally add offers (intro pricing, free trial).
6. Activate the subscription.

Wait a few minutes for Play to propagate the product.

Step 2: Import into RevenueCat and attach an entitlement

1. Open the RevenueCat dashboard -> your project -> Products.
2. Click Import to sync from the Play Console. The new product appears in the list.
3. Open the product and attach it to an existing entitlement, or create a new one.
   • Entitlement example: pro. Every product that unlocks pro features attaches to pro.

Your client code checks entitlements by key:

kotlinCopy code
val isPro = customerInfo.entitlements["pro"]?.isActive == true

Step 3: Wire the product into an Offering as a Package

1. In the dashboard, open Offerings.
2. Pick the offering you want to edit, or create a new one (for example default).
3. Add a Package. Choose a package identifier that matches your paywall:
   • $rc_monthly for monthly
   • $rc_annual for annual
   • Or a custom identifier
4. Attach the Play Console product to the package.
5. Save. Make it the Default offering if it should be the default (the SDK returns it as offerings.current).

Your client code stays the same:

kotlinCopy code
val offerings = Purchases.sharedInstance.awaitOfferings()
val monthly = offerings.current?.monthly

Step 4 (optional): Targeting

If different users should see different offerings, use placements.

1. In the dashboard, open Targeting -> Placements.
2. Create a placement (for example paywall_upsell).
3. Add rules (country, app version, platform, custom attribute) that map users to specific offerings.

Client code:

kotlinCopy code
val offering = offerings.getCurrentOfferingForPlacement("paywall_upsell")
    ?: offerings.current

No app update is required when you change targeting rules later.

Phase 4: Verify

Check the change landed before you close the task.

If awaitOfferings() returns null for a package you expect, the most common causes are: the offering is not the Default offering, the product is not attached to the package, or Play has not finished propagating the product. If no configured product resolves from Play at all, awaitOfferings() throws PurchasesException with PurchasesErrorCode.ConfigurationError. Check the product IDs, that the base plan is active, and that Play has propagated the product.

Common Mistakes

• Calling monetization.subscriptions from your backend. Use RevenueCat instead.
• Creating an offering before importing the product. Import first, then wire.
• Shipping hard coded product IDs in your paywall UI. Use package identifiers so you can swap products without an app release.
• Forgetting to make an offering the Default offering. Clients that call offerings.current will see the old offering until you flip this.

References

• Full chapter