Skip to main content

Subscription Lifecycle

⚠️Beta Feature

RevenueCat Billing and the RevenueCat Web SDK are currently in beta.

Overview​

Here is an overview of the various states that a RevenueCat Billing subscription can take on, as well as the events that are being sent as a subscription transitions from one state to the other. For more details, read the following sections.

Starting a subscription​

The process to start a subscription is initiated by calling the purchase method in the SDK. The subscription starts only if and when the initial payment is confirmed – if the customer cancels the checkout form, or if the initial payment for the subscription fails, no subscription is generated, and no events will be generated.

When the subscription is successfully started, RevenueCat generates an INITIAL_PURCHASE event. An invoice is then generated and sent to the customer via email, along with a link to the customer portal.

Offers​

RevenueCat Billing does not yet support any offers, discounts, or free trials.

Renewal​

RevenueCat will attempt to charge the payment method of a customer not more than 24 hours before the end of the current billing period, if the customer has not canceled their subscription. An invoice is generated for the renewal attempt.

Successful renewal​

If the renewal payment is successfully processed, RevenueCat will:

  • Generate a RENEWAL event.
  • Send a renewal confirmation email to the customer, including their invoice and a link to the customer portal.

Unsuccessful renewal​

If the renewal payment couldn't be charged successfully, RevenueCat will:

  • Generate a CANCELLATION and BILLING_ISSUE event.
  • Generate an EXPIRATION event, unless a grace period has been configured.
  • Send a notice of the billing issue to the customer via email, including their invoice and a link to the customer portal to fix their payment method.

The subscription then enters the billing retry period.

Billing retry​

After a renewal payment has failed, RevenueCat will retry charging the customer's payment method on file for up to 30 days.

Billing recovery​

If one of the retry attempts is successful, RevenueCat will renew the subscription and generate a RENEWAL event. Unless the subscription was still in a grace period, the new billing cycle will start on the date that the payment was succesfully recovered.

As an example, consider a monthly subscription started on 1 January, for which the first renewal on 1 February failed, and no grace period was set up. If the payment gets recovered on 10 February, the next billing cycle will run from 10 February to 10 March.

Overview of billing retry and recovery​

The following image illustrates the timelines and events sent for a successful billing recovery under different circumstances. If the billing retry period ends without being able to recover the payment, no further events get sent, and the subscription remains expired.

In all three cases, a monthly subscription is shown that started on January 1st. The first renewal payment on February 1st failed.

  • Case 1: If a 14 day grace period was set up, the failed renewal payment on February 1st leads to BILLING_ISSUE, and CANCELLATION events. If the billing is later recovered within the grace period (eg. on February 10th), a RENEWAL event is sent. The subscription remains on its original billing cycle, ie. the next renewal will occur on March 1st.
  • Case 2: Like in case 1, the failed renewal with a 14 day grace period leads to BILLING_ISSUE, and CANCELLATION events. If the payment couldn't be recovered by the end of the grace period, an EXPIRATION event is sent because the customer should now lose access to their entitlement. If the payment is later recovered (eg. on February 20th), a RENEWAL event is sent. The next subscription cycle restarts from the time that the billing was recovered (eg. the next monthly billing period will run from February 20th to March 20th).
  • Case 3: If no grace period was set up, the failed payment leads to BILLING_ISSUE, CANCELLATION, and EXPIRATION events, since the customer in this case immediately loses access to their entitlements. If the billing is later recovered (eg. on February 20th), a RENEWAL event is sent. The next subscription cycle restarts from the time that the billing was recovered (eg. the next monthly billing period will run from February 20th to March 20th).

Cancelation​

The subscription can be canceled by the customer (via the customer portal) or by the developer (via the dashboard or API). If the subscription is cancelled, RevenueCat will generate a CANCELLATION event. The subscription will continue to be active until the end of the current period. At the end of the period, the subscription will expire.

Refunds​

You can refund the most recent subscription period of a subscription from the RevenueCat Dashboard. Refunds will result in a CANCELLATION event with a cancellation_reason of CUSTOMER_SUPPORT. If a subscription is refunded, the customer immediately loses access to any associated entitlements.

Expiration​

A subscription can expire for one of several reasons:

  • The subscription has been cancelled and the billing period ended.
  • A renewal payment failed and no grace period was set up. Please note that in this case, if payment gets recovered at a later point, the subscription may become active again (and a RENEWAL event will be generated).
  • A grace period has ended. Please note that in this case, if payment gets recovered at a later point, the subscription may become active again (and a RENEWAL event will be generated).
  • The subscription was refunded.

In all of these cases, an EXPIRATION event is generated.