Cancellation Solution

Build a solution that lets customers cancel their subscription orders, track the changes to a customer's assets, and recognize changes to revenue.

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, recording 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.

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

Before you build this solution, you must create assets and billing schedules for the new sale order.

• To create assets, call /actions/standard/createOrUpdateAssetFromOrder.
• To create billing schedules, call /actions/standard/createBillingScheduleFromOrderItem.

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

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

To create assets for the new sale order, you called /actions/standard/createOrUpdateAssetFromOrder. The system generated an asset state period to represent the time span of the subscription and an asset action to represent the change owing to the initial sale. The asset's quantity is zero, because the quantity is taken from the asset state period.

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

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

Example: Cancel the Order for August 1

On July 15, seven months into the subscription, the customer cancels all 10 licenses. The cancellation takes effect August 1. The /asset-management/assets/{assetId}/actions/initiate-cancellation request creates a cancellation order with a quantity of -10. The AssetCancelInitiatedEvent returns the ID of the cancellation order.

Call /actions/standard/createOrUpdateAssetFromOrder to update the asset, so that it reflects the cancellation. 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

The system updates the asset state period to end on July 31 (1 second before the cancellation order date). A new asset action is created to indicate the changes in quantity, amount, and monthly recurring revenue.

Call /actions/standard/createBillingScheduleFromOrderItem to update the billing schedule and billing schedule group to reflect the cancellation. Use the ID of the new sale order item.

Subscribe to the BillingScheduleCreatedEvent to learn when the billing schedule is updated.

Example: Update the Billing Schedule Group to Reflect the Cancellation

The end date on the billing schedule and billing schedule group is changed to August 1 to reflect the cancellation. The changes are rolled up to the billing schedule group.

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 is changed to Completely Billed.