Add Item to a Subscription for Future Billing

Add an additional item to a subscription, but do not bill it until the next interval of the first item. No purchase is created for 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. You control whether your customer can access the additional item before it is billed.

Preconditions and Considerations

  • The subscription has the status Active.
  • All items in a subscription must have the same billing interval.
  • Changes made by this function, including the price and/or quantity, apply to 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.


  1. On March 12th, a customer's HDSM (High-Definition Streaming Movie) subscription renews for $5.95 for the new weekly billing interval.
  2. On March 15th, the client emails HDSM customers to inform them of a new service, LSE (Live Sporting Event), that can be added to a subscription for $3 weekly.
  3. On March 16th, the customer clicks a link in the email and is redirected to a landing page that uses the Get Subscription endpoint to display details about the HDSM subscription.
  4. The customer clicks the Buy Now button on the landing page to add LSE to the subscription. The client's landing page uses the Add Subscription Item endpoint to update the subscription details in the Cleverbridge platform.
  5. On March 19th, the customer's next billing date, the Cleverbridge platform automatically bills the customer $8.95, which is the sum of $5.95 for HDSM and $3 for LSE.

To achieve this particular use case, set the parameters in the Add Subscription Item API call to the values listed in the table.

ParameterSet to Value
SubscriptionIdThe unique identifier of the primary subscription.
ProductIdThe unique identifier of the product to be added.
QuantityThe quantity of the new subscription item.
AlignmentSettingsAlignToCurrentInterval: false
GetCustomerPricePreviewOnly: false


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

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