Positive Quantity Amendment Solution

Let customers purchase more of what they've bought by increasing the quantity of their assets partway through a subscription. This solution calculates the price of the quantity increase, creates and activates the positive quantity amendment order, then creates a billing schedule. Finally, the solution generates the next invoice for the updated order.

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.

Positive Quantity Amendment Solution

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.

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

Initial asset object model

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.

Initial billing schedule

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.

Example: Create a Positive Quantity Amendment Order on August 15, 2022

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.

Amended order item

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.

Example: Update the Asset to Reflect the Positive Quantity Amendment

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.
  • 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.

Amended asset

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.

Example: Update the Billing Schedule Group to Reflect the Increase in Quantity

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.

Amended billing schedule

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.