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.

Subscription uncancelled

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

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.

Subscription renewal retry

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

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 Itunes connect (App Store Connect Help).


Subscription grace period expire

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

Subscription renewal

The subscription has been renewed.

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)

Subscription pause enabled

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

Subscription pause disabled

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