Add Custom-Priced Item Immediately

Add an item immediately at a custom price. This generates customer billing for the pro-rated price of the new item. The subscription is updated with the new item, and in the next billing interval, the new item's price is included in the amount to be billed.

Preconditions and Considerations

• The subscription has the status Active.
• All items in a subscription have the same billing interval.
• Changes made by this function, including the price and/or quantity, apply to current and all future billing events unless changed subsequently.
• Use of the CustomerPrice parameter in the API response is optional. Before doing so, see Understand Customer Price.
• Use of the SubscriptionAlignmentSettings parameter in the API response is required. Before doing so, see Get Started with Subscription API > Alignment Settings.
• When you add a subscription item, a history of revisions is created automatically.

Description

1. On March 15th, a client emails existing customers of its High-Frequency Trading subscription product. The email alerts customers that five new add-ons are now available at special introductory pricing.

2. On March 16th, a customer clicks a link in the email and is redirected to a client-hosted landing page that uses the Get Subscription endpoint to display details about their High-Frequency Trading subscription. The page also displays the following information regarding the five new add-ons:

   Click the checkbox next to each desired service

   Add-On Service	Monthly	Special Introductory Pricing!
   ☐ Service 1	$10	Select any 3 services for $24.99/month ($8.33 each)
   ☐ Service 2	$10
   ☐ Service 3	$10	Select any 4 services for $30/month ($7.50 each)
   ☐ Service 4	$10
   ☐ Service 5	$10	Select all 5 services for $35/month ($7.00 each)

3. The customer selects Service 1, Service 2, and Service 4, and clicks a "Calculate Prices" button on the page to view a preview of the amounts to be billed.

4. The page uses the Add Subscription Item endpoint to calculate the pro-rated price for the selected subscription items between March 16th and the subscription’s March 28th renewal date, and then displays the pro-rated price and renewal price to the customer:

   • Pro-rated price for the 3 services selected (to be billed immediately): $11.66
   • Renewal price for the 3 services selected (to be billed on March 28th): $24.99

5. After reviewing this information, the customer confirms this purchase by clicking a "Buy Now" button on the page. The client's landing page uses the Add Subscription Item endpoint to update the subscription details in the Cleverbridge platform. The same day, the Cleverbridge platform automatically bills the customer $11.66, the pro-rated cost of the added items for the remainder of the current billing interval.

6. On March 28th, the customer's next billing date, the Cleverbridge platform automatically bills the customer $124.99, which is the sum of $100 for High-Frequency Trading, $8.33 for Service 1, $8.33 for Service 2, and $8.33 for Service 4.

This use case calls the Add Subscription Item endpoint multiple times as described below:

• Three times to obtain the pro-rated price for each of the three subscription items.
• Three times to add each of the three subscription items to the customer’s subscription.

Preview of pro-rated billing amount (first call)

If the API call is formatted as described below, it behaves as follows:

• Calculates the pro-rated price to be billed if the subscription item is added.
• Returns the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer).
• Does not change any data in the Cleverbridge system.

Addition of the item to the subscription (second call)

If the API call is formatted as described below, it updates the customer's subscription data in the Cleverbridge platform.

Options

Although not utilized in this use case, the following option is also available:

• Reduce the price of the selected subscription items by applying a discount coupon that was set up in the Cleverbridge platform.

🚧

Important

Get the customer's consent for changes to subscriptions. For more information, see Best Practices: Obtain Customer Consent.

Illustration