Understanding Subscription Lifecycle Flows

This guide provides a detailed look at the key flows that govern a subscription's journey - from initial purchase to renewal, cancellation, and beyond. Whether you're managing subscriptions directly via the web or integrating with third-party platforms, understanding these lifecycle flows ensures accurate entitlement handling and seamless user experiences.

Each subscription in our system transitions through well-defined lifecycle stages, driven by customer (end-user) actions, system processes, or external triggers (e.g., app store events).

Understanding these states helps you interpret entitlement behavior, billing expectations, and API responses accurately.

Subscription Statuses Explained

Here are the core statuses a subscription can have throughout its lifecycle:

Subscription status	Description
active	The customer (end-user) has access with valid entitlements. Billing is scheduled to happen at the next renewal (anniversary) date.
stopped (also referred to as canceled)	The customer (end-user) still has access to the subscription which will remain available until the end of the current billing period, after which the subscription will not renew. No further billing will occur.
terminated	The customer (end-user) does not have access to the subscription, entitlements are not valid any more. No future billing will occur.

Each flow described in this article will indicate the transitions between these statuses and outline the associated triggers.

Subscription Lifecycle Flows

Each flow below shows:

user/system actions
subscription statuses
events

Initial Purchase

This section describes events for web and Apple StoreKit 2 purchases.

The Initial Purchase flow covers the process when a customer buys a subscription offer for the first time. This flow involves successful payment processing, subscription creation, and entitlement activation.

The following webhook events are created:

🔔 transactionCreated
🔔 subscriptionCreated

The subscription status becomes: active. The customer gets access to content.

When the subscription renewal date comes, a successful recurring payment must happen for the subscription to continue in active status, so the following webhook events are created:

🔔 transactionCreated
🔔 subscriptionRenewed

For situations when payments are unsuccessful please refer to: subscription cancellation flow, billing retry flow.

Subscription Cancellation

This section describes events for web and Apple StoreKit 2 purchases.

When a customer cancels their subscription, the following webhook event is created:

🔔 subscriptionStopped

The subscription status changes to stopped (canceled), but access to content continues until the end of the current billing period.

When the subscription reaches the end of the billing period, another webhook event is created:

🔔 subscriptionTerminated

It marks the end of the subscription. Its status changes to terminated, and access is revoked.

While subscription status is stopped (canceled), the customer can still reactivate it, see Subscription Reactivation Flow.

Subscription Reactivation

This section describes events for web and Apple StoreKit 2 purchases.

If a customer cancels a subscription, but then reactivates it while its status is stopped (canceled), the following webhook event is created:

🔔 subscriptionReactivated

The subscription status changes from stopped (canceled) to active.

Subscription Extension - Web

This section describes events for web purchases.

Subscription extension covers the process when a publisher extends an active subscription - changes its expiration date and extends the billing period. The following webhook event is created:

🔔 subscriptionExtended

Such a subscription is renewed at the new expiration date. The following webhook event is created:

🔔 subscriptionRenewed

Refunds

▪️ Refunds - Web

This section describes events for web purchases.

When a customer requests a refund for their subscription, the following webhook event is created:

🔔 refundPayment

The subscription status remains active.

Then, when a payment refund process is completed and funds are returned to the customer, another webhook event is created:

🔔 paymentRefunded

At this point the customer loses access to content.

▪️ Refunds - Apple StoreKit 2

This section describes events for Apple StoreKit 2 purchases.

When Apple sends "Refund" notification, the folowing webhook event is created:

🔔 paymentRefunded

At this point the customer loses access to content.

Chargebacks - Web

This section describes events for web purchases.

When the chargeback is awarded, the following webhook event is emitted:

🔔 subscriptionTerminated

This marks the end of the subscription. At this point the customer loses access to content.

Trial with Successful Conversion

This section describes events for web and Apple StoreKit2 purchases.

A successful conversion after trial entails a customer subscribing to an offer, providing valid payment details, and continuing with a standard subscription when a trial period ends.

When a customer starts a trial period, the following events are created:

🔔 subscriptionCreated
🔔 transactionCreated

The subscription status becomes: active.

When a trial period reaches its end, and converts to a standard, paid subscription, the customer is charged. The following events are created:

The subscription status remains active.

Trial without Successful Conversion

This section describes events for web and Apple StoreKit 2 purchases.

An unsuccessful conversion after trial entails a customer subscribing to an offer, but failing to continue with a standard subscription when a trial period ends.

When a customer starts a trial period, the following events are created:

🔔 subscriptionCreated
🔔 transactionCreated

The subscription status becomes: active.

When a trial period reaches its end, but payment attempt fails, the following event is created:

🔔 paymentRejected

The payment retries are made as per defined dunning action logic. The subscription status remains active for the duration of Grace period.

When the grace period reaches its end and payment does not succeed, the following event is created:

🔔 subscriptionTerminated

It marks the end of the subscription. Its status changes to terminated, and access is revoked.

Trial without Successful Conversion Flow

Customer Cancels Free Trial

This section describes events for web and Apple StoreKit2 purchases.

It might happen that a customer starts a trial period for a subscription, but then he/she cancels before the trial period ends, and does not convert to a standard subscription.

When a customer starts a trial period, the following events are created:

🔔 subscriptionCreated
🔔 transactionCreated

The subscription status becomes: active.

When a customer cancels their subscription during trial period, the following webhook event is created:

🔔 subscriptionStopped

The subscription status changes to stopped (canceled), but access continues until the end of the current trial period. When the trial period comes to an end, the following webhook event is created:

🔔 subscriptionTerminated

It marks the end of the subscription. Its status changes to terminated, and access is revoked.

Offer Switch

This describes events for web and Apple StoreKit 2 purchases.

When a customer switches an offer (upgrades or downgrades), it can be changed immediately or the switch may be deferred, depending on the algorithms used.

Below you can see an example flow, and events emitted for offer switches.

When a customer has an active subscription to offer A and requests a switch (upgrade/downgrade) to offer B, the switch is scheduled, and the following event is created:

🔔 subscriptionSwitchRequested

The subscription status remains active.

Once the scheduled switch is completed, the following event is created:

🔔 subscriptionSwitched

At this point the customer gets access to the new offer - offer B, subscription status is active.

Billing Retry

▪️ Billing Retry - Web

This section describes events for web purchases.

When payment issues occur while renewing a subscription, there is a payment retry logic (dunning actions) in place.

When a customer buys a subscription offer for the first time, the initial payment takes place.

The following webhook events are created:

🔔 transactionCreated
🔔 subscriptionCreated

The subscription status becomes: active.

When the subscription renewal date comes, and a successful recurring payment happens, the following webhook events are created:

🔔 transactionCreated
🔔 subscriptionRenewed

The subscription status remains: active.

When the subscription renewal date comes, but a recurring payment fails, the following webhook events are created:

🔔 paymentRejected

The payment retries are made as per defined dunning action logic. The subscription status remains: active (grace period).

When the subscription reaches the end of the grace period, and payment fails, the following webhook event is created:

🔔 subscriptionTerminated

The subscription status changes to: terminated.

▪️ Billing Retry - Apple StoreKit 2

This section describes events for Apple StoreKit 2 purchases.

When payment issues occur while renewing a subscription, there is a payment retry logic.

When a customer buys a subscription offer for the first time, the initial payment takes place.
The following webhook events are created:

🔔 subscriptionCreated
🔔 inAppPurchaseSyncResult

The subscription status becomes: active.

When the subscription renewal date comes, but a recurring payment fails, and the grace period begins, the subscription status remains: active. Billing retries continue.

When the subscription reaches the end of the grace period, and payment fails, the following webhook event is created:

🔔 subscriptionTerminated

The subscription status changes to: terminated.

Billing retries on Apple's side continue, and if a payment succeeds, a new subscription with a new renewal (anniversary) date is created in Cleeng. The following webhook events are triggered:

🔔 subscriptionCreated
🔔 transactionCreated

The link between the original subscription and the new subscription is captured in the subscription properties:

New subscription:

  "originatedFrom": {
    "subscriptionId": 111111111,
    "reason": "revival",
    "date": 16911432000
  }

Transfer Access to New User - Apple StoreKit 2

This section describes events for Apple StoreKit 2 purchases.

When customer A purchases a subscription, the following webhook events are created:

🔔 subscriptionCreated
🔔 inappPurchaseSyncResult

The subscription status for customer A becomes: active.

When the subscription is transferred to customer B (purchase is restored by customer B), the following webhook events are created:

🔔 subscriptionTerminated for customer A
🔔 subscriptionCreated for customer B

The subscription status for customer B becomes: active.

The link between the original subscription and the new subscription is captured in the subscription properties.

New subscription:

  "originatedFrom": {
    "subscriptionId": 111111111,
    "reason": "transferred",
    "date": 1691143200
  }

Original subscription:

 "replacedBy": {
    "subscriptionId": 333333333,
    "reason": "transferred",
    "date": 1691143200  
 }

Transfer Access to New User Flow - Apple StoreKit 2