Increase Subscription Quantity Example

Let customers increase the quantity of their assets partway through a subscription. Calculate the price of the quantity increase, create and activate the positive quantity amendment order, then update the related asset records. Create a billing schedule to recognize the change in revenue, then generate the next invoice.

In this example, the customer makes the following purchases.

• On January 1, the customer buys a 1-year subscription for 10 licenses at $10/month. The total price of the subscription is $1,200.
• On August 15, the customer buys an additional 5 licenses at $10/month, effective September 1. The total price of the additional licenses is $200.
• The new total amount of the subscription, including the initial purchase and the additional quantity, is $1,200 + $200 = $1,400.

This diagram illustrates one way to build a positive quantity amendment 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 have created assets and billing schedules for the 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 and an asset action. The asset state period represents a time span when an asset has the same quantity, amount, and monthly recurring revenue (MRR). The asset action represents a change made to a lifecycle-managed asset - in this case, the 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.

Create billing schedules for the new sale order by calling /actions/standard/createBillingScheduleFromOrderItem. Subscription Management creates one billing schedule and one billing schedule group for each order item in a new sale. Then, to generate an invoice each month, call /commerce/invoicing/invoices/collection/actions/generate. The following diagram shows the billing schedule on August 15 after 8 monthly invoices are created. The total billed amount indicates that $800 has been billed since the beginning of the subscription. The total pending amount indicates that $400 remains to be billed.

First, update the following field on the asset representing the subscription, so the positive quantity amendment order can be priced.

• QuantityIncreasePricingType—indicates how to price the quantity amendment. To amend at the current list price, use List Price.

Then, to create the positive quantity amendment order, call /asset-management/assets/collection/actions/initiate-amend-quantity. Subscribe to the AssetAmendInitiatedEvent platform event to learn when the amendment order is created and to get its ID.

On August 15, 2022, the customer adds 5 licenses at the list price. The increase in quantity takes effect Sept 1, 2022. To create a positive quantity amendment order, set the QuantityIncreasePricingType field on the asset, either in Salesforce or by calling the REST API.

Then, call /asset-management/assets/collection/actions/initiate-amend-quantity to create a positive quantity amendment order. Pass in the ID of the asset you’re changing, startDate = 09-01-2022T00:00.000+0000, and quantityChange=5. Subscription Management creates a positive quantity amendment order with an amendment order item. The order item's total line amount is $200, because there are 5 subscriptions per month at a price of $10 per subscription, and 4 months left in the subscription.

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

After you call /actions/standard/createOrUpdateAssetFromOrder, Subscription Management creates an asset action and an asset state period for the amendment.

• The new sale asset state period is updated. Its end date is changed to August 31, 2022 at midnight - one second before the amendment asset state period's start date.
• A new asset state period is created to reflect how the amendment has updated the asset. The amendment asset state period includes the original and the additional licenses. Its quantity is 15 and the monthly recurring revenue is $150.
• The amendment asset action stores the change in quantity, amount, and MRR.

To create the billing schedule that reflects the increase in quantity, and to update the billing schedule group, call /actions/standard/createBillingScheduleFromOrderItem. Use the ID of the positive quantity amendment order item. To learn when the billing schedule is updated, subscribe to the BillingScheduleCreatedEvent platform event.

After calling /createBillingScheduleFromOrderItem with the positive quantity amendment order item, a new billing schedule for the additional 5 licenses is created, spanning the period from September 1 to December 31. The pending amount of $200 indicates the amount due for the remainder of the subscription. The changes from the new billing schedule are rolled up into the billing schedule group.

Because the billing schedule group is updated to reflect the positive quantity amendment, no additional action is required. Call /commerce/invoicing/invoices/collection/actions/generate to create the next invoice.