AI agents: the complete RevenueCat documentation index is available at llms.txt. A Markdown version of this page is available at this URL.

Subscriptions

Ask AI

Copied as markdown!

In addition to one-time products, subscriptions can be used to grant in-app currency on a recurring basis, such as a monthly coin pack or weekly credit refill. This model helps drive predictable revenue while encouraging long-term engagement and retention.

With RevenueCat’s in-app currency feature, you can configure subscriptions to automatically deliver currency to customers at regular intervals. These currencies, like tokens, gems, or credits, can then be spent on virtual goods or in-app experiences.

Setting up subscriptions for in-app currency requires careful configuration in each platform to ensure consistent behavior across upgrades, downgrades, and trials. This guide walks through the key setup steps and platform-specific considerations.

📘Supported Stores

RevenueCat’s subscription support for in-app currency is available for the following stores:

• App Store (Apple)
• Play Store (Google)
• Stripe
• RevenueCat Billing

This guide covers how in-app currency works with subscriptions across these stores, including how and when currency is granted during free trials and product changes.

Subscription Schedules

When using subscriptions to grant in-app currency through RevenueCat, you choose when currency is deposited per product. You can grant the full amount once per billing cycle, on purchase or renewal, or drip it on a fixed daily, weekly, or monthly schedule. For all the options and details, see Grant Cadence.

Free Trials

When using free trials with in-app currency subscriptions, RevenueCat gives you control over how much currency to grant during the trial period. You can configure a separate currency grant amount specifically for free trials in the RevenueCat dashboard. This allows you to offer a smaller set of currency during the trial to give customers a preview of what they’ll receive as a paying subscriber.

For example, if your monthly subscription grants 100 credits, you could set the trial to grant only 25 credits.

To grant currency when a trial starts, select the "Add on trial start" option and specify the amount. If left unchecked, no currency will be granted for trials by default.

When currency is granted

Trial credits are granted when the trial begins. This gives customers immediate access to currency during the trial period.

Trial credit expiration

By default, currency granted during a free trial does not expire when the trial ends, even if the customer cancels or chooses not to convert to a paid subscription. Customers will retain access to any in-app currency they received during the trial.

If you have enabled the Auto-expire at the end of billing cycle toggle on the in-app currency, trial credits will also expire when the trial period ends.

Product Changes

RevenueCat automatically manages subscription product changes and adjusts in-app currency grants accordingly. When a customer switches between subscription products (e.g: upgrades or downgrades), RevenueCat calculates the in-app currency grants to reflect the actual amount charged, factoring in any prorated refunds during the transition.

This ensures that:

• Customers receive a fair amount of in-app currency that corresponds to what they paid.
• You avoid overgranting currency when the customer did not have an effective charge.
• Balance adjustments are aligned with the billing behavior of each store.

The exact behavior depends on the platform and the type of product change (e.g: replacement modes for Play Store), but the general principle is consistent across stores.

App Store

Setup Requirements ✅

• All interchangeable subscriptions must be in the same subscription group.
  • This means that if a customer can upgrade, downgrade, or crossgrade between two products, those products must belong to the same subscription group in App Store Connect. Apple only supports transitions (e.g: proration, immediate upgrades, deferred downgrades) within a subscription group.
• Subscriptions in the same group should be configured to grant the same amount of in-app currency.
• Use subscription levels within the group to define upgrade/downgrade relationships.
  • Each subscription in a group should be assigned a level that reflects its relative position (usually based on price or feature tier). This ordering tells Apple, and by extension RevenueCat, which products are upgrades, downgrades, or crossgrades.

Product Change Behavior 🔄

RevenueCat adjusts in-app currency grants automatically based on how the App Store handles product changes. Here’s how each scenario is handled:

Product change	When customer is charged for new sub	When new sub starts	New currency grant behavior
Upgrade	Immediately, full price of new sub + prorated refund on old sub	Immediately	RevenueCat grants currency proportionally, based on the amount the customer is effectively charged after proration.
Downgrade	At next renewal	At next renewal	Defer grant until charge occurs
Crossgrade (same duration)	Immediately	Immediately	Same as an upgrade
Crossgrade (different duration)	At next renewal	At next renewal	Same as a downgrade

Tips 💡

• Always verify subscription levels in App Store Connect match your intended upgrade/downgrade flow.
• Test product changes to confirm that upgrades and downgrades behave as expected.
• Correct subscription levels allow RevenueCat to apply currency grants accurately.

Play Store

RevenueCat adjusts in-app currency grants based on the replacement mode used when changing subscriptions. Each mode affects when the new subscription takes effect, how the customer is charged, and therefore when and how much currency should be granted.

RevenueCat determines when to grant in-app currency based on whether and when a charge occurs for the new subscription. No new currency is granted until the customer is actually charged. This helps ensure that customers receive currency in proportion to what they’ve paid.

Product Change Behavior 🔄

RevenueCat adjusts in-app currency grants automatically based on how the Play Store handles product changes. Here’s how each scenario is handled:

Replacement mode	When customer is charged for new sub	When new sub starts	New currency grant behavior
WITHOUT_PRORATION	At the end of the current billing cycle	Immediately	Defer grant until charge occurs
WITH_TIME_PRORATION	At delayed billing date (pushed forward)	Immediately	Defer grant until charge occurs
CHARGE_FULL_PRICE	Immediately	Immediately	Grant full currency upon charge
CHARGE_PRORATED_PRICE	Immediately (partial)	Immediately	Grant prorated currency based on the partial charge
DEFERRED	At the end of current billing cycle	At next renewal date	Defer grant until new sub starts and charge occurs

Tips 💡

• Don’t rely solely on default replacement modes. The Play Store defaults to WITH_TIME_PRORATION when no replacement mode is specified, which pushes out the billing date without charging the customer immediately. This can lead to confusion if a customer expects more currency right away, but hasn’t actually paid yet.
• Recommended modes when using in-app currencies for subscriptions:
  • Use CHARGE_FULL_PRICE or CHARGE_PRORATED_PRICE for immediate upgrades. These modes trigger a charge, allowing RevenueCat to grant currency right away.
  • Use DEFERRED for downgrades, the new subscription takes effect later, and currency is granted only once the customer is charged.
• These modes help ensure that currency is tied to actual payments, providing a clearer and more consistent customer experience, especially if customers associate a subscription change with receiving more in-app value.

Stripe

Stripe supports different proration modes combined with optional billing cycle resets when customers change subscriptions, which can result in 6 different proration behaviors.

Product Change Behavior 🔄

RevenueCat adjusts in-app currency grants automatically based on how Stripe handles product changes. Here’s how each scenario is handled:

Proration behavior	Billing cycle reset	When customer is charged for new sub	New currency grant behavior
No proration (none)	Now	Immediately, full price	The full in-app currency amount is granted immediately
No proration (none)	Unchanged	At next renewal date	The full in-app currency amount will be granted at the next renewal date
Immediately proration (always_invoice)	Now	Immediately, full price	Grants in-app currency immediately, while also taking into account any credits Stripe grants for unused time left on the old subscription. Customers will receive an adjusted amount of currency.
Immediately proration (always_invoice)	Unchanged	Immediately, partial price	Grants in-app currency immediately, while also taking into account any credits Stripe grants for unused time left on the old subscription. Customers will receive an adjusted amount of currency.
Proration in next cycle (create_prorations)	Now	Immediately	Same as immediate proration with billing cycle reset, the adjusted in-app currency amount is granted immediately.
Proration in next cycle (create_prorations)	Unchanged	At the end of the currency billing cycle	Grant prorated currency combined with upcoming renewal, may include an additional full grant at renewal.

Tips 💡

• To ensure in-app currency is granted at appropriate times and in amounts that reflect what customers are actually paying, we recommend the following configurations:
  • Upgrades: Use any proration mode with a billing cycle reset to now. This charges the customer immediately for the new subscription and allows RevenueCat to grant in-app currency right away.
  • Downgrades: Use either no proration or proration in the next cycle without a billing cycle reset (unchanged). The new (downgraded) subscription will go into effect at the next renewal date.

RevenueCat Billing

RevenueCat Billing supports subscription changes through configured upgrade and downgrade paths in the Customer Portal. For in-app currency, RevenueCat currently grants currency for RevenueCat Billing subscriptions only on purchase and renewal events, not as a separate grant at the moment a subscription change is scheduled or processed.

RevenueCat will grant in-app currency for the following scenarios:

• Initial purchases
• Renewals

Currency is granted in full based on the configuration amount for the active subscription product.

Refunds

When a subscription that granted in-app currency is refunded, RevenueCat will:

• Remove a prorated amount of the originally granted currency, based on the refund amount.
• Round up to the nearest whole number (fractional balances are not supported).
• Cap the balance at zero if the removal would result in a negative balance.

⚠️Partial refunds on Google Play

Partial refunds are not reliably detected for Google Play and may not affect the currency balance. Learn more in our refunds doc.

If you are also using one-time purchases, refer to our refunds documentation for more details on how those are treated.

Grace Periods and Billing Recovery

When a customer enters a grace period due to an issue with their payment method (such as an expired credit card), RevenueCat will not deposit any currency until the billing issue is successfully resolved.

• During grace period: In-app currency will not be granted since the payment has not gone through yet.
• Recovery within grace period: if the subscription recovers (e.g: the payment is completed) within the grace period, RevenueCat will grant the currency for that billing cycle. The deposit behaves as if the renewal occurred on time.
• Recovery after grace period ends: If the subscription failed to recover within the grace period, the subscription is considered expired. When a successful purchase occurs afterwards, the in-app currency schedule resets from that new start date.

Was this page helpful?