Manage subscription states

This article aims to list the different states of a renewable subscription.

New subscription

A new subscription has been purchased and is now active.

• A purchase webhook will be triggered.
• When fetching the purchase of the subscription, the isSubscriptionActive property is true and the subscriptionState property is active.
• When fetching the user, the subscription will be returned in the activeProducts with the subscriptionState property active.

Subscription cancelled

The subscription has been cancelled, the auto-renewal is disabled but the subscription is still active and will expire on the expiration date.

• A subscription_cancel webhook will be triggered.
• The isSubscriptionRenewable property of the subscription will now be false when fetching the purchase or fetching the user.

Subscription uncancelled

The auto-renewal of a cancelled subscription is now active again, it'll be renewed on the expiration date.

• A subscription_uncancel webhook will be triggered.
• The isSubscriptionRenewable property of the subscription will now be true when fetching the purchase or fetching the user.

Subscription product changed

The subscription has been downgraded, the product of the subscription has been changed.
The subscription will be replaced with the new product at the next renewal date.

• A subscription_product_change webhook will be triggered.
• The subscriptionRenewalProduct property containing the new product will be returned when fetching the purchase or fetching the user.

Subscription renewal retry

The first attempt to renew the subscription failed but new attempts will be made.

• A subscription_renewal_retry webhook will be triggered.
• The isSubscriptionRetryPeriod property of the subscription will now be true when fetching the purchase or fetching the user.
• The isSubscriptionGracePeriod property of the subscription will be true if the grace period is enabled when fetching the purchase or fetching the user.
• The subscriptionState property of the subscription will have the retry_period or grace_period value.

You must react differently if the grace period is enabled or not.

No grace period

When the grace period is disabled, the subscriber’s days of paid service are paused until the payment is collected.
You should restrict the access to the features offered by the subscription and ask for the user to update its payment informations.

note

A subscription in a retry period will still be returned in theactiveProductsproperty when fetching the user.
You must check thesubscriptionStateproperty of an active subscription.

note

On Android you must active Account hold (lasts for up to 30 days) to enable the retry period, otherwise the subscription will expire after the renewal attempt fails.

Grace period

Billing Grace Period allows you to let subscribers whose auto-renewal failed due to a payment issue continue accessing your app’s paid content for a period of time while Apple/Google continues to attempt to collect payment.
There won’t be any interruption to the subscriber’s days of paid service or to your revenue if Apple/Google is able to recover the subscription within the grace period of your subscription product.
You should display a message asking for the user to update its payment informations.

On Android all the subscriptions have the grace period enabled by default, you can disable/enable it from the Google Play Console.
On IOS you must enable the grace period on App Store connect (App Store Connect Help).

Subscription grace period expire

The subscription grace period has ended (but the retry period is still active).

• A subscription_grace_period_expire webhook will be triggered.
• The isSubscriptionGracePeriod property of the subscription will now be false when fetching the purchase or fetching the user.
• The subscriptionState property of the subscription will now be on a retry_period when fetching the purchase or fetching the user.

Subscription renewal

The subscription has been renewed.

• A subscription_renewal webhook will be triggered.
• When fetching the user, the subscription returned in the activeProducts property will be updated.

Subscription expired

The subscription has expired and isn't active anymore (subscription is expired and retry period is over).

• A subscription_expire webhook will be triggered (last webhook you'll receive for a subscription).
• When fetching the user, the subscription won't be returned in the activeProducts property anymore.
• When fetching the purchase of the subscription, the isSubscriptionActive property is false and the subscriptionState property is expired.

Subscription pause

The subscription has been paused, you have to restrict the access to the features offered by the subscription. (Android only)

• A subscription_pause webhook will be triggered.
• The isSubscriptionPaused property of the subscription will now be true and the subscriptionState property will be paused when fetching the purchase or fetching the user.
• You will receive a subscription_renewal webhook when the subscription will automatically resume at a later date (autoResumeDate property).

Subscription pause enabled

The subscription pause has been enabled but isn't active yet. (Android only)

• A subscription_pause_enabled webhook will be triggered.
• The autoResumeDate property of the subscription will now contain the date when the subscription will automatically resume when fetching the purchase or fetching the user.

Subscription pause disabled

The subscription pause has been disabled, the subscription will renew on the expiration date. (Android only)

• A subscription_pause_disabled webhook will be triggered.
• The autoResumeDate property of the subscription will now be undefined when fetching the purchase or fetching the user.