Add Item to a Subscription for Immediate Billing

This guide shows you how to implement the Add Subscription Item endpoint to add an additional item to a subscription and bill it immediately.

Use Case

Add an add-on immediately to an active subscription

Cloudify, a fictitious company, offers monthly cloud storage subscription. Their customer has run out of space and wants to purchase additional GB, available instantly.

To handle this, your system:

Confirms the customer already has an active subscription.
The customer clicks Buy now for the add-on.
Your backend calls the Add Subscription Item endpoint.

Result:

Cleverbridge adds the new item to the existing subscription immediately and the customer is charged instantly.

The customer can use the new feature straight away, and the subscription now includes the additional item.

Before you start

Make sure that:

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.

🚧
Important
Get the customer's consent for changes to subscriptions. To avoid chargebacks and customer inquiries, it is also essential that you coordinate all price increases with Client Experience.
In the European Economic Area (EEA), Strong Customer Authentication (SCA) is required for recurring electronic payments when the amount changes. This means that some of your customers will have to authenticate their payment, which in turn might impact the renewal success rate.
For more information, see Best Practices: Obtain Customer Consent.

📘
Revisions history
When you add a subscription item, a history of revisions is created automatically.

Step 1

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.

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the primary subscription.
`ProductId`	The unique identifier of the product to be added.
`Quantity`	The quantity of the new subscription item.
`AlignmentSettings`	`AlignToCurrentInterval: true` `GetCustomerPricePreviewOnly: true`

Step 2

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.

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the primary subscription.
`ProductId`	The unique identifier of the product to be added.
`Quantity`	The quantity of the new subscription item.
`AlignmentSettings`	`AlignToCurrentInterval: true` `GetCustomerPricePreviewOnly: false`

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.