Review the key AlignmentSettings parameters before running subscription API calls.

You can use the following subscription API endpoints to upgrade, downgrade, or align active subscriptions.
The behavior of these operations is controlled by the AlignmentSettings object.

These endpoints can also support customer self-service flows that allow customers to change their own subscriptions:

Parameters

Each endpoint request includes an AlignmentSettings object with three sub-parameters:

Sub-parameter	Defaults to:	Required?
`GetCustomerPricePreviewOnly`	true	Yes
`AlignToCurrentInterval`	false	Yes
ExtendInterval	true	No

The API response depends on the combination of values passed in AlignmentSettings.

Parameter Combinations and Results

Preview only?	Align to current interval?	Extend interval?	Result
`true`	`true`	`false`	No change is made. The API returns preview prices for the requested change.
`false`	`true`	`false`	The subscription is changed as requested. The billing interval of the new or updated subscription item is shortened to align with the billing interval of the existing subscription item. If the alignment price is positive, the customer is billed a prorated amount immediately. If the alignment price is negative, the API returns an error and the requested change is not completed.
`true`	`false`	`false`	No change is made. The API returns preview prices for the requested change. Because alignment to the current interval is not requested, the alignment price fields return zero values.
`false`	`false`	`false`	The subscription is changed as requested. Because alignment to the current billing interval is not requested, no immediate billing event is generated, and the customer is billed on the next billing date.
`true`	`true`	`true`	No change is made. The API returns preview prices for the requested change.
`false`	`true`	`true`	The subscription is changed as requested. The billing interval of the existing subscription item is extended to align with the billing interval of the new or updated subscription item. If the alignment price is positive, the customer is billed a prorated amount immediately. If the alignment price is negative, the API returns an error and the requested change is not completed.

Preview Prices

When GetCustomerPricePreviewOnly = true, the API calculates prices but does not modify the subscription.

The response includes all relevant price information, such as the net price, applicable taxes, and gross price, for:

The alignment charge, if the requested change would result in immediate billing
The renewal price that will apply on the next billing date

Preview Price Parameters

You can display this information to customers so that customers can fully understand what they will be billed in the future and, in the case of alignment, what they will be billed immediately. The six price fields that are returned are the following:

Field name	Usage notes
`AlignmentCustomerGrossPrice`	Returns the gross alignment price, if the requested change would create an immediate alignment charge. If `AlignToCurrentInterval = false`, this field returns `0` because the previewed change will not be effective immediately. If `GetCustomerPricePreviewOnly = false`, this field returns `null`.
`AlignmentCustomerVatPrice`	Returns the calculated tax amount for the alignment price, if tax applies and the requested change would create an immediate alignment charge. If `AlignToCurrentInterval = false`, this field returns `0` because the previewed change will not be effective immediately. If `GetCustomerPricePreviewOnly = false`, this field returns `null`.
`AlignmentCustomerNetPrice`	Returns the net alignment price, if the requested change would create an immediate alignment charge. If `AlignToCurrentInterval = false`, this field returns `0` because the previewed change will not be effective immediately. If `GetCustomerPricePreviewOnly = false`, this field returns `null`.
`NextBillingCustomerGrossPrice`	Returns the gross renewal price that will apply on the next billing date. If `GetCustomerPricePreviewOnly = false`, this field returns `null`.
`NextBillingCustomerVatPrice`	Returns the calculated tax amount for the renewal price, if tax applies. If `GetCustomerPricePreviewOnly = false`, this field returns `null`.
`NextBillingCustomerNetPrice`	Returns the net renewal price that will apply on the next billing date. If `GetCustomerPricePreviewOnly = false`, this field returns `null`.

📘
Note
If these API endpoints are called with GetCustomerPricePreviewOnly = false, then these fields contain null values.

Alignment, US Sales Tax Calculation, and Billing

If the GetCustomerPricePreviewOnly parameter is set to true, and if US Sales Tax would apply to the purchase, then the “preview” price returned includes sales tax.

Rollback for Unpaid, Refunded, or Charged-Back Alignment Purchases

When a customer's running subscription is upgraded via the Update Subscription Item, two independent events occur:

The subscription details are updated in the Cleverbridge platform.
A payment process is initiated to pay for the alignment cost of the upgrade.

Because subscription updates and payment processing are intentionally decoupled, the subscription's details will be updated in the Cleverbridge platform, even if alignment payment for the upgrade fails.

Subscription details also remain changed if the alignment payment is refunded or charged back.

📘
Note
If you want to prevent this discrepancy from occurring and roll back a customer's subscription details after a defined period of time, you can request that a database setting is activated in the Cleverbridge platform. To activate this setting, contact Client Experience.

Alignment Payments

For more information about alignment payments, see Subscription Billing.