Learn more about key parameters before running subscription API calls.

Alignment Settings

You can use the following subscription API endpoints to upgrade and downgrade running subscriptions. You can also use these endpoints to launch a Customer Self-Service feature to enable customers to make changes to their subscription:

Parameters

The request of each of these subscription API endpoints contains a common parameter called AlignmentSettings that is comprised of three sub-parameters:

GetCustomerPricePreviewOnly
AlignToCurrentInterval
ExtendInterval

The response of the API endpoint call depends on the combination of sub-parameter values passed by each API endpoint call request in the AlignmentSettings parameter.

The table below provides details of each combination:

Sub-Parameter Values Passed	Expected Result
`AlignToCurrentInterval = true` `GetCustomerPricePreviewOnly = true` `ExtendInterval = false`	No change is made. The API call returns preview prices. For more information, see Preview Prices.
`AlignToCurrentInterval = true` `GetCustomerPricePreviewOnly = false` `ExtendInterval = false`	The subscription is changed as requested in the API call. 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 price is positive, the customer is billed a pro-rated amount immediately. If the price is negative, then an error message is returned in the API call response.
`AlignToCurrentInterval = false` `GetCustomerPricePreviewOnly = true` `ExtendInterval = false`	No change is made. The API call returns preview prices. For more information, see Preview Prices.
`AlignToCurrentInterval = false` `GetCustomerPricePreviewOnly = false` `ExtendInterval = false`	The subscription is changed as requested in the API call. Since alignment to the current billing, interval was not requested, no immediate billing event is generated and the customer is billed on the next billing date.
`AlignToCurrentInterval = true` `GetCustomerPricePreviewOnly = true` `ExtendInterval = true`	No change is made. The API call returns preview prices. For more information, see Preview Prices.
`AlignToCurrentInterval = true` `GetCustomerPricePreviewOnly = false` `ExtendInterval = true`	The subscription is changed as requested in the API call. 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 price is positive, the customer is billed a pro-rated amount immediately. If the price is negative, then an error message is returned in the API call response.

Sub-Parameter Values Passed

Expected Result

AlignToCurrentInterval = true

GetCustomerPricePreviewOnly = true

ExtendInterval = false

No change is made.

The API call returns preview prices. For more information, see Preview Prices.

AlignToCurrentInterval = true

GetCustomerPricePreviewOnly = false

ExtendInterval = false

The subscription is changed as requested in the API call.

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 price is positive, the customer is billed a pro-rated amount immediately.
If the price is negative, then an error message is returned in the API call response.

AlignToCurrentInterval = false

GetCustomerPricePreviewOnly = true

ExtendInterval = false

No change is made.

The API call returns preview prices. For more information, see Preview Prices.

AlignToCurrentInterval = false

GetCustomerPricePreviewOnly = false

ExtendInterval = false

The subscription is changed as requested in the API call.

Since alignment to the current billing, interval was not requested, no immediate billing event is generated and the customer is billed on the next billing date.

AlignToCurrentInterval = true

GetCustomerPricePreviewOnly = true

ExtendInterval = true

No change is made.

The API call returns preview prices. For more information, see Preview Prices.

AlignToCurrentInterval = true

GetCustomerPricePreviewOnly = false

ExtendInterval = true

The subscription is changed as requested in the API call.

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 price is positive, the customer is billed a pro-rated amount immediately.
If the price is negative, then an error message is returned in the API call response.

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 an immediate change is made)
The renewal price that will be applicable on the next billing date

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` `AlignmentCustomerVatPrice` `AlignmentCustomerNetPrice`	If taxation applies, then `AlignmentCustomerVatPrice` returns the appropriate calculated tax amount. If `AlignToCurrentInterval = false`, then these fields contain zeros because the previewed change will not be effective immediately (no alignment to the current billing interval).
`NextBillingCustomerGrossPrice` `NextBillingCustomerVatPrice` `NextBillingCustomerNetPrice`	These fields reflect the renewal price that will be applicable on the next billing date. If tax applies, then `NextBillingCustomerVatPrice` returns the appropriate calculated tax amount.

Field Name

Usage Notes

AlignmentCustomerGrossPrice

AlignmentCustomerVatPrice

AlignmentCustomerNetPrice

If taxation applies, then AlignmentCustomerVatPrice returns the appropriate calculated tax amount.

If AlignToCurrentInterval = false, then these fields contain zeros because the previewed change will not be effective immediately (no alignment to the current billing interval).

NextBillingCustomerGrossPrice

NextBillingCustomerVatPrice

NextBillingCustomerNetPrice

These fields reflect the renewal price that will be applicable on the next billing date.

If tax applies, then NextBillingCustomerVatPrice returns the appropriate calculated tax amount.

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

Alignment, USA Sales Tax Calculation, and Billing

If the AlignmentSettingsGetCustomerPricePreviewOnly parameter is set to true, and if USA sales tax would apply to the purchase, then the “preview” price returned includes sales tax.

Rollback on Unpaid or Reimbursed Alignment Purchase

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.

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.

For more information about alignment payments, see Understand Subscription Billing.