Overview

This guide shows you how to use the Update Subscription Item API endpoint to change the billing interval of a subscription to replace a customer's current subscription with a different subscription product, and provide a free access period to the new subscription.

Use Case

Customer subscribes to Cloudify Pro for a quarterly subscription.
Cloudify launches a new plan called Cloudify Plus with the same features but cheaper. The customer wants to cancel their current plan.
To keep the customer and avoid issuing a refund, the account manager offers to: Switch the customer from Cloudify Pro to Cloudify Plus on the next renewal date (July 1) and give the customer 30 days free on Cloudify Plus.
On July 1, Cloudify Pro ends and Cloudify Plus starts, but no charge is created.
On July 31, Cleverbridge automatically bills the customer for the next Cloudify Plus quarterly period.

For more information on which API endpoint to use, see Guidelines for When to Use UpdateSubscriptionItem vs. UpdateSubscriptionItemPrice.

Update Subscription Item via API

Before you start

Make sure that:

The subscription status is Active
Both products are already set up in the Cleverbridge platform
Both products use the same billing interval (and if replacing an item, the same currency)
Updating the billing interval via Update Subscription Item is supported only for single-item subscriptions and takes effect on the next billing date.
Any changes you apply (price and/or quantity) affect all future billing events unless changed again later.

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

Parameters

To update the customer's subscription data in the Cleverbridge platform, set the parameters in the Update Subscription ItemAPI call to the values listed in the table.

Parameter	Set to Value
`SubscriptionId`	The unique identifier of the primary 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 note below.

📘
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)

Diagram

flowchart LR
  classDef mainColor fill:#ffffff,color:#96C34B,stroke:#96C34B,stroke-width:2px;

  A(["&nbsp;&nbsp;<br/>Cloudify launches a cheaper plan called Cloudify Plus<br/>(same features). Customer wants to cancel Cloudify Pro&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/>To avoid issuing a refund, Cloudify offers to:<br/>Switch from Cloudify Pro to Cloudify Plus on July 1st<br/>and give 30 days free on Cloudify Plus&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/>July 1<br/>Cloudify Pro ends and Cloudify Plus starts,<br/>but no charge is created&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> D(["&nbsp;&nbsp;<br/>July 31<br/>Cleverbridge automatically bills the customer<br/>for the next Cloudify Plus quarterly period&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor