Overview

Change a subscription’s billing interval from longer to shorter, effective on the next billing date.

Use Case

1. A Cloudify customer is due to renew an annual subscription on June 1st, but the total renewal cost is too high because their number of seats has increased.
2. The customer contacts their Cloudify account manager to discuss options.
3. To reduce the upfront cost, Cloudify proposes switching the subscription from annual billing to monthly billing.
4. The customer agrees and provides consent.
5. The account manager updates the subscription in the internal platform (based on Update Subscription Item), and on June 1st the customer is billed the new monthly amount instead of the full annual renewal.

Update Subscription Item via API

Before you start

Make sure that:

• The subscription has the status Active

• The subscription contains only one item

• Using the Update Subscription Item 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.

Other considerations

• Changes made by this function, including the price and/or quantity, apply to all future billing events unless changed subsequently.

• When you add a subscription item, a history of revisions is created automatically. It is important to confirm that the current version receives the update.

• Use of the CustomerPrice parameter in the API response is optional. Before doing so, see Understand Customer Price.

• Use of the AlignmentSettings parameter for the subscription in the API response is required. Before doing so, see Get Started with Subscription API > Alignment Settings.

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

Step 1: Retrieve the customer's current subscription details (first call)

To call the Get Subscriptions for Customer endpoint, pass one (and only one) of the following parameters: CustomerId or CustomerReferenceId or CustomerEmail.

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

Parameters

The Subscriptionstatus parameter is optional. If it is blank, information on all subscriptions for the specified customer is returned. The Subscriptionstatus parameter takes the following string values (and returns a corresponding integer in a JSON response):

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

Step 2: Change the annual subscription to a monthly subscription (second call)

Call the Update Subscription Item API endpoint to update the customer's subscription data in the Cleverbridge platform.

Parameters

📘

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)

Usage Notes

Changing the billing interval of a customer’s subscription is achieved by setting up two products in the Cleverbridge platform, one for each of the two billing intervals. Usually, these products are functionally identical to each other, but are not required to be.

Diagram

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

  A(["&nbsp;&nbsp;<br/>Annual subscription due:<br/>Total renewal cost too high&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/>Cloudify proposes switching the subscription<br/>from annual billing to monthly billing&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/>Customer is billed the new monthly amount<br/>instead of the full annual renewal&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor