Extend Billing Interval of the Original Seat

You can co-term co-term subscription items by extending the billing interval of the original seat. The following contains relevant information about this use case:

👍

Tip

It is possible to use either the /updatesubscriptionitem or the /updatesubscriptionitemprice resource if the only subscription item properties to be changed are the price, the quantity, or both. However, /updatesubscriptionitem should be used for new developments or for modifying existing code in cases where other subscription data, in addition to price and (optionally) quantity, are changed. Whereas, /updatesubscriptionitemprice should be used for new developments in which only the subscription item's price and (optionally) quantity are changed.

Considerations

• The subscription has the status Active.
• 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).
• When replacing one subscription item with another, the original and the replacement items must have the same currency and billing interval.
• The price update takes place on the next renewal date.
• Any changes made, including the price and/or quantity, apply to current and all future billing events unless modified subsequently.
• Use of the CustomerPrice parameter in the API response is optional. Before doing so, see Understand Customer Price.
• Use the AlignmentSettings parameter for the subscription in the API response is required. Before doing so, see Get Started with Subscription API > Alignment Settings.
• If you add a subscription item, a history of revisions is created automatically. It is important to confirm that the current version receives the update.

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

Timeline

Description

1. On January 1st, 2018, a customer signs up for your CRM service and receives one seat for $40 per year.

2. On July 1st, 2018, the customer, now fully satisfied with the CRM service, receives a promotional email where an additional seat can be purchased at a discounted price - $10 for a one-year seat - if the customer renews their existing seat immediately.
3. The customer clicks on the link in the email and is taken to your Customer Self-Service page. The page uses the Update Subscription Item API endpoint to obtain and display the price of the additional seat ($10), in combination with the pro-rated cost of extending the existing seat by 6 months ($20). The next billing date for both seats is also shown (July 1st, 2019).
4. After reviewing this information, the customer confirms this purchase by clicking a Buy Now button. The page uses the Update Subscription Item API endpoint to immediately extend the existing seat and add the additional seat at the discounted price.
5. The Cleverbridge platform bills the customer a total of $30 for the extended seat ($20) and the additional seat ($10). An additional 6 months are added to the interval of the existing seat, moving the next billing date for both seats to July 1st, 2019.

6. The customer sees a confirmation page, which is linked from a URL provided by Update Subscription Item API endpoint. If the transaction is not successful, the page provided by the API will inform the customer about the next steps, such as updating the payment details in case of a failed payment.
7. On July 1st, 2019, the customer is automatically charged $50 to renew the seats ($40 for the original seat and $10 for the additional seat).

🚧

Important

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

This use case calls the Update Subscription Item API endpoint twice as described below:

🚧

Important

When using the UpdateSubscriptionItem function for this use case, you should not assign values to the CustomerPrice parameter. If you do so, it will overwrite the current product price. Instead, you do the following in the Cleverbridge platform:

1. Go to Products and select your priduct.
2. Under Pricing > Base Price select Incremental discount in the Volume Pricing Method drop-down menu. For more information, see Incremental Discount.
3. In the pricing grid, enter the product pricing. For example, if you are offering the original license for $39.99 and will offer the additional license for $10, you would do the following:

4. Click Save & Close.

Preview of price and next billing date (first call)

If the API call is formatted as described below, it will:

• Calculate price if the new purchase and renewal are made
• Return the next billing date in the NextBillingDate parameter of the API response (so that it can be provided to the customer)
• Not change any data in the Cleverbridge system

Add additional seat immediately at a discounted price (second call)

If the API call is formatted as described below, it will update the customer's subscription data in the Cleverbridge platform.

📘

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)

Illustration