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

The customer pays $125.00 for a monthly Cloudify Pro subscription.
The customer wants to cancel their current plan.
To keep the customer, the support agent offers a switch to Cloudify Plus with the same features for $100.00 per month, including a free month on Cloudify Plus.
On July 1st, Cloudify Pro ends and Cloudify Plus starts, but no charge is created.
On Aug 1st, Cleverbridge automatically bills the customer for the next Cloudify Plus billing period.

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/><b>June 26th</b><br/>Customer wants to cancel Cloudify Pro&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/>Support Agent offers a switch to Cloudify Plus<br/>including a free 1st month&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/><b>July 1st</b><br/>Free month for Cloudify Plus starts,<br/>no charge is created&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> D(["&nbsp;&nbsp;<br/><b>Aug 1st</b><br/>Cleverbridge charges the customer<br/>for the next billing period&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor