Review these key AlignmentSettings parameters before running subscription API calls.

You can use the following subscription API endpoints to upgrade, downgrade, or align active subscriptions. 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:

GetCustomerPricePreviewOnly
AlignToCurrentInterval
ExtendInterval

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

Parameters combinations

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

If called with GetCustomerPricePreviewOnly = true, then each of these four API endpoints returns in the response all relevant price data, such as the net price, applicable taxes, and gross price, for:

The alignment price, if the requested change would create an immediate alignment charge
The renewal price that will be applicable 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 AlignmentSettingsGetCustomerPricePreviewOnly 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.

Since subscription updates and payment processes are decoupled from one another by design, the subscription's details will be updated in the Cleverbridge platform, even if alignment payment for the upgrade fails.

Subscription details also remain changed when alignment payments are refunded or charged back is executed.

📘
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.