Subscription statuses and update options

Every subscription in Cleverbridge has a status that reflects its current state in the customer lifecycle—such as active, pending cancellation, or expired. These statuses determine what actions are available, both to you as the merchant and to your customers, and they influence how the subscription appears in the Subscription Management Portal and in backend tools.

You can view a subscription's status and manage related updates directly in the Subscription Management Portal. The same information is also available in the Subscription section of the Customer Profile in SCM. For more details, see Customer Profile.

Statuses

We need to distinguish between subscription statuses and subscription item statuses. So, a subscription can contain more than one item/product if both items have an identical interval length. For example, if the customer purchases two of your subscription products in the same cart and both those products have an identical interval length, this is considered and billed as one subscription. This means the customer won't be billed under two separate invoices. There is one subscription ID for all items, but all items can have different item statuses.

Subscription statuses

The following subscription statuses are available:

Status	Description
Active	The customer will be billed automatically on the next renewal date. The customer has paid for the current billing interval and is entitled to receive service from you until the next renewal date. How the subscription is renewed depends on the customer payment profile (manual renewal with offline payment options or automatic renewal with online payment options).
Deactivated	The subscription will not be renewed automatically on the renewal date. There are different scenarios how this status can be assigned to a subscription. For instance, the subscription will not be renewed if a customer decides to stop the auto-renewal or if customer service receives a complaint and consequently stops further renewals by a chargeback or a full refund request. note You will receive the following notifications for the Deactivated subscription status: A RecurringBillingCanceledNotification when the customer stops the auto-renewal. Make sure to deactivate the customer's license by the next renewal date so its validity is not extended. A ChargebackNotification or RefundNotification once the refund is processed. You can then deactivate the customer's license immediately.
Finished	The subscription product was set up and the checkbox End subscription after this many billing events was selected. All required rebilling events are complete for a subscription.
Grace	In case a customer doesn't immediately pay, the subscription is in a grace period. The customer may still be able to use the product. When the customer pays, the billing date moves forward. If the customer doesn't pay after a period of time, the subscription goes into hold.
Handled by Client	The client controls the entire subscription process. Cleverbridge does not handle anything for the client.
Hold	A scheduled payment was missed. Cleverbridge didn't receive payment for a subscription. Example A renewal date for the subscription has come, and the customer has withdrawn their approval for the subscription renewal payment or their payment is not successful. In this case: The status of the customer's subscription changes from Active to Hold. We try to collect the payment again automatically after five days using our Retry Logic. The subscription status remains on Hold. This standard behavior has a revenue retention value. It means that if the customer makes a late payment on day 10 after the payment due date, the subscription status changes from Hold back to Active and the customer continues using the license. tip The Hold subscription status is the termination status for the subscription. This means that the subscription remains on Hold indefinitely in case the payment does not succeed. Contact Client Experience and ask them to switch on the Grace option, which will give the customer time to update their payment information before the subscription goes into Hold.
New	Initial status before the first payment.

Subscription item statuses

The following subscription item statuses are available:

Status	Description
Active	Item is currently active.
Deactivated	Item was deactivated.
Finished	All required rebilling events are complete for an item.
Removed	Item was removed and cannot be reactivated. For example, the item may have been replaced by another item.
Awaiting Reinstate	Item is on hold until the customer confirms that the subscription should stay active.

Subscription statuses and subscription item status combinations

This table explains the meaning of different combinations of the two statuses.

Subscription status	Item Status	Meaning
Active	Active	The customer will be billed per interval, according to the product setting at the time you added the product to the subscription.
Active	Deactivated	The subscription has multiple subscription items, and one of the items was either canceled or a refund was issued for the item. A deactivated item can be reinstated via Commerce Assistant or via an "activate" link that is sent to the customer in an email.
Active	Removed	The subscription item has been removed. You can use the AddSubscriptionItem API endpoint to add the item to the subscription again.
Deactivated	Active	Occurs when a refund is processed. The subscription status is set to Deactivated, but the item status remains Active when the checkbox "Deactivate and terminate subscription billing" is selected during the refund process.
Deactivated	Deactivated	Occurs when all subscription items have been canceled by the customer or in the Cleverbridge platform.
Deactivated	Awaiting Reinstate	The most common combination for manual-renewal subscriptions. Here, the customer agreed to purchase the subscription product for the duration agreed upon. To get the customer to extend the service or subscription, you should generally send an email marketing campaign to the customer with links that allow them to reinstate the subscription. This status combination also occurs when a customer, typically working for a corporation, government, or educational institution, makes a price quote for a subscription product.
Finished	Active	An exception to the definition above. This status applies to new orders that were reviewed by the Cleverbridge Fraud Team. The purchase was flagged as fraudulent, and the purchase status is OrderBlockedforExportCompliance.
Finished	Finished	The subscription is finished, and the customer has paid all the billing events as defined in the product settings under Subscription Options > End subscription after this many billing events. You also get this status combination when you deactivate all subscription items using the DeactivateSubscriptionItems function and set AllowReinstate to false.
Grace	Active	Cleverbridge didn't receive payment for a subscription, but the customer may still use the product. The customer still has a certain number of days to update their payment information (in the case of online payment methods) or make a payment (in the case of offline payment methods) before the subscription goes into Hold.
Hold	Active	The payment was declined (in the case of online payment methods) or the customer didn't make the payment (in the case of offline payment methods). In both cases, the customer needs to either change or fill in the payment information.
Hold	Deactivated	The customer clicked on the "Cancel" link when the subscription was already on Hold. This status
New	Active	The customer signed up for a subscription (initial subscription purchase), but Cleverbridge hasn't received a payment yet. In this case, the subscription is in interval 0 (initial subscription interval), and the payment was either declined (in the case of online payment options) or the customer hasn't made the payment yet (in the case of offline payment options).

Subscription intervals vs subscription item intervals

The platform tracks both the subscription lifecycle and the lifecycle of each item within the subscription. Select a tab to understand how each interval number is counted.

Subscription interval

Subscription interval number

Every newly created subscription gets an interval number assigned to it. The initial subscription purchase, or sign-up, is equivalent to interval 0. With every subsequent renewal of the subscription, the subscription interval number is incremented by 1. Interval 1 is equivalent to the first subscription renewal, interval 2 to the second subscription renewal, and so on.

Every subscription can contain x subscription items, which all renew on the same date.

note

If a customer has more than one ongoing subscription, each subscription is set to renew on its own individual date, depending on the initial date of the subscription purchase and the subscription length: Subscription 1 renews on January 3; subscription 2 renews on July 19, etc. The renewal of multiple items within each individual subscription, however, is set to renew on the same date.

Subscription item interval

Subscription item interval number

Every newly created subscription item gets an interval number assigned to it. The initial subscription item purchase is equivalent to interval 0. With every subsequent renewal of the subscription item, the subscription item interval number is incremented by 1. Interval 1 is equivalent to the first subscription item renewal, interval 2 to the second subscription item renewal, and so on.

All subscription items in one subscription (Subscription 1) have the same renewal date: January 3.

Example

At the bottom you can see the running Subscription Interval Number. In the rows above, you can see the respective running Item Interval Numbers

Update Options for subscriptions

There following actions can be performed to a Subscription:

Action	Description
Deactivate	If a customer requests subscription deactivation or cancellation, either you or Cleverbridge Customer Support can deactivate the subscription. Click the Deactivate button in the Subscription Billing tab of the Purchase viewer. After deactivation, the customer receives a confirmation email. Deactivation prevents billing for unpaid orders but doesn't affect previously billed orders. If a refund is needed for a billed order, Cleverbridge Customer Support must process it.
Await Reinstate	To suspend billing intervals without canceling the subscription, click the Await Reinstate button in the Subscription Billing tab of the Purchase Viewer. This places the subscription on hold until the customer confirms via email that the subscription should remain active. Alternatively, switch the renewal type to manual by clicking the Switch to Manual Renewal button. This stops future billing while simplifying reactivation. Use the Switch to Automatic Renewal button to revert back to automatic renewal.
Reinstate	To reactivate a deactivated subscription, click the Reinstate button in the Subscription Billing tab of the Purchase viewer. After reinstating, the customer receives a confirmation email.
Extend Next Billing Date	Extend the billing date for a subscription by clicking the Extend Next Billing Date button in the Subscription Billing tab of the Purchase viewer. You can enter the number of additional days or select a specific next billing date.
Copy Change Payment Link	Generate a unique link for customers to review and update their payment details for subscriptions. Create this link by clicking the Copy Change Payment Link button in the Subscription Billing tab of the Purchase viewer.

Reporting scenarios

Select the scenario that matches the subscription structure to understand how subscription and item intervals appear in reporting.

Single-item subscription

Subscriptions with one single subscription item

Provided the subscription item remains the same and has not been replaced by another subscription item throughout the duration of the subscription, reporting on subscription interval number and subscription item interval number will come back with identical results.

Multi-item subscription

Subscriptions with multiple subscription items

When reporting on the subscription level, any addition of items is counted as a single renewal.

When reporting on subscription item level, additional item(s) are counted as purchase (item interval 0) and existing items are counted as renewals. This leads to more events being reported: for example, 1 renewal + 1 purchase in a 2-item subscription.

note

• In XML, Subscription Interval Number and Subscription Item Interval Number are called SubscriptionIntervalNo and IntervalNo, respectively.
• In JSON, Subscription Interval Number and Subscription Item Interval Number are called subscriptionIntervalNumber and intervalNumber, respectively.

Did you find this doc useful?