v1

latestOpenAPI 3.0.02026-07-2636111249.2 KB

Subscription API

Update Subscription Item

Modifies an existing subscription or creates a preview of a modified subscription. You can add a coupon code, adjust the quantity of a subscription item, bill a customer in arrears for usage, replace one product with another product, change the product name, and even change the billing interval of a subscription (by exchanging the product). This endpoint also allows you to update the price of an item. For XML examples and schemas, see the Additional Examples - Update Subscription Item.

post/subscription/updatesubscriptionitem

Headers

Accept'application/json' | 'application/xml'

Expected response format.

Content-Type'application/json' | 'application/xml'

Format of the HTTP post body.

Request body

CouponCodestring

Coupon code for a promotion. The customer will be given a discount on the next renewal or a future renewal, depending on the configuration of the coupon code.

GenerateMailboolean

Set to <code>false</code> if you want to suppress the automatically generated email that informs the customer about the subscription update. Important: If set to <code>false</code>, you must send the email yourself. For more information, see Best Practices: Obtaining Customer Consent.

ProductIdinteger required

ID of the new product you want to replace the existing product with.

ProductNamestring

New product name to be used in customer communication.

ProductNameEnstring

New English product name. Only used in internal communication and for reporting purposes.

ProductNameExtensionstring

New product description. Corresponds to the Additional name information in the Cleverbridge platform.

Quantityinteger required

Total number of items after the update. If you want to only increase the item quantity, use <code>/subscription/increasesubscriptionitemquantity</code> instead.

RecommendationsetIdinteger

ID of the 'recommendation set' to which the product belongs. Corresponds to the Recommendation ID in the Cleverbridge platform. Used for reporting purposes only.

RunningNumberinteger required

Running number of the item in the subscription.

SubscriptionIdstring required

Unique ID of the subscription, with or without an initial 'S'.

TriggerImmediateRenewalboolean

Triggers a renewal immediately. As a result, it also extends the next billing cycle by remaining time of current cycle. You should use this with caution because it is not a standard action for subscription upgrades. Renewals are allowed between start of current billing interval and next billing date. For more information, see Renew a Manual-Renewal Subscription Ahead of Schedule.

ResetBillingIntervalboolean

Set to <code>true</code> to immediately start the new billing interval. If you use this option, you must also set TriggerImmediateRenewal to <code>true</code>. Can be used when the customer has reached their data limit and you want to offer them to upgrade to a higher-value plan. For more information, see Combine an Upgrade with an Early Renewal at Full Price.

UpdateAction'Update' | 'Upgrade' | 'Downgrade' required

Type of update. This is used for reporting only. It does not affect the subscription.

ForcePriceRecalculationboolean

Set to <code>true</code> if you want to update the price of the subscription item based on the current product price. You can use the parameter independent of any other price-relevant updates, such as a quantity or product change. For more information, see Use Case: Update Existing Subscription with New Product Pricing.

Response

ContinueUrlstring

URL of web page with transaction details or payment instructions.

NextBillingDatestring date-time

Next billing date and time according to RFC3339. Specified in UTC.

NextRenewalDatestring date-time

Next renewal date and time according to RFC3339. Specified in UTC.

TransactionStatusstring

Status of the renewal transaction. Possible values are <code>Success</code>, <code>Error</code>, <code>Rejected</code>, <code>Pending</code>, <code>Unknown</code>. See Transaction Status for explanations to those values.

AlignmentCustomerGrossPricenumber double

Total gross price for alignment interval. Only for <code>CustomerPricePreview-Mode</code>.

AlignmentCustomerNetPricenumber double

Total net price for alignment interval. Only for <code>CustomerPricePreview-Mode</code>.

AlignmentCustomerVatPricenumber double

Total VAT amount for alignment interval. Only for <code>CustomerPricePreview-Mode</code>.

NextBillingCustomerGrossPricenumber double

Total gross price for next billing interval. Only for <code>CustomerPricePreview-Mode</code>.

NextBillingCustomerNetPricenumber double

Total net price next billing interval. Only for <code>CustomerPricePreview-Mode</code>.

NextBillingCustomerVatPricenumber double

Total VAT amount for next billing interval. Only for <code>CustomerPricePreview-Mode</code>.

NextRenewalCustomerGrossPricenumber double

Total gross price for next subscription interval. Only for <code>CustomerPricePreview-Mode</code>.

NextRenewalCustomerNetPricenumber double

Total net price next subscription interval. Only for <code>CustomerPricePreview-Mode</code>.

NextRenewalCustomerVatPricenumber double

Total VAT amount for next subscription interval. Only for <code>CustomerPricePreview-Mode</code>.

PriceCurrencyIdstring

Currency code in capital letters, see ISO 4217.

ResultMessagestring

Optional result or error message.