Overview

This guide shows you how to implement Add Subscription Item endpoint to offer an add-on at time of renewal, with volume-based or other special pricing.

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.

Use Case

An enterprise Cloudify customer has an active base subscription for their organization and needs additional storage for 300 users. To retain the customer, Cloudify offers Cloudify Extra Storage at a custom price of 35.00 GBP per user per billing interval.

The extra storage is added as an additional item to the customer’s existing subscription with a quantity of 300 and the agreed custom price. No separate subscription is created. The base subscription is updated to include the new item, and the total amount is calculated and billed according to the subscription’s billing interval.

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

Parameters

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.

Parameter	Type	Required	Example
`SubscriptionId`	str	Yes	The unique identifier of the primary subscription.
`ProductId`	int	Yes	The unique identifier of the product to be added.
`Quantity`	int	Yes	`300`
`AlignmentSettings`	obj	No	`AlignToCurrentInterval: false` `GetCustomerPricePreviewOnly: false`
`CustomerPrice`	obj	No	`CurrencyId: GBP` `IsGross: false` `Value: 35.00`