Decrease Subscription Quantity Example

Let customers decrease the quantity of their assets partway through a subscription. This solution calculates the credit amount using the last negotiated price, creates and activates the negative quantity amendment order, then creates a billing schedule. Finally, the solution generates the next invoice for the updated subscription.

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 reduces 5 licenses, effective September 1. The credit amount is $50/month for 4 months, or $200.
  • The new total amount of the subscription, including the initial purchase and the reduced quantity, is $1,200 - $200 = $1,000.

This diagram illustrates one way to build a negative amendment solution. Information following the diagram provides more context for each step and links to the API reference.

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

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 at $10 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

To create the negative 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.

In adherence with standard business practices, this endpoint reduces past transactions in reverse order, or "last in first out". The most recent positive transaction is reduced first. For example, suppose that a customer purchases 10 licenses at $100 each, then later adds two licenses at $50 each. Finally, the customer reduces the quantity to eight licenses. This endpoint calculates the credit amount of two licenses at $50 and one license at $100.

On August 15, 2022, the customer removes 5 licenses at the last negotiated price. The decrease in quantity takes effect Sept 1, 2022. To create a negative quantity amendment order, set the QuantityDecreasePricingType 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 negative 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 negative 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 reduction in quantity, call /actions/standard/createOrUpdateAssetFromOrder. Use the ID of the negative 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. This asset state period has a quantity of five and a monthly recurring revenue of $50.
  • The amendment asset action indicates that the change in quantity is -5, the change in amount is -200, and the change in MRR is -50.

Amended asset

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

After calling /createBillingScheduleFromOrderItem with the negative quantity amendment order item, a new billing schedule for the reduction of 5 licenses is created, spanning the period from September 1 to December 31. The pending amount of -$200 indicates the amount of the credit. 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 negative quantity amendment, no additional action is required. Call /commerce/invoicing/invoices/collection/actions/generate to create the next invoice.