Cancel Subscription Example

Let customers cancel their assets partway through a subscription. Track what a customer owns and owes so you can accurately recognize revenue.

In this example, the customer makes the following sales transactions.

  • On January 1, the customer buys 10 1-year licenses at $10 per month.
  • July 15, the customer cancels all 10 licenses.

This solution creates a cancellation order for the order items, updates the assets, then adjusts the billing schedule so that subsequent invoices (if any) reflect the cancellation. It then creates the final invoice to reflect the cancellation.

This diagram illustrates one way to build a cancellation solution. Information following the diagram provides more context for each step, and links to the API reference.

Cancelation Solution

If the Create Billing Schedule and Asset flow is activated, /actions/standard/createOrUpdateAssetFromOrder and /actions/standard/createBillingScheduleFromOrderItem are called automatically.

Before you build the cancellation solution, you must have created assets and billing schedules for a new sale order, for example, by using the Buy Now solution.

Example: Create an Asset and a Billing Schedule for the New Sale Order (Prerequisite)

Suppose that your customer buys 10 1-year licenses at $10 per month. The customer’s subscription (represented by an asset) starts January 1, 2022, and costs $1,200 for one year, billed monthly.

To create assets for the new sale order, call /actions/standard/createOrUpdateAssetFromOrder. The system generates:

  • An asset state period to represent the state of an asset over a period of time.
  • An asset action to represent the change made to an asset - in this case, a new sale.

The following diagram shows the asset and it's related order item.

  • The net unit price of the monthly subscription is $10.
  • The total amount of a yearly subscription for 10 licenses per month is $1,200.
  • The asset state period indicates the asset's current quantity and the monthly recurring revenue, which is $100/month.
  • The asset action indicates the change in quantity, amount, and MRR due to the new sale.

Initial asset object model

To create billing schedules for the new sale order, call /actions/standard/createBillingScheduleFromOrderItem. The system creates one billing schedule group for each order item. Then, from January to July, call /actions/standard/createInvoiceFromOrder to create monthly invoices. The following diagram shows the billing schedule in July after seven monthly invoices were created.

  • The total billed amount indicates that $700 has been billed since the beginning of the subscription.
  • The total pending amount indicates that $500 remains to be billed.

Initial Billing and Billing Schedule

To create a cancellation order, call /asset-management/assets/{assetId}/actions/initiate-cancellation, passing in the cancellation date. Subscribe to the AssetCancelInitiatedEvent platform event to learn when the cancellation order is created and to get its ID.

Example: Create a Cancellation Order on August 1

On July 15, seven months into the subscription, the customer cancels all 10 licenses. The cancellation takes effect August 1.

To create a cancellation order, call /asset-management/assets/{assetId}/actions/initiate-cancellation, passing in the cancellation date. Subscribe to the AssetCancelInitiatedEvent to get the ID of the cancellation order.

The cancellation order contains the following information.

  • A quantity of -10, indicating that all 10 subscriptions are canceled.
  • A total line amount of -$500.

Cancellation order

To update the asset and related records to reflect the cancellation, call /actions/standard/createOrUpdateAssetFromOrder. Use the ID of the cancellation order from the previous step. Subscribe to the CreateAssetOrderEvent to learn when the asset is created and to get its ID.

Example: Update the Asset to Reflect the Cancellation

Subscription Management updates the asset action and creates a new asset state period.

  • The asset state period ends on July 31 at midnight (1 second before the cancellation order date).
  • The new asset action indicates the change in quantity is -10, the change in amount is -$500, and the change in MRR is -100.

Cancellation Asset Object Model

To create a billing schedule that reflects the cancellation, call /actions/standard/createBillingScheduleFromOrderItem. Use the ID of the new sale order item.

To learn when the billing schedule is updated, subscribe to the BillingScheduleCreatedEvent.

Example: Update the Billing Schedule Group to Reflect the Cancellation

After calling /createBillingScheduleFromOrderItem with the cancellation order item, a new billing schedule is created to reflect the cancellation. The changes are rolled up to the billing schedule group.

  • The cancellation billing schedule's start date is August 1, the end date is Dec 31, and the billing period amount is -$100.
  • The cancellation date of August 1 is added to the billing schedule group. The total pending amount (rolled up from the two billing schedules) is $0.

Cancellation Asset Object Model

To create the final invoice of $0, call /commerce/invoicing/invoices/collection/actions/generate. Subscribe to the InvoiceProcessedEvent platform event to learn when the invoice is created and to get its ID.

Example: Create the Final Invoice for the August 1 Cancellation

Call /commerce/invoicing/invoices/collection/actions/generate, using the cancellation date of August 1 for the target date and invoice date.

The status on the cancellation billing schedules is changed to Completely Billed.

Cancellation Asset Object Model