Add Item to a Subscription for Immediate Billing

Add an additional item to a subscription and bill it immediately.

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

A client offers a subscription product that consists of two items:

• Research Portal: $2,500 yearly
• Live Feed (optional premium content): $1,000 yearly

1. On January 1st, a customer purchases the Research Portal subscription item.
2. On May 18th, the customer logs into the client-hosted account management page. The customer selects the option to add the Live Feed subscription item to the subscription.
3. The account management page uses the Add Subscription Item endpoint to calculate the pro-rated price for Live Feed for the remainder of the current billing interval and displays the price and subscription details to the customer.
4. The customer confirms the addition of Live Feed, submitting the order.The account management page uses the Add Subscription Item endpoint to add Live Feed to the subscription in the Cleverbridge platform.
5. On the same day, the Cleverbridge platform automatically bills the customer $616.45 for Live Feed, which is the pro-rated amount for the 225 days remaining in the billing interval.
6. On January 1st, the Cleverbridge platform automatically bills the customer $3,500 for the new billing interval.

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

Preview of pro-rated billing amount (first call)

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

• 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 options are also available:

• Reduce the price of the Live Feed subscription item by applying a discount coupon that was set up in the Cleverbridge platform.
• Suppress generation of the confirmation email to the customer for adding the Live Feed item.
• Change the product name or the product's additional name information for the subscription.

🚧

Important

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

Illustration