Get Started with Subscriptions

It is important to take the following steps and understand certain key features before getting started with subscriptions on the Cleverbridge platform.

Share and Store Information

Follow these recommended approaches to ensure you and Cleverbridge share and use a common unique identifier for each customer. It ensures you link subscription purchase data with the appropriate customer:

Provide a unique customer ID to Cleverbridge

At the time of the initial purchase, supply a customer ID value from your internal systems to Cleverbridge for use in the Cleverbridge platform. Using your own customer ID allows your internal applications to interact easily with customer subscriptions and related data in the Cleverbridge platform.

Store the subscription identifier created by Cleverbridge

Upon completion of a purchase, Cleverbridge provides you with a notification containing data such as the subscription ID and the associated customer ID you supplied Cleverbridge. Save the subscription ID within your own applications for API calls and associated Cleverbridge event notifications.

Use the GetSubscription API endpoint to retrieve and store basic information about a subscription at the initial purchase to:

• have basic subscription information readily available for internal use.
• save time by avoiding unnecessaryGetSubscription API calls in the future.

Complete Implementation Tasks

Use the checklist below to get started:

• Request Subscription API access
• Review subscription documentation
• Resolve questions with Cleverbridge Client Experience
• Create your hosted pages
• Complete integration and testing
• Test in production

Set up Notifications

Cleverbridge provides a comprehensive and powerful set of automated notifications, alerting you to events such as when a new subscription is created or when an existing subscription is updated.

Make use of Cleverbridge notifications as they ensure an effective and seamless integration between our platform and your system. For more information, see Notifications Overview.

Understand Subscription Billing

Subscription updates using Subscription API and the subscription payment process are decoupled from one another. This decoupling enhances the subscription API call performance and results in the automatic handling of unprocessed online payments.

If a payment could not be processed:

• The customer receives an email, including a link to update the credit card information or to change the payment method .
• You receive a notification that a payment failed.

If the customer updates the credit card information or changes the payment method, Cleverbridge re-processes the purchase and calculates the next billing date automatically. Upon successful payment, you automatically receive a notification that the purchase has been paid.

Understand Subscription Alignment, Pro-rated Billing, and Preview Prices

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:

• Add Subscription Item
• Align Subscriptions
• Update Subscription Item
• Update Subscription Item Price

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:

Negative Alignment Price

If an API endpoint call sets AlignToCurrentInterval equal to true and the resulting pro-rated billing amount is negative, then an error message is returned and any requested subscription change is not completed. A negative alignment price occurs under these scenarios:

1. Item price is to be decreased and item quantity remains the same.
2. Item quantity is to be decreased and item price remains the same.
3. Both item price and quantity are to be changed, and the resulting billing amount (price x quantity) is less than the current billing amount.
4. A negative alignment price is also possible when using Align Subscriptions if there were overpayments for one of the subscriptions from a prior billing interval.

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:

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:

1. The subscription details are updated in the Cleverbridge platform.
2. 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.

Understand Customer Price

Within each Product defined in the Cleverbridge platform, the Base Price tab defines one or more Product price(s); each price includes the following attributes:

• Currency (ISO Currency ID)
• Taxes (governs how taxes are applied when the Product is purchased)
• Price (the price for the associated Currency ID)

The Product price(s) set up in the Cleverbridge platform constitute(s) the default price(s) for the item when it is part of a subscription offering: the following Subscription API endpoints can be used to override the original item price in a customer’s subscription:

• AddSubscriptionItem
• UpdateSubscriptionItem
• UpdateSubscriptionItemPrice

These functions include a CustomerPrice parameter, which consists of the following required subparameters, in the function call response:

The rest of this section discusses the CurrencyId and IsGross subparameters. Understanding these subparameters is required to correctly and effectively use any of the three related API endpoints.

Using the Currency Subparameter

The CurrencyID value passed in the CustomerPrice parameter should always match the currency of the underlying subscription.

If a non-matching currency is passed, then an error message ("'CustomerPrice' currency differs from subscription currency") is returned and any requested subscription change is not completed.

Using the IsGross Subparameter

On the Cleverbridge platform, the Taxes settings on the Base Price tab govern how taxes are applied to a product purchase.

When using the Subscription API, unless instructed otherwise, you should always set the value of IsGross consistent with the Taxes setting on the Cleverbridge Platform Base Price tab for the underlying product, as follows:

• If taxes should be included in the item price, then the Taxes setting should be Gross and the value of IsGross should be set to True.
• If taxes should be added on top of the item price, then the Taxes setting should be Net and the value of IsGross should be set to False.

🚧

Important

IsGross is not set consistently with the Cleverbridge platform Product setup, then the Subscription API can have a major undesired impact on the price paid by the customer and also on client revenue.

The example below illustrates how setting IsGross inconsistently can produce unintended results.

Assume that a product priced at US$15.00 has been set up in the Cleverbridge platform with its Taxes setting set to Net (taxes should be added to the $15.00 price). The following table shows the price calculations resulting from IsGross being set to True compared to False:

In this example, an update results in lost revenue of $24.00 per item ($150.00 - $126.00).

Notes on US Sales Taxes:

• When US sales tax applies, the Taxes setting should always be set to Net and IsGross should be set to False.
• US sales tax on the net price is calculated at the time of billing.

Using the Value Subparameter

The CustomerPrice parameter is used to set the per-unit price of the item, not the total price billed for the item. The total (gross or net) price is calculated as CustomerPrice x Quantity.

Flow Chart for Auto-renewal Subscriptions

The following diagram depicts the statuses that can be set for an auto-renewal subscription at the time of the initial purchase, and how the status can change.