Renew Subscription Example

Let customers renew 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.
• On October 15, the customer renews all 10 licenses at the last negotiated price.

This solution calculates the price of the renewal, creates and activates the renewal order, then creates the billing schedule. Finally, the solution creates the first invoice for the renewal order.

This diagram illustrates one way to build a renewal 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 the renewal solution, you must have created assets and billing schedules for a new sale order, for example, by using the Buy Now solution.

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.

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, to generate an invoice each month, call [/commerce/invoicing/invoices/collection/actions/generate][collectionactionsgenerate].

The following diagram shows the billing schedule in October after 10 monthly invoices are created. The total billed amount indicates that $1,000 has been billed since the beginning of the subscription. The total pending amount indicates that $200 remains to be billed.

First, update the following fields on the Asset record so the renewal order can be priced.

• Renewal Term—the number of renewal term units in the renewal term, for example, the number of months.
• Renewal Term Unit—the unit of time used to measure the renewal, for example, Months.
• Renewal Pricing Type—how to price the renewal. To renew at the same price, use Last Negotiated Price. To renew at the current list price, use List Price.

Then, to create the renewal order, call /asset-management/assets/{assetId}/actions/initiate-renewal. Subscribe to the AssetRenewInitiatedEvent platform event to learn when the renewal order is created and to get its ID.

On October 15, 10 months into the subscription, the customer renews all 10 licenses at the last negotiated price. The renewal takes effect Jan 1, 2023.

To create a renewal order, first set the following fields on the Asset record, either in Salesforce or by calling the REST API.

Then, call /asset-management/assets/{assetId}/actions/initiate-renewal to create a renewal order, passing in the ID of the updated asset.

Subscription management creates a renewal order with a renewal order item. The order item's total line amount is $1,200.

To update the asset and related records so that it reflects the renewal, call /actions/standard/createOrUpdateAssetFromOrder. Use the ID of the renewal order from the previous step. To learn when the asset is updated, subscribe to the CreateAssetOrderEvent platform event.

The system creates an asset state period for January 1 to December 31, 2023. A new asset action is created to record the changes in quantity, amount, and monthly recurring revenue.

• The original asset state period is unchanged.
• A new asset state period is created. It's start date is Jan 1, 2023.
• A new asset action is created to record the change in quantity, amount, and MRR due to the renewal.

To create the renewal billing schedule and update the billing schedule group, call /actions/standard/createBillingScheduleFromOrderItem. Use the ID of the renewal order item. To learn when the billing schedule is updated, subscribe to the BillingScheduleCreatedEvent platform event.

After calling /createBillingScheduleFromOrderItem with the renewal order item, a new billing schedule with a start date of January 1, 2023, is created. This new billing schedules stores billing information for the renewed order. The changes are rolled up to the billing schedule group, where the end date for the billing schedule group is changed from December 31, 2022, to December 31, 2023.

Use /actions/standard/createInvoiceFromOrder to create an invoice for the renewal order. Pass in the following values from the renewal order:

Two invoices are generated for each order item: one invoice for the cost of the item, and one invoice for the tax. If the order item is sold by subscription, the first set of invoices contains the amounts owed for the first billing period.

To learn when the invoices are created and to get the IDs of the invoice records, subscribe to the InvoiceProcessedEvent platform event.