Overview

This guide shows you how to implement the Update Subscription Item endpoint to offer a discount by adding a coupon code.

The discount will apply to future billing events starting from the next billing date.

Use case

A Cloudify customer contacts support and says they want to cancel their subscription.

To retain the customer, a Cloudify support agent offers a discount for the subscription—either as a one-time retention offer or as an ongoing reduced price. Since the discount coupon is already configured in the Cleverbridge platform, the agent applies it directly to the customer’s subscription.

Cloudify then calls the Update Subscription Item endpoint and sets the CouponCode in the request. The discount will take effect on the next billing date and will apply to all future billing events unless the coupon is removed or replaced.

Considerations

Single-item subscriptions only
Takes effect on next billing event
Discount remains until removed/changed
Coupon must already exist in platform

Implement Update Subscription Item

Before you start

Make sure that:

the subscription's status is Active.
the subscription has one item
the coupon code is set in the Cleverbridge platform

Parameters

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

Parameter	Type	Example	Notes
SubscriptionId	str	284947	The unique identifier for the customer's subscription.
ProductId	int	29899	Product ID for the current Enterprise Hosting product associated with the subscription item.
Quantity	int	1	Total number of items after the update.
RunningNumber	int	1	Current number of subscription items.
UpdateAction	str	upgrade	Used for documentation and tracking only. The value set does not affect transaction processing. See the Note below.
AlignmentSettings	obj	`AlignToCurrentInterval: false` `GetCustomerPricePreviewOnly: false`	Define the behavior when adding or updating a subscription item
CouponCode	str	YTY-DYT-F4A	Coupon code for a promotion

📘
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/>A Cloudify customer contacts support<br/>to cancel their subscription&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> B(["&nbsp;&nbsp;<br/>A Cloudify support agent offers a discount<br/>&nbsp;"]):::mainColor
    --> C(["&nbsp;&nbsp;<br/>Cloudify calls <i>Update Subscription Item</i><br/>and sets the Coupon Code in the request&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor
    --> D(["&nbsp;&nbsp;<br/>The discount takes effect<br/>on the next billing date&nbsp;&nbsp;<br/>&nbsp;"]):::mainColor