Build With RevenueCat

Build a customized mobile subscription business with RevenueCat. We do the heavy lifting of normalizing subscribers from any source and maintain a single source of truth for subscription status, so you can get back to building your app.

RevenueCat is a powerful, secure, reliable, and free to use in-app purchase server with global support. All you need to get started is an API key.

Get Started    REST API Endpoints

Managing Subscriptions

Making changes to a customer's subscription

Some parts of a customer's subscription can be managed directly through RevenueCat, other parts can only be managed by the customer directly in Apple / Google. Learn how to upgrade/downgrade, cancel, and refund subscriptions here!

For information about Stripe, you can read more about working with web payments here.

Upgrade or Downgrade a Subscription

πŸ“˜

Developers cannot change a customer's subscription directly

The app stores do not allow developers (you) to upgrade or downgrade a subscription on behalf of a customer. Only a customer can change their subscription.

iOS

There are no code changes required to support upgrades, downgrades, and crossgrades for iOS subscriptions in your app. A customer can choose to upgrade, downgrade, or crossgrade between subscriptions as often as they like.

According to Apple, when a customer changes their subscription level, access to the new product can vary depending on the change:

Upgrade. A user purchases a subscription that offers a higher level of service than their current subscription. They are immediately upgraded and receive a refund of the prorated amount of their original subscription. If you’d like users to immediately access more content or features, rank the subscription higher to make it an upgrade.

Downgrade. A user selects a subscription that offers a lower level of service than their current subscription. The subscription continues until the next renewal date, then is renewed at the lower level and price.

Crossgrade. A user switches to a new subscription of the equivalent level. If the subscriptions are the same duration, the new subscription begins immediately. If the durations are different, the new subscription goes into effect at the next renewal date.

You can refer to this blog post for more information on how to set up subscription groups in App Store Connect.

πŸ“˜

Sandbox testing

Due to sandbox limitations, you cannot test upgrade/downgrade/crossgrade in sandbox.

Android

In order to perform upgrades and downgrades for Android subscriptions, you need to pass the UpgradeInfo object to either purchaseProduct or purchasePackage. The UpgradeInfo is a small object containing the oldSKU (the SKU the user is changing from) and the prorationMode. Proration modes are documented here.

πŸ“˜

Supported proration modes

RevenueCat currently only supports IMMEDIATE_WITH_TIME_PRORATION. This mode changes the subscription immediately and the remaining time will be prorated.

Considerations

PRODUCT_CHANGE events and webhooks

Note that expiration_at_ms will always be for the product the customer is changing from (old product). You will also see a RENEWAL event trigger when the new iOS subscription is in effect, an INITIAL_PURCHASE would trigger for Android instead. When this triggers may vary for App Store subscriptions depending on if the product change is an upgrade, downgrade, or crossgrade.

Prorations

iOS

Due to some limitations, prorated revenue will not be calculated in the customer page. However, prorated revenue will be calculated for your chart and overview data.

Android

RevenueCat assumes the default proration mode, IMMEDIATE_WITH_TIME_PRORATION, for all pricing calculations. This mode will take effect immediately, and the new expiration time will be prorated and credited or charged to the user.

If you choose a different proration mode, the subscription status will be reflected correctly but the RevenueCat price calculation will be off.

Cancel a Subscription

iOS

Apple does not allow developers to manage subscriptions on behalf of users. Your customers have to manually opt-out of renewal.

Android

To revoke an Android subscription, you can use our REST API endpoint to do so. This will refund the last purchase, immediately expire the subscription, and remove entitlement access. This can also be done from the dashboard (see 'Refund a Subscription' below for more details).

🚧

Deleting a User

Deleting a user from RevenueCat WILL NOT cancel their subscription. The user can still trigger the Restore Purchases method to re-sync their transactions with RevenueCat servers.

Refund a Subscription

Refunds are issued differently depending if a subscriber purchased through the App Store or the Play Store.

App Store

Apple does not allow developers to issue refunds on behalf of users. Customers will need to contact Apple customer support directly for a refund.

If a user requests a refund, you can direct them to the Apple support page: https://support.apple.com/en-us/HT204084

Play Store

There are multiple ways to refund a customer that purchased through the Play Store:

  • (recommended) Active Android subscriptions may be refunded directly through the RevenueCat dashboard. Click on the respective transaction event on the customer page and hit "Refund" in the upper right. Documentation for reference.
  • Refunds can also be granted programmatically through the RevenueCat REST API. This will immediately revoke access to the Google subscription and issue a refund for the last purchase.
  • It's also possible to refund users directly through the Google Play console. This is not recommended since RevenueCat cannot track refunds initiated through the Google Play console.

We recommend granting a refund directly through RevenueCat to keep chart data consistent. Note that refunding a subscription through RevenueCat would also revoke access.

Updated 27 days ago


Managing Subscriptions


Making changes to a customer's subscription

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.