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

To retain customers, you can replace a customer's current subscription with a different subscription product, and provide a free access period to the new subscription.

Preconditions and Considerations

  • The subscription has the status Active.
  • Both products are set up in the Cleverbridge platform.
  • Both products have the same billing interval.
  • 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.
  • 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 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.
  • 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.
  • 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.

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


  1. On January 1st, a customer purchases a client’s cloud-based PaymentsLaw legal research service, paying $5,000 for a subscription that renews quarterly.
  2. On June 24th, the client introduces the new subscription product ComplianceShield with identical functionality but priced at $3,500 quarterly. Due to this price difference, the customer contacts an account manager to cancel.
  3. The account manager accesses an internal application that uses the Get Subscription API endpoint to retrieve customer’s subscription details, including the next billing date.
  4. To retain the customer and to avoid a refund, the account manager offers to:
    • Replace the PaymentsLaw subscription with the ComplianceShield subscription effective on the renewal date of July 1st.
    • Provide free access to ComplianceShield for the first 30 days.
  5. The customer accepts this offer, so the account manager updates the subscription in the Cleverbridge platform using the internal application, making the following changes:
    • Replace the PaymentsLaw subscription with the ComplianceShield subscription, effective on the next renewal date (July 1st). This change utilizes the Update Subscription Item API endpoint.
    • Provide free access to ComplianceShield for the first 30 days. This change utilizes the Update Next Billing Date API endpoint.
  6. On July 1st, the PaymentsLaw subscription ends and the ComplianceShield subscription begins. No billing is generated at this time.
  7. On July 31st, the Cleverbridge platform automatically bills the customer $3500 for ComplianceShield's new quarterly billing interval.

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.

ParameterSet to Value
SubscriptionIdThe unique identifier of the primary subscription.
RunningNumber1 (This subscription has only one item.)
ProductIdProduct ID for the free trial product (not the current Legal Research product being replaced).
AlignmentSettingsAlignToCurrentInterval: false
GetCustomerPricePreviewOnly: false
UpdateActionSee the note below.



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)


Although not utilized in this use case, the following option is also available:

  • Apply a discount coupon that was set up in the Cleverbridge platform to reduce the price of the free trial subscription after the first billing interval.



Get the customer's consent for changes to subscriptions. For more information, see Best Practices: Obtain Customer Consent.

Manage upgrades and downgrades. For more information, see Best Practices: Manage Upgrades and Downgrades.