Renewal Solution

Build a solution that lets customers renew their subscription asset. 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.

Renew 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 renewal solution, you must have created assets and billing schedules for the new sale order, for example, by using the Buy Now solution.

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, 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 time span of the subscription, and an asset action to represent the change caused by the new sale. The asset's quantity is 0, because the quantity is taken from the asset state period.

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, to generate an invoice each month, call /actions/standard/createInvoiceFromOrder.

The following diagram shows the billing schedule in October after 10 monthly invoices are created.

Initial Billing and Billing Schedule

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.

Example: Create a Renewal Order on October 15, 2022

On October 15, 2022, 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.

FieldValue
RenewalTerm12
RenewalTermUnitMonths
RenewalPricingTypeLast Negotiated Price

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

renewal order

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.

Example: Update the Asset to Reflect the Renewal

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.

Renewal Asset Object Model

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.

Example: Update the Billing Schedule Group to Reflect the Renewal

A new billing schedule with a start date of January 1, 2023, is created to store 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.

renewal Asset Object Model

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

ParameterValue
invoiceDateorder.EffectiveDate
targetDateorder.EffectiveDate
invoiceStatusPosted

To avoid unexpected behavior, finish invoicing the new sale order before invoicing 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.