Subscription API Guide

Sharing and Storing Information

Two recommended approaches exist that ensure client applications and Cleverbridge share and use a common unique identifier for each customer, and link subscription purchase data with the appropriate customer:

Provide a unique customer ID to Cleverbridge
At the time of the initial purchase, clients have the option to supply a customer ID value from the client's internal systems to Cleverbridge for use in the Cleverbridge platform. This approach is highly recommended because a client's internal applications can easily interact with customer subscriptions and related data in the Cleverbridge platform, using the customer ID that already exists in the client's internal systems.
Store the subscription identifier created by Cleverbridge
Upon completion of a purchase, Cleverbridge provides a notification to the client that contains data such as the subscription ID and the associated client-supplied customer ID. It is highly recommended that clients save the subscription ID within their own applications for API calls and associated Cleverbridge event notifications.

Several use cases described in the Cleverbridge Documentation use the GetSubscription API to obtain basic information about a subscription at the initial purchase. It is highly recommended that clients save this information because:

Basic subscription information is readily available for internal use.
Unnecessary GetSubscription API calls can be avoided, improving the efficiency of the integration.

Completing Implementation Tasks

Clients can use the checklist below to get started.

Implementation Checklist	Done
Request Subscription API access
Review subscription documentation
Resolve questions with Cleverbridge Client Experience
Create your hosted pages
Complete integration and testing
Test in production

Setting Up Notifications

Cleverbridge provides a comprehensive and powerful set of automated notifications, alerting clients to events such as the creation of new subscriptions or updates to existing subscriptions.

It is important that you understand and utilize Cleverbridge notifications because they are essential to developing an effective and seamless integration between the Cleverbridge platform and your system.

For more information about notifications, see Notification Guide.

Understanding Subscription Billing

By design, updates to subscriptions using the Subscription API and billing with the payment process are completely decoupled from one another. API endpoints such as UpdateSubscriptionItem can be used to trigger the immediate creation of a new purchase in the Cleverbridge payment process. However, a Subscription API call does not wait for, nor is it informed of the result of, the attempt to bill for the purchase.

This decoupling achieves the following:

Subscription API call performance is enhanced.
Online payments that could not be processed are handled automatically.

If a payment could not be processed:

The customer receives the normal notification email, including a link to a page to update credit card information or to change the payment method.
The client receives a notification that a payment was not processed.

If the customer clicks through the notification email to update credit card information or to change the payment method, Cleverbridge re-processes the purchase and calculates the next billing date automatically. Upon successful payment, the client automatically receives a notification that the purchase has been paid.

Understanding Subscription Alignment, Pro-rated Billing, and Preview Prices

Alignment Settings

The following Subscription API endpoint calls are used by clients for subscription add-ons, upgrades, downgrades, and other changes to running subscriptions:

AddSubscriptionItem
AlignSubscriptions
UpdateSubscriptionItem
UpdateSubscriptionItemPrice

Clients can also use these functions to launch landing pages or a Customer Self-Service feature to enable customers to upgrade, increase the quantity, and change their subscription in other ways.

The request of each of these Subscription API endpoints contains a parameter, AlignmentSettings, that is comprised of three sub-parameters:

GetCustomerPricePreviewOnly
AlignToCurrentInterval
ExtendInterval (This is currently only offered for UpdateSubscriptionItem and UpdateSubscriptionItemPrice.)

The response (and result) of the API endpoint call depends on the combination of sub-parameter values passed by the API endpoint call request in the AlignmentSettings parameter. The table below provides details of each combination:

AlignmentSettings Sub-Parameter Values Result

AlignmentSettings Sub-Parameter Values	Result
`AlignToCurrentInterval` = `true` `GetCustomerPricePreviewOnly` = `true` `ExtendInterval` = `false`	No change is made. The API call returns preview prices. For more information, see Preview Prices.
`AlignToCurrentInterval` = `true` `GetCustomerPricePreviewOnly` = `false` `ExtendInterval` = `false`	The subscription is changed as requested in the API call. The billing interval of the new or updated subscription item A subscription item is component of a subscription with its own set of attributes including price, description and feature set. is shortened to align with the billing interval of the existing subscription item. If the price is positive, the customer is billed a pro-rated amount immediately. If the price is negative, then an error message is returned in the API call response.
`AlignToCurrentInterval` = `false` `GetCustomerPricePreviewOnly` = `true` `ExtendInterval` = `false`	No change is made. The API call returns preview prices. For more information, see Preview Prices.
`AlignToCurrentInterval` = `false` `GetCustomerPricePreviewOnly` = `false` `ExtendInterval` = `false`	The subscription is changed as requested in the API call. Since alignment Alignment is the act of consolidating the billing for two separate subscriptions into a single recurring billing event. to the current billing interval was not requested, no immediate billing event is generated and the customer is billed on the next billing date.
`AlignToCurrentInterval` = `true` `GetCustomerPricePreviewOnly` = `true` `ExtendInterval` = `true`	No change is made. The API call returns preview prices. For more information, see Preview Prices.
`AlignToCurrentInterval` = `true` `GetCustomerPricePreviewOnly` = `false` `ExtendInterval` = `true`	The subscription is changed as requested in the API call. The billing interval of the existing subscription item is extended to align with the billing interval of the new or updated subscription item. If the price is positive, the customer is billed a pro-rated amount immediately. If the price is negative, then an error message is returned in the API call response.

AlignToCurrentInterval = true

GetCustomerPricePreviewOnly = true

ExtendInterval = false

No change is made.

The API call returns preview prices. For more information, see Preview Prices.

AlignToCurrentInterval = true

GetCustomerPricePreviewOnly = false

ExtendInterval = false

The subscription is changed as requested in the API call.

The billing interval of the new or updated subscription item A subscription item is component of a subscription with its own set of attributes including price, description and feature set. is shortened to align with the billing interval of the existing subscription item.

If the price is positive, the customer is billed a pro-rated amount immediately. If the price is negative, then an error message is returned in the API call response.

AlignToCurrentInterval = false

GetCustomerPricePreviewOnly = true

ExtendInterval = false

No change is made.

The API call returns preview prices. For more information, see Preview Prices.

AlignToCurrentInterval = false

GetCustomerPricePreviewOnly = false

ExtendInterval = false

The subscription is changed as requested in the API call.

Since alignment Alignment is the act of consolidating the billing for two separate subscriptions into a single recurring billing event. to the current billing interval was not requested, no immediate billing event is generated and the customer is billed on the next billing date.

AlignToCurrentInterval = true

GetCustomerPricePreviewOnly = true

ExtendInterval = true

No change is made.

The API call returns preview prices. For more information, see Preview Prices.

AlignToCurrentInterval = true

GetCustomerPricePreviewOnly = false

ExtendInterval = true

The subscription is changed as requested in the API call.

The billing interval of the existing subscription item is extended to align with the billing interval of the new or updated subscription item.

If the price is positive, the customer is billed a pro-rated amount immediately. If the price is negative, then an error message is returned in the API call response.

Negative Alignment Price

If an API endpoint call sets AlignToCurrentInterval equal to true and the resulting pro-rated billing amount is negative, then an error message is returned (and any requested subscription change is not completed). A negative alignment price occurs under these scenarios:

Item price is to be decreased and item quantity remains the same.
Item quantity is to be decreased and item price remains the same.
Both item price and quantity are to be changed, and the resulting billing amount (price x quantity) is less than the current billing amount.
A negative alignment price is also possible when using AlignSubscriptions if there were overpayments for one of the subscriptions from a prior billing interval.

Preview Prices

If called with GetCustomerPricePreviewOnly = true, then each of these four API endpoints returns in the response all relevant price data, such as the net price, applicable taxes, and gross price, for:

The alignment price (if an immediate change is made)
The renewal price that will be applicable on the next billing date

Clients can display this information to customers so that customers can fully understand what they will be billed in the future and, in the case of alignment, what they will be billed immediately. The six price fields that are returned are as follows:

Field Name	Usage Notes
`AlignmentCustomerGrossPrice`	If tax applies, then `AlignmentCustomerVatPrice` returns the appropriate calculated tax amount. If `AlignToCurrentInterval = false`, then these fields contain zeros, because the previewed change will not be effective immediately (no alignment to the current billing interval).
`AlignmentCustomerVatPrice`
`AlignmentCustomerNetPrice`
`NextBillingCustomerGrossPrice`	These fields reflect the renewal price that will be applicable on the next billing date. If tax applies, then `NextBillingCustomerVatPrice` returns the appropriate calculated tax amount.
`NextBillingCustomerVatPrice`
`NextBillingCustomerNetPrice`

If these API endpoints are called with GetCustomerPricePreviewOnly = false, then these fields contain null values.

Alignment, USA Sales Tax Calculation, and Billing

If the AlignmentSettingsGetCustomerPricePreviewOnly parameter is set to true, and if USA sales tax would apply to the purchase, then the “preview” price returned includes sales tax.

Rollback on Unpaid or Reimbursed Alignment Purchase

When a customer's running subscription is upgraded via the Subscription API, two independent events occur:

The subscription's details are updated in the Cleverbridge platform.
A payment process is initiated to pay for the alignment cost of the upgrade.

Since update and payment processes are decoupled from one another, the subscription's details will be updated in the Cleverbridge platform, even if alignment payment for the upgrade fails. Subscription details also remain changed when alignment payments are refunded or charged back.

If you want to prevent this discrepancy from occurring, and roll back a customer's subscription details after a defined period of time, you can request that a database setting is activated in the Cleverbridge platform. To activate this setting, contact Client Experience.

For more information about alignment payments, see Understanding Subscription Billing.

Understanding Customer Price

Within each Product defined in the Cleverbridge platform, the Base Price tab defines one or more Product price(s); each price includes the following attributes:

Currency (ISO Currency ID)
Taxes (governs how taxes are applied when the Product is purchased)
Price (the price for the associated Currency ID)

The Product price(s) set up in the Cleverbridge platform constitute the default price(s) for the item when it is part of a subscription offering: the following Subscription API endpoints can be used to override the original item price in a customer’s subscription:

AddSubscriptionItem
UpdateSubscriptionItem
UpdateSubscriptionItemPrice

These functions include a CustomerPrice parameter, which consists of the following required subparameters, in the function call response:

Subparameter	Type	Description
`Currency`	string	ISO ID for the currency
`IsGross`	boolean	Determines whether the price is gross or net
`Value`	decimal	The new price amount for the item

The rest of this section discusses the CurrencyId and IsGross subparameters. Understanding these subparameters is required to correctly and effectively use any of the three related API endpoints.

Using the Currency Subparameter

The CurrencyID value passed in the CustomerPrice parameter should always match the currency of the underlying subscription.

If a non-matching currency is passed, then an error message ("'CustomerPrice' currency differs from subscription currency") is returned and any requested subscription change is not completed.

Using the IsGross Subparameter

As mentioned above, the Taxes settings on the Commerce Assistant Base Price tab governs how taxes are applied to a Product purchase.

When using the Subscription API, unless instructed otherwise, you should always set the value of IsGross consistent with the Taxes setting on the Commerce Assistant Base Price tab for the underlying product, as follows:

If taxes should be included in the item price, then the Taxes setting should be Gross and the value of IsGross should be set to True.
If taxes should be added on top of the item price, then the Taxes setting should be Net and the value of IsGross should be set to False.

Important: If IsGross is not set consistently with the Cleverbridge platform Product setup, then the Subscription API can have a major undesired impact on the price paid by the customer and also on client revenue.

The example below illustrates how setting IsGross inconsistently can produce unintended results.

Assume that a product priced at US$15.00 has been set up in the Cleverbridge platform with its Taxes setting set to Net (taxes should be added to the $15.00 price). The following table shows the price calculations resulting from IsGross being set to True compared to False:

Description of price	`IsGross=true` (inconsistent with how the Product is set up in the platform)	`IsGross=false` (consistent with how the Product is set up in the platform)
Product Prices passed in the API Call	$150.00	$150.00
VAT Tax (19% rate)	- 24.00	+ 28.50
Gross Price to Customer	$150.00	$178.50
Gross Amount to Client (before Cleverbridge fee)	$126.00	$150.00

In this example, an update results in lost revenue of $24.00 per item ($150.00 - $126.00).

Notes on US Sales Taxes:

When US sales tax applies, the Taxes setting should always be set to Net and IsGross should be set to False.
US sales tax on the net price is calculated at the time of billing.

Using the Value Subparameter

The CustomerPrice parameter is used to set the per-unit price of the item, not the total price billed for the item. The total (gross or net) price is calculated as CustomerPrice x Quantity.

Flow Charts for Auto-renewal Subscriptions

The following diagram depicts the statuses that can be set for an auto-renewal subscription at the time of the initial purchase, and how the status can change.

sub bill statuses initial purchase

Considerations

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 Subscription API Guide > Understanding Customer Price.
Use of the SubscriptionAlignmentSettings parameter in the API response is required. Before doing so, see Subscription API Guide > Alignment Settings.
If a client adds a subscription item, a history of revisions is created automatically.
When a subscription item is added, the new item must have the same billing interval as the underlying subscription.

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Add Item to a Subscription for Future Billing

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

For more information, see Add Item to a Subscription for Future Billing.

Add Item to a Subscription for Immediate Billing

This use case calls the AddSubscriptionItem function twice as described below.

Preview of pro-rated billing amount (first call)

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

Calculate the pro-rated price to be billed if the subscription item is added
Return the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

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

Addition of the item to the subscription (second call)

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

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

For more information, see Add Item to a Subscription for Immediate Billing .

Add Item at a Custom Price Effective Next Billing Date

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`ProductId`	The unique identifier of the product to be added.
`Quantity`	300
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`CustomerPrice`	`CurrencyId`: `GBP` `IsGross`: `false` `Value`: `35.00`

For more information, see Add Item at a Custom Price Effective Next Billing Date.

Add Custom-Priced Item Immediately

This use case calls the AddSubscriptionItem 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 will:

Calculate the pro-rated price to be billed if the subscription item is added
Return the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

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

Addition of the item to the subscription (second call)

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

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

For more information, see Add Custom-Priced Item Immediately.

Considerations

Changes made by this function, including the price and/or quantity, apply to all future billing events unless changed subsequently.
One of the subscriptions for a given customer must be designated as the primary subscription. The other subscriptions become secondary and align with the billing interval of the primary.
The two subscriptions must have the same billing interval, for example, monthly.
The next billing date of the primary subscription must be greater than the next billing date of the secondary subscription. If this is an issue, clients can simply update the secondary subscription's billing date before aligning the subscriptions.
Note
Updating the secondary subscription billing date could result in lost revenue for the adjusted billing interval.
Both subscriptions must have the status Active.
Both subscriptions must have the same currency type.
Use of the SubscriptionAlignmentSettings parameter in the API response is required. Before doing so, refer to and understand the considerations detailed in Subscription API Guide > Alignment Settings.

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Align Subscriptions

Parameter Set to Value

PrimarySubscriptionId The unique identifier of the primary subscription.

SecondarySubscriptionId The unique identifier of the secondary subscription.

Parameter	Set to Value
`PrimarySubscriptionId`	The unique identifier of the primary subscription.
`SecondarySubscriptionId`	The unique identifier of the secondary subscription.
`AlignmentSettings`	`AlignToCurrentInterval`: `true*` `GetCustomerPricePreviewOnly`: `false`

AlignmentSettings

AlignToCurrentInterval: true*

GetCustomerPricePreviewOnly: false

* To align subscriptions effective at the time of the next billing date, set AlignToCurrentInterval to false.

For more information, see Align Subscriptions

Considerations

Each subscription item must have the status Active.
If all items in a subscription are deactivated, the status of the entire subscription automatically changes to deactivated.

Use Cases

The following are some of the most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Turn Off Automatic Renewal (Subscription Management 1.0)

Parameter	Set to Value
`RunningNumbers`	1 (This subscription has only one item.)
`SubscriptionId`	The unique identifier of the subscription.

For more information, see Turn Off Automatic Renewal

Cancel Part of a Multi-Item Subscription

Parameter	Set to Value
`RunningNumbers`	2,3 (This subscription has three items; the second and third are to be deactivated.)
`SubscriptionId`	The unique identifier of the subscription.

For more information, see Cancel Part of a Multi-Item Subscription

Cancel a Subscription

Parameter	Set to Value
`RunningNumbers`	1 (This subscription has only one item.)
`SubscriptionId`	The unique identifier of the subscription.

For more information, see Cancel a Subscription

Retire Subscriptions for a Discontinued Product

Parameter	Set to Value
`RunningNumbers`	1 (This subscription has only one item.)
`SubscriptionId`	The unique identifier of the subscription.
`GenerateMail`	false
`AllowReinstate`	false

For more information, see Retire Subscriptions for a Discontinued Product

Considerations

None

Use Cases

This endpoint is used in the following use cases. There is only one parameter passed when calling this endpoint, SubscriptionID.

Retrieving the Quantity of Users

The following use cases assume that the current subscription item quantity is being retrieved for display:

To do so:

Call the function as specified above.
In the SubscriptionItem array data returned in the response, locate the single instance in the array for which both of the following statements are true:
- RunningNumber matches the running number of the subscription item for which the quantity is needed.
- The IsCurrent parameter is true.
Retrieve the current quantity for the Users subscription item from this instance of the array.

Considerations

To call this function, pass one (and only one) of the following parameters:
- CustomerId
- CustomerReferenceId
- CustomerMail
If your company is able to securely identify a customer prior to an order, then you can pass your own unique customer identifier to Cleverbridge, and Cleverbridge will store it as CustomerReferenceId for your subsequent use in qualifying certain API endpoint calls (including this one).
The Subscriptionstatus parameter is optional. If it is blank, then information on all subscriptions for the specified customer will be returned. Valid Subscriptionstatus parameters are:

Active (or 1 for JSON)
Deactivated (or 3 for JSON)
Finished (or 4 for JSON)
Grace (or 5 for JSON)
Hold (or 6 for JSON)
New (or 7 for JSON)

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Note

All but one of the use cases below assume that CustomerId is passed. However, each use case could be implemented just as effectively by passing either CustomerReferenceId or CustomerMail.

Retain Customer by Decreasing Subscription Billing Interval

Parameter	Set to Value
`CustomerId`	The unique identifier for the customer.
`CustomerReferenceId`	(blank)
`Subscriptionstatus`	New, Active
`CustomerMail`	(blank)

For more information, see Retain Customer by Decreasing the Subscription Billing Interval.

Update Subscription to Reflect Product Renaming or Rebranding

Parameter	Set to Value
`CustomerId`	The unique identifier for the customer.
`CustomerReferenceId`	(blank)
`Subscriptionstatus`	New, Active
`CustomerMail`	(blank)

For more information, see Update Subscription to Reflect Product Renaming or Rebranding.

Cancel a Subscription

Parameter	Set to Value
`CustomerId`	The unique identifier for the customer.
`CustomerReferenceId`	(blank)
`Subscriptionstatus`	New, Active
`CustomerMail`	(blank)

For more information, see Cancel a Subscription.

Display All Subscriptions for a Customer

Parameter	Set to Value
`CustomerId`	The unique identifier for the customer.
`CustomerReferenceId`	(blank)
`Subscriptionstatus`	Hold
`CustomerMail`	(blank)

For more information, see Customize Subscription Renewal Price and Quantity.

Considerations

None

Use Cases

Use cases vary. The only parameter passed when calling this function is purchaseid.

Considerations

Changes made by this function apply to all future billing events, unless changed subsequently.
Using the SubscriptionAlignmentSettings parameter in the API response is required. Before doing so, see Subscription API Guide > Alignment Settings.

Use Cases

The following are some of the most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Increase Subscription Quantity or Volume Immediately

This use case calls the UpdateSubscriptionItem function twice as described below.

Preview of pro-rated billing amount (first call)

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

Calculate the pro-rated price to be billed if the five additional users are added.
Return the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer).
Not change any data in the Cleverbridge system.

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the users subscription item.
`Quantity`	15 (The new quantity.)
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

Upgrade by increasing quantity (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID associated with the users subscription item.
`Quantity`	15 (The new quantity.)
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Change Subscription Quantity Immediately.

Increase Subscription Quantity or Volume Effective Next Billing Date

This use case calls the UpdateSubscriptionItem function twice as described below.

Preview of pro-rated billing amount (first call)

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

Calculate the pro-rated price to be billed if the five additional users are added.
Return the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer).
Not change any data in the Cleverbridge system.

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the users subscription item.
`Quantity`	15 (The new quantity.)
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

Upgrade by increasing quantity (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID associated with the users subscription item.
`Quantity`	15 (The new quantity.)
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

Considerations

The item must have the status Deactivated.
The item must be a currently available subscription product.

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Turn On Automatic Renewal (Subscription Management 1.0)

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumbers`	1 (This subscription has only one item.)

For more information, see Reactivate a Subscription.

Reactivate a Subscription

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumbers`	1 (This subscription has only one item.)

For more information, see Reactivate a Subscription.

Reactivate a Subscription Retroactively

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumbers`	2 (The second of the two items being reactivated.)

For more information, see Reactivate a Subscription Retroactively.

Offer a Period of Free Service for Reactivating a Subscription

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumbers`	1, 2, 3 (All three items are being reactivated.)

For more information, see Offer a Period of Free Service for Reactivating a Subscription.

Track Performance of a Promotional Campaign for Subscription Customers

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumbers`	1 (This subscription has only one item.)

For more information, see Track Performance of a Promotional Campaign for Subscription Customers.

Considerations

This function should be used rarely and with caution. It deletes the subscription item, and all data associated with it, for every subscription that contains the item. For any future reports, such as reporting on which items customers purchased, the item wouldn't be included.

Tip

It is recommended to use the DeactivateSubscriptionItems API endpoint instead, because it retains the subscription information but prevents future billing for the item.

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Remove Discontinued or Temporary Subscription Item

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumbers`	2 (The second of two items being removed.)

For more information, see Remove Discontinued or Temporary Subscription Item.

Considerations

The call must be made between the start of the current billing interval and the next billing date.
By default, the Cleverbridge platform bills the customer the full price for the next billing interval, which starts immediately. Any remaining time from the current billing interval is added to the next billing interval, moving the next billing date further into the future. If you want to suppress this behavior, set ResetBillingInterval to true.

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Renew a Manual-Renewal Subscription Ahead of Schedule

This use case first calls the UpdateSubscriptionItem function and then the RenewSubscription function as described below.

Preview of price and new expiration date (first call)

The price and and new expiration date are previewed using another API endpoint, see Update Subscription Item.

Renew subscription for another billing interval (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`ResetBillingInterval`	false

For more information, see Renew a Manual-Renewal Subscription Ahead of Schedule.

Renew an Auto-Renewal Subscription Ahead of Schedule

This use case first calls the UpdateSubscriptionItem function and then the RenewSubscription function as described below.

Preview of price and new expiration date (first call)

The price and and new expiration date are previewed using another API endpoint, see Update Subscription Item.

Renew subscription for another billing interval (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`ResetBillingInterval`	false

For more information, see Renew an Auto-Renewal Subscription Ahead of Schedule.

Renew a Data-Limited Subscription Early at Full Price

Step 1: Process renewal for customer

If a customer has a subscription whose data limit has run out, and the customer would like to do the following:

Immediately renew the subscription at the full price so that they can continue using the service

Call the Renew Subscription API endpoint and do the following:

Set ResetBillingInterval to true
Include the customer's SubscriptionId

Cleverbridge immediately processes the renewal using the payment details that we have stored in our database. We immediately bill the customer the full price for the next billing interval. The next billing interval also starts immediately, and the next billing date changes.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/renewsubscription \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "SubscriptionId": "S12345678",
    "ResetBillingInterval": true
  }'

Step 2: Confirm to customer that payment was processed

After receiving the response, forward the customer to the confirmation page The confirmation page is displayed after a customer makes a purchase. The confirmation page contains the order confirmation and delivery information. in the ContinueUrl field. If the transaction is not successful, the page linked in the ContinueUrl field will inform the customer about the next steps, such as updating the payment details in case of a failed payment.

{
  "ContinueUrl":"http://www.cleverbridge.com/2/p/123546-sf78g97sd897g8df"
  "NextBillingDate":"2018-05-15T23:20:50.52+00:00"
  "TransactionStatus":"Success"
  "ResultMessage":"OK"
}

Step 3: Cleverbridge sends you a PaidOrderNotification

Cleverbridge sends you a PaidOrderNotification, which contains information that allows you to map the payment profile and update your local ecosystem (CRM, ERP, etc.). It includes:

subscriptionID - the Cleverbridge subscription ID
renewalType - whether the subscription has an automatic or manual renewal type
intervalNumber - the current billing interval, which for renewals is always 1 or more
nextBillingDate - the next billing date is calculated based on your product settings

{
  "meta": {
    "type": "PaidOrderNotification",
    "date": "2019-03-19T14:47:34.857671",
    "schemaUrl": "https://www.cleverbridge.com/JsonNotificationSchemas/PaidOrderNotification"
  },
  "purchaseId": 123456789,
  ...
  "items": [{
    ...
    "recurringBilling": {
      "subscriptionId": "S12345678",
      ...
      "intervalNumber": 1,
      ...
      "nextBillingDate": "2020-03-19T14:47:34.857671",
      ...
      "renewalType": "Automatic"
      ...
    }],				
  ...
  }
}

For more information, see Renew a Data-Limited Subscription Early at Full Price.

Considerations

Use this endpoint only if you handle subscriptions yourself. By default, Cleverbridge controls the entire subscription process, during which the account updater is automatically triggered.

Required Parameters by Use Case

Use cases vary. There is only one parameter passed when calling this function, SubscriptionId.

Considerations

None

Use Cases

Use cases vary.

Considerations

The customer must have purchased at least one subscription product.
At least one of the subscription products has the status Active.
The ContactType parameter is required. Valid values are:
- LicenseeContact (or 0 for JSON)
- BillingContact (or 1 for JSON)
- DeliveryContact (or 2 for JSON)

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Update Customer Contact Information

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`Contact`	See documentation at Update Contact for complete information
`ContactType`	`Billing`

For more information, see Update Customer Contact Information.

Considerations

The date to which the next billing date is updated must be in the future. If the date must be set to today, set it at least one minute in the future.

Use Cases

This endpoint is used in the following use cases:

Only two parameters are passed when calling this function:

SubscriptionID
NextBillingDate

Guidelines for When to Use UpdateSubscriptionItemPrice vs. UpdateSubscriptionItem

It's possible to use either the UpdateSubscriptionItem or the UpdateSubscriptionItemPrice functions if the only subscription item properties to be changed are the price, the quantity, or both. The following guidelines should be kept in mind when making this decision:

UpdateSubscriptionItemPrice should be used for new development in which only the subscription item’s price and (optionally) quantity will change.
UpdateSubscriptionItem should be used for new development or for modifying existing client code in cases where subscription data in addition to price and (optionally) quantity will be changed.

Considerations

The following are considerations for this function:

Using this API endpoint to change the billing interval of a subscription is only supported for single-item subscriptions (which is the most common type of subscription), and only effective at the time of the next billing date. Otherwise, when one subscription item is replaced with another, the original and the replacement items must have the same currency and 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 Understanding Customer Price.
Use of the SubscriptionAlignmentSettings parameter in the API response is required. Before doing so, see Subscription API Guide > Alignment Settings.
If a client adds a subscription item, a history of revisions is created automatically. It is important to confirm that the current version receives the update.

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Customer Converts from Freemium to Paid Subscription

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the paid product (not the freemium product being replaced).
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Use Case: Customer Converts from Freemium to Paid Subscription

Capture Customer Consent for a Subscription Renewal Price Increase

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the higher priced product (not the current product being replaced).
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Capture Customer Consent for a Subscription Renewal Price Increase.

Change Subscription Renewal Quantity

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the free trial product (not the current Legal Research product being replaced).
`Quantity`	15 (The new quantity.)
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Change Subscription Renewal Quantity.

Renew a Manual-Renewal Subscription Ahead of Schedule

This use case first calls the UpdateSubscriptionItem function and then the RenewSubscription function as described below.

Preview of price and new expiration date (first call)

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

Calculate the next billing date if the renewal is made
Return the next billing date in the NextBillingDate parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the users subscription item.
`Quantity`	1
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`TriggerImmediateRenewal`	`true`

Renew subscription for another billing interval (second call)

The subscription is renewed using another API endpoint, see Renew Subscription.

For more information, see Renew a Manual-Renewal Subscription Ahead of Schedule.

Upgrade a Subscription Immediately

This use case calls the UpdateSubscriptionItem function twice as described below.

Preview of pro-rated billing amount (first call)

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

Calculate the pro-rated price to be billed if the upgrade is made
Return the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the premium plan product (not the current basic plan product being replaced).
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `true`

Upgrade by replacing the basic plan with the premium plan (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the premium plan product (not the current basic plan product being replaced).
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	`See the UpdateAction parameter usage note at the end of this section.`

For more information, see Upgrade a Subscription Immediately.

Upgrade a Subscription Effective Next Billing Date

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the platinum product (not the current gold product being replaced).
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section..

For more information, see Upgrade a Subscription Effective Next Billing Date.

Downgrade a Subscription Effective Next Billing Date

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the 100 gigabyte product (not the current 200 gigabyte product being replaced).
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Downgrade a Subscription Effective Next Billing Date.

Combine an Immediate Upgrade with an Early Renewal (Monthly to Yearly)

This use case calls the UpdateSubscriptionItem function twice as described below.

Preview of price and next billing date (first call)

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

Calculate the next billing date if the renewal is made
Return the next billing date in the NextBillingDate parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the annual plan product (not the current monthly plan product being replaced).
`Quantity`	1
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`TriggerImmediateRenewal`	`true`

Upgrade by replacing the monthly plan with the yearly plan and renew subscription for another billing interval (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the annual plan product (not the current monthly plan product being replaced).
`Quantity`	1
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`TriggerImmediateRenewal`	`true`

For more information, see Combine an Immediate Upgrade with an Early Renewal (Monthly to Yearly).

Combine an Immediate Upgrade with an Early Renewal (Basic to Premium)

This use case calls the UpdateSubscriptionItem function twice as described below.

Preview of price and next billing date (first call)

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

Calculate the next billing date if the renewal is made
Return the next billing date in the NextBillingDate parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the premium plan product (not the current basic plan product being replaced).
`Quantity`	1
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`TriggerImmediateRenewal`	`true`

Upgrade by replacing the basic plan with the premium plan and renew subscription for another billing interval (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the premium plan product (not the current basic plan product being replaced).
`Quantity`	1
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`TriggerImmediateRenewal`	`true`

For more information, see Combine an Immediate Upgrade with an Early Renewal (Basic to Premium).

Combine an Upgrade with an Early Renewal at Full Price

This use case calls the UpdateSubscriptionItem function twice as described below.

Preview of price and next billing date (first call)

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

Calculate the next billing date if the renewal is made
Return the next billing date in the NextBillingDate parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the higher-value plan product (not the current plan product being replaced).
`Quantity`	1
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `true`
`ResetBillingInterval`	`true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`TriggerImmediateRenewal`	`true`

Upgrade by replacing the lower-value plan with the higher-value plan and renew subscription for another billing interval (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the premium plan product (not the current basic plan product being replaced).
`Quantity`	1
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`ResetBillingInterval`	`true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`TriggerImmediateRenewal`	`true`

For more information, see Combine an Upgrade with an Early Full-Price Renewal of a Data-Limited Subscription.

Retain Customer with a Discount

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the customer's subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the current Enterprise Hosting product associated with the subscription item.
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	Type of update. This is used for reporting only. It does not affect the subscription.
`CouponCode`	A coupon code previously set up in the Cleverbridge platform.

For more information, see Retain Customer with a Discount.

Retain Customer by Replacing a Subscription and Providing a Free Access Period

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the free trial product (not the current Legal Research product being replaced).
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Retain Customer by Replacing a Subscription and Providing a Free Access Period.

Retain Customer by Increasing Subscription Billing Interval

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (to change the subscription billing interval, the subscription can only have one item).
`ProductId`	Product ID for the new product (in this use case, it is the ID of the product with an annual billing interval).
`Quantity`	1
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Retain Customer by Increasing the Subscription Billing Interval.

Retain Customer by Decreasing Subscription Billing Interval

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (to change the subscription billing interval, the subscription can only have one item).
`ProductId`	Product ID for the new product (in this use case, it is the ID of the product with a monthly billing interval).
`Quantity`	1
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Retain Customer by Decreasing the Subscription Billing Interval.

Update Subscription to Reflect Product Renaming or Re-branding

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	The running number for the subscription item being changed.
`ProductId`	Product ID for the Users subscription item.
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`ProductName`	The new product name to replace the current one.
`UpdateAction`	See the note at the end of this section.
`ProductNameExtension`	The new product description to replace the current one.

For more information, see Update Subscription to Reflect Product Renaming or Rebranding.

Bill Customer for Usage

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	Product ID for the usage subscription item.
`Quantity`	Quantity of usage.
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Bill Customer for Usage.

Bill Customer for Excess Usage

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	2 (Excess usage is the second of the two subscription items.)
`ProductId`	Product ID for the usage subscription item.
`Quantity`	Quantity of excess usage.
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Bill Customer for Excess Usage.

Bill Usage at a Custom Price

This use case makes two calls:

The first call uses UpdateSubscriptionItemPrice to update the price for the subscription item. For more information, see Update Subscription Item.
The second call, at the end of the billing interval, uses UpdateSubscriptionItem to update the subscription item with the quantity of usage for the billing interval.

Update the quantity of usage (second call)

If the API call is formatted as described below, it will update the subscription item’s price and quantity in the Cleverbridge platform.

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	2 (the Streaming Usage item is the second of two items in the subscription).
`ProductId`	The product ID for the Streaming Usage subscription item.
`Quantity`	1360
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.

For more information, see Bill Usage at a Custom Price.

Co-Terming Subscription Items (Extend Billing Interval of Original Seat)

This use case calls the UpdateSubscriptionItem function twice as described below.

Important

When using the UpdateSubscriptionItem function for this use case, you should not assign values to the CustomerPrice parameter. If you do so, it will overwrite the current product price. Instead, you do the following in the Cleverbridge platform:

Go to Products and select your product.
Under Pricing > Base Price, select Incremental discount in the Volume Pricing Method drop-down menu. For more about this method, see Incremental discount.
In the pricing grid, enter the product pricing. For example, if you are offering the original license for $39.99 and will offer the additional license for $10, you would do the following:
Click Save.

Preview of price and next billing date (first call)

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

Calculate price if the new purchase and renewal are made
Return the next billing date in the NextBillingDate parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the premium plan product (not the current basic plan product being replaced).
`Quantity`	2
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `true` `ExtendInterval:true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`GenerateMail`	`false`

Add additional seat immediately at discounted price (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the premium plan product (not the current basic plan product being replaced).
`Quantity`	2
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `false` `ExtendInterval:true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`GenerateMail`	`true`

For more information, see Co-Terming Subscription Items (Extend Billing Interval of Original Seat).

Co-Terming Subscription Items (Shorten Billing Interval of Additional Seat)

This use case calls the UpdateSubscriptionItem function twice as described below.

Preview of price and next billing date (first call)

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

Calculate price if the new purchase is made
Return the next billing date in the NextBillingDate parameter of the API response (so that it can be provided to the customer)
Not change any data in the Cleverbridge system

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the premium plan product (not the current basic plan product being replaced).
`Quantity`	2
`AlignmentSettings`	`AlignToCurrentInterval`: true `GetCustomerPricePreviewOnly`: `true` `ExtendInterval:false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`GenerateMail`	`false`

Add additional seat immediately at a pro-rated price (second call)

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

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`ProductId`	The product ID for the premium plan product (not the current basic plan product being replaced).
`Quantity`	2
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `false` `ExtendInterval:false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`GenerateMail`	`true`

For more information, see Co-Terming Subscription Items (Shorten Billing Interval of Additional Seat).

Renew a Data-Limited Subscription Early at Custom Price

Step 1: Show customer price of immediate renewal

If a customer has a subscription whose data limit has run out, and the customer would like to do the following:

Immediately renew the subscription at custom price so that they can continue using the service

Call the Update Subscription Item API endpoint to generate a preview of the price that the customer will pay for the renewal. In the API call, do the following:

Submit the SubscriptionId that belongs to the customer's subscription.
Submit the ProductId that belongs to the product.
Set GetCustomerPricePreviewOnly to true in the AlignmentSettings argument and set GenerateMail to false to generate a preview that will not be processed or communicated via email.
Set the price that the customer will pay for the renewal in the CustomerPrice argument.
Set TriggerImmediateRenewal to true to trigger the renewal immediately.
Set ResetBillingInterval to true so that a new billing interval starts immediately.
Set UpdateAction to Update for reporting purposes.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": true
    },
    "CustomerPrice" : {
	  "CurrencyId": USD,
	  "IsGross": true,
	  "Value": 75
    }
    "GenerateMail": false,
    "ProductId": 123456,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval" : true,
    "UpdateAction": "Update"
  }'

For more information about the AlignmentSettings argument, see Alignment Settings.

Step 2: Process upgrade for customer

After the customer confirms the previewed price, set GetCustomerPricePreviewOnly to false in the AlignmentSettings argument and set GenerateMail to true. Call the Update Subscription Item API endpoint again. Cleverbridge will process the upgrade using the payment details that we have stored in our database and send a confirmation email to the customer.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice" : {
      "CurrencyId": USD,
      "IsGross": true,
      "Value": 75
    }
    "GenerateMail": true,
    "ProductId": 123456,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval": true,
    "UpdateAction": "Update"
  }'

Step 3: Cleverbridge sends you a PaidOrderNotification

Cleverbridge sends you a PaidOrderNotification, which contains information that allows you to update your local ecosystem (CRM, ERP, etc.). It includes:

subscriptionID - the Cleverbridge subscription ID
renewalType - whether the subscription has an automatic or manual renewal type
intervalNumber - the current billing interval, which for renewals is always 1 or more
nextBillingDate - the next billing date is calculated based on your product settings

{
  "meta": {
    "type": "PaidOrderNotification",
    "date": "2019-03-19T14:47:34.857671",
    "schemaUrl": "https://www.cleverbridge.com/JsonNotificationSchemas/PaidOrderNotification"
  },
  "purchaseId": 123456789,
  ...
  "items": [{
    ...
    "recurringBilling": {
      "subscriptionId": "S12345678",
      ...
      "intervalNumber": 1,
      ...
      "nextBillingDate": "2020-03-19T14:47:34.857671",
      ...
      "renewalType": "Automatic"
      ...
    }],				
  ...
  }
}

For more information, see Renew a Data-Limited Subscription Early at Custom Price.

Combine Upgrade with an Early Full-Price Renewal of a Data-Limited Subscription

Step 1: Show customer price of the upgrade and immediate renewal

If a customer has a subscription whose data limit has run out, and the customer would like to do the following:

Upgrade to plan with higher data limit
Immediately renew the subscription so that they can continue using the service

Call the Update Subscription Item API endpoint to generate a preview of the price that the customer will pay for the upgrade and renewal. In the API call, do the following:

Submit the SubscriptionId that belongs to the customer's subscription.
Submit the ProductId that belongs to the product that the customer would like to upgrade to.
Set GetCustomerPricePreviewOnly to true in the AlignmentSettings argument and set GenerateMail to false to generate a preview that will not be processed or communicated via email.
Set TriggerImmediateRenewal to true to trigger the renewal immediately.
Set ResetBillingInterval to true so that a new billing interval starts immediately.
Set UpdateAction to Update for reporting purposes.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": true
    },
    "GenerateMail": false,
    "ProductId": 123451,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval" : true,
    "UpdateAction": "Update"
  }'

For more information about the AlignmentSettings argument, see Alignment Settings.

Step 2: Process upgrade for customer

After the customer confirms the previewed price, set GetCustomerPricePreviewOnly to false in the AlignmentSettings argument and set GenerateMail to true. Call the Update Subscription Item API endpoint again. Cleverbridge will process the upgrade using the payment details that we have stored in our database and send a confirmation email to the customer.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": false
    },
    "GenerateMail": true,
    "ProductId": 123451,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval": true,
    "UpdateAction": "Update"
  }'

Step 3: Cleverbridge sends you a PaidOrderNotification

Cleverbridge sends you a PaidOrderNotification, which contains information that allows you to update your local ecosystem (CRM, ERP, etc.). It includes:

subscriptionID - the Cleverbridge subscription ID
renewalType - whether the subscription has an automatic or manual renewal type
intervalNumber - the current billing interval, which for renewals is always 1 or more
nextBillingDate - the next billing date is calculated based on your product settings

{
  "meta": {
    "type": "PaidOrderNotification",
    "date": "2019-03-19T14:47:34.857671",
    "schemaUrl": "https://www.cleverbridge.com/JsonNotificationSchemas/PaidOrderNotification"
  },
  "purchaseId": 123456789,
  ...
  "items": [{
    ...
    "recurringBilling": {
      "subscriptionId": "S12345678",
      ...
      "intervalNumber": 1,
      ...
      "nextBillingDate": "2020-03-19T14:47:34.857671",
      ...
      "renewalType": "Automatic"
      ...
    }],				
  ...
  }
}

For more information, see Combine an Upgrade with an Early Full-Price Renewal of a Data-Limited Subscription.

Combine Upgrade with an Early Custom-Price Renewal of a Data-Limited Subscription

Step 1: Show customer custom price of upgrade and immediate renewal

If a customer has a subscription whose data limit has run out, and the customer would like to do the following:

Upgrade to custom-priced plan with higher data limit
Immediately renew the subscription so that they can continue using the service

Call the Update Subscription Item API endpoint to generate a preview of the price that the customer will pay for the upgrade and renewal. In the API call, do the following:

Submit the SubscriptionId that belongs to the customer's subscription.
Submit the ProductId that belongs to the product that the customer would like to upgrade to.
Set GetCustomerPricePreviewOnly to true in the AlignmentSettings argument and set GenerateMail to false to generate a preview that will not be processed or communicated via email.
Set the price that the customer will pay for the renewal in the CustomerPrice argument.
Set TriggerImmediateRenewal to true to trigger the renewal immediately.
Set ResetBillingInterval to true so that a new billing interval starts immediately.
Set UpdateAction to Update for reporting purposes.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": true
    },
    "CustomerPrice" : {
	  "CurrencyId": USD,
	  "IsGross": true,
	  "Value": 215
    }
    "GenerateMail": false,
    "ProductId": 123451,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval" : true,
    "UpdateAction": "Update"
  }'

For more information about the AlignmentSettings argument, see Alignment Settings.

Step 2: Process upgrade for customer

After the customer confirms the previewed price, set GetCustomerPricePreviewOnly to false in the AlignmentSettings argument and set GenerateMail to true. Call the Update Subscription Item API endpoint again. Cleverbridge will process the upgrade using the payment details that we have stored in our database and send a confirmation email to the customer.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": false
    },
    "CustomerPrice" : {
      "CurrencyId": USD,
      "IsGross": true,
      "Value": 215
    }
    "GenerateMail": true,
    "ProductId": 123451,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": true,
	"ResetBillingInterval": true,
    "UpdateAction": "Update"
  }'

Step 3: Cleverbridge sends you a PaidOrderNotification

Cleverbridge sends you a PaidOrderNotification, which contains information that allows you to update your local ecosystem (CRM, ERP, etc.). It includes:

subscriptionID - the Cleverbridge subscription ID
renewalType - whether the subscription has an automatic or manual renewal type
intervalNumber - the current billing interval, which for renewals is always 1 or more
nextBillingDate - the next billing date is calculated based on your product settings

{
  "meta": {
    "type": "PaidOrderNotification",
    "date": "2019-03-19T14:47:34.857671",
    "schemaUrl": "https://www.cleverbridge.com/JsonNotificationSchemas/PaidOrderNotification"
  },
  "purchaseId": 123456789,
  ...
  "items": [{
    ...
    "recurringBilling": {
      "subscriptionId": "S12345678",
      ...
      "intervalNumber": 1,
      ...
      "nextBillingDate": "2020-03-19T14:47:34.857671",
      ...
      "renewalType": "Automatic"
      ...
    }],				
  ...
  }
}

For more information, see Combine an Upgrade with an Early Custom-Price Renewal of a Data-Limited Subscription.

Combine Downgrade with an Early Full-Price Renewal of a Data-Limited Subscription

Step 1: Show customer price of the downgrade and immediate renewal

If a customer has a subscription whose data limit has run out, and the customer would like to do the following:

Downgrade to plan with lower data limit
Immediately renew the subscription so that they can continue using the service

Call the Update Subscription Item API endpoint to generate a preview of the price that the customer will pay for the downgrade and renewal. In the API call, do the following:

Submit the SubscriptionId that belongs to the customer's subscription.
Submit the ProductId that belongs to the product that the customer would like to downgrade to.
Set GetCustomerPricePreviewOnly to true in the AlignmentSettings argument and set GenerateMail to false to generate a preview that will not be processed or communicated via email.
Set TriggerImmediateRenewal to true to trigger the renewal immediately.
Set ResetBillingInterval to true so that a new billing interval starts immediately.
Set UpdateAction to Update for reporting purposes.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": true
    },
    "GenerateMail": false,
    "ProductId": 123450,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval" : true,
    "UpdateAction": "Update"
  }'

For more information about the AlignmentSettings argument, see Alignment Settings.

Step 2: Process downgrade for customer

After the customer confirms the previewed price, set GetCustomerPricePreviewOnly to false in the AlignmentSettings argument and set GenerateMail to true. Call the Update Subscription Item API endpoint again. Cleverbridge will process the downgrade using the payment details that we have stored in our database and send a confirmation email to the customer.

curl --request POST \
  --url https://rest.cleverbridge.com/subscription/updatesubscriptionitem \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "AlignmentSettings": {
      "AlignToCurrentInterval": false,
      "ExtendInterval": false,
      "GetCustomerPricePreviewOnly": false
    },
    "GenerateMail": true,
    "ProductId": 123450,
    "Quantity": 1,
    "RunningNumber": 1,
    "SubscriptionId": "S12345678",
    "TriggerImmediateRenewal": true,
    "ResetBillingInterval": true,
    "UpdateAction": "Update"
  }'

Step 3: Cleverbridge sends you a PaidOrderNotification

Cleverbridge sends you a PaidOrderNotification, which contains information that allows you to update your local ecosystem (CRM, ERP, etc.). It includes:

subscriptionID - the Cleverbridge subscription ID
renewalType - whether the subscription has an automatic or manual renewal type
intervalNumber - the current billing interval, which for renewals is always 1 or more
nextBillingDate - the next billing date is calculated based on your product settings

{
  "meta": {
    "type": "PaidOrderNotification",
    "date": "2019-03-19T14:47:34.857671",
    "schemaUrl": "https://www.cleverbridge.com/JsonNotificationSchemas/PaidOrderNotification"
  },
  "purchaseId": 123456789,
  ...
  "items": [{
    ...
    "recurringBilling": {
      "subscriptionId": "S12345678",
      ...
      "intervalNumber": 1,
      ...
      "nextBillingDate": "2020-03-19T14:47:34.857671",
      ...
      "renewalType": "Automatic"
      ...
    }],				
  ...
  }
}

For more information, see Combine a Downgrade with an Early Full-Price Renewal of a Data-Limited Subscription.

Note

The UpdateAction parameter is currently used for documentation and tracking only. The value set does not affect transaction processing.

The supported values are as follows:

For upgrades, set the parameter to upgrade(or 1 for JSON)
For downgrades, set the parameter to downgrade, (or 2 for JSON)
For all other changes, set the parameter to update (or 0 for JSON)

Considerations

The following are considerations for this function:

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 required. Before doing so, see Understanding Customer Price.
Use of the SubscriptionAlignmentSettings parameter in the API response is required. Before doing so, see Subscription API Guide > Alignment Settings.

Guidelines for When to Use UpdateSubscriptionItemPrice vs. UpdateSubscriptionItem

It’s possible to use either the UpdateSubscriptionItem or the UpdateSubscriptionItemPrice functions if the only subscription item properties to be changed are the price, the quantity, or both. Keep in mind the following guidelines when making this decision:

UpdateSubscriptionItemPrice should be used for new development in which only the subscription item’s price and (optionally) quantity will change.
UpdateSubscriptionItem should be used for new development or to modify existing client code in cases where, in addition to price and (optionally) quantity, subscription data will be changed as well.

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Customize Subscription Renewal Price

This use case initially calls GetSubscription to retrieve details for the customer’s subscription. To change the subscription in the Cleverbridge platform, UpdateSubscriptionItemPrice is called with the following parameter values:

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (it is assumed that the seats item is the only item in the subscription).
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`CustomerPrice`	`CurrencyId`: `HUF` `IsGross`: `true` `Value`: `1950.00`

For more information, see Customize Subscription Renewal Price.

Customize Subscription Renewal Price and Quantity

This use case initially calls GetSubscription to retrieve details for the customer’s subscription. To change the subscription in the Cleverbridge platform, UpdateSubscriptionItemPrice is called with the following parameter values:

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (it is assumed that the seats item is the only item in the subscription).
`Quantity`	300
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`CustomerPrice`	`CurrencyId`: `CHF` `IsGross`: `true` `Value`: `24.95`

For more information, see Customize Subscription Renewal Price and Quantity.

Make Renewal Quantity and Quantity-Based Price Changes

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (it is assumed that the Desktop License item is the only item in the subscription).
`Quantity`	800
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`CustomerPrice`	`CurrencyId`: `EUR` `IsGross`: `true` `Value`: `20.00`

For more information, see Make Renewal Quantity and Quantity-based Price Changes.

Change Subscription Price Immediately

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (it is assumed that the license item is the only item in the subscription).
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`CustomerPrice`	`CurrencyId`: `USD` `IsGross`: `false` `Value`: `12.00`

For more information, see Change Subscription Price Immediately.

Make Quantity and Quantity-Based Price Changes Immediately

This use case calls the UpdateSubscriptionItemPrice function twice as described below.

The first time, to obtain the pro-rated price reflecting the combined price and quantity change for the subscription item.
The second time, to update the subscription item in the customer’s subscription.

Preview of pro-rated billing amount (first call)

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

Calculate the pro-rated billing amount if the subscription item is updated.
Return the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer).
Not change any data in the Cleverbridge system.

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (it is assumed that the user accounts item is the only item in the subscription).
`Quantity`	40
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `true`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`CustomerPrice`	`CurrencyId`: `USD` `IsGross`: `true` `Value`: `10.00`

Update the subscription item (second call)

If the API call is formatted as described below, it will update the subscription item’s price and quantity in the Cleverbridge platform.

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (it is assumed that the user accounts item is the only item in the subscription).
`Quantity`	40
`AlignmentSettings`	`AlignToCurrentInterval`: `true` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`CustomerPrice`	`CurrencyId`: `USD` `IsGross`: `true` `Value`: `10.00`

For more information, see Make Quantity and Quantity-Based Price Changes Immediately.

Update Existing Subscription with New Product Pricing

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`RunningNumber`	1 (This subscription has only one item.)
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	Type of update. This is used for reporting only. It does not affect the subscription.
`GenerateMail`	false
`ForcePriceRecalculation`	true

For more information, see Update Existing Subscription with New Product Pricing.

Bill Usage at a Custom Price

This use case makes two calls:

The first call uses UpdateSubscriptionItemPrice to update the price for the subscription item.
The second call, at the end of the billing interval, uses UpdateSubscriptionItem to update the subscription item with the quantity of usage for the billing interval, see Update Subscription Item.

Update the price (first call)

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

Calculate the pro-rated billing amount if the subscription item is updated.
Return the pro-rated billing amount in the AlignmentCustomerGrossPrice parameter of the API response (so that it can be provided to the customer).
Not change any data in the Cleverbridge system.

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	2 (the Streaming Usage item is the second of two items in the subscription).
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`CustomerPrice`	`CurrencyId`: `USD` `IsGross`: `true` `Value`: `5.75`

For more information, see Bill Usage at a Custom Price.

Bill Usage using Quantity-Based Pricing

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RunningNumber`	1 (it is assumed that the messages item is the only item in the subscription).
`Quantity`	78,421
`AlignmentSettings`	`AlignToCurrentInterval`: `false` `GetCustomerPricePreviewOnly`: `false`
`UpdateAction`	See the `UpdateAction` parameter usage note at the end of this section.
`CustomerPrice`	`CurrencyId`: `JPY` `IsGross`: `false` `Value`: `0.50`

For more information, see Bill Usage using Quantity-Based Pricing.

Note

The UpdateAction parameter is currently used for documentation and tracking only. The value set does not affect transaction processing.

The supported values are as follows:

For upgrades, set the parameter to upgrade (or 1 for JSON)
For downgrades, set the parameter to downgrade (or 2 for JSON)
For all other changes, set the parameter to update (or 0 for JSON)

Considerations

The following are considerations for this function:

Only subscription parameters can be updated.
The updated parameters affect the next billing interval, not data from the past.

Use Cases

The following are some most common use cases for this endpoint. To achieve a particular use case, set the parameters in the API call to the values listed in the tables.

Track Performance of a Promotional Campaign for Subscription Customers

Parameter	Set to Value
`SubscriptionId`	The unique identifier for the subscription.
`Items`	`x-promotion=25off`

For more information, see Track Performance of a Promotional Campaign for Subscription Customers.

Subscription API Guide

Important

Getting Started with the Subscription API

Add Subscription Item

Align Subscriptions

Deactivate Subscription Items

Important

Get Subscription

Get Subscriptions for Customer

Get Subscription by Purchase

Increase Subscription Item Quantity

Reinstate Subscription Items

Remove Subscription Item

Warning

Renew Subscription

Update Account

Update Internal Customer ID

Update Contact

Update Next Billing Date

Update Subscription Item

Tip

Update Subscription Item Price

Update Subscription Parameters

Update Subscription Renewal Type

Important

Considerations

Use Cases

Turn Off Automatic Renewal

Turn On Manual Renewal

Sorry about that

Great!

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the subscription.
`RenewalType`	`Manual`