Subscription API Guide

Important

You can filter the content on this page by subscription management version. For more information, see Subscription Management 1.0 and 2.0.

Show resources for:

The Subscription API allows you to acquire information about your subscriptions. It also gives you the option of processing a number of different API calls in order to change or update existing subscriptions.

Before you start integrating the Subscription API, make sure to read the following:

Getting Started with the Subscription API

Before getting started with subscriptions in the subscription commerce platform, it is important to take certain steps and understand key features. The integration of client and cleverbridge systems involves the following important aspects:

 

Once you have done so, you can read through the following information to help you understand and integrate the following Subscription API resources:

Add Subscription Item

POST /subscription/addsubscriptionitem

The Add Subscription Item endpoint adds a new subscription item to an existing subscription. You can also use it to calculate and preview the pro-rated cost of adding a new subscription item to an existing subscription item. Additionally, you can use the resource to set a price for the subscription item that differs from what has been set up in the Commerce Assistant.

Align Subscriptions

POST /subscription/alignsubscriptions

The Align Subscriptions endpoint consolidates the billing of two subscriptions that belong to one customer. If AlignToCurrentInterval is set to true, the resource performs a pro-rated calculation of the cost of one subscription so that it can be merged with another subscription, and this results in a single billing event for a given period. You can also use the resource to calculate and preview the pro-rated cost of aligning two subscriptions.

Get Subscription

GET /subscription/getsubscription?subscriptionid={subscriptionid}

The Get Subscription endpoint retrieves a collection of subscription items for a particular subscription using a subscription ID. Subscription items contain billing events and the current subscription status, which could be Active, Deactivated, Finished, Grace, Hold, or New.

Get Subscriptions for Customer

GET /subscription/getsubscriptionsforcustomer?customerid={customerid}&customerreferenceid={customerreferenceid}&subscriptionstatus={subscriptionstatus}&customeremail={customeremail}

The Get Subscriptions for Customer endpoint retrieves the subscription items pertatining to particular customer's subscriptions using the corresponding customer ID (cleverbridge’s unique identifier), the customer reference ID (your unique identifier), or the customer's email address. Subscription items contain billing events and the current subscription status, which could be Active, Deactivated, Finished, Grace, Hold, or New.

Get Subscription by Purchase

GET /subscription/getsubscriptionsbypurchase?purchaseid={purchaseid}

The Get Subscription by Purchase endpoint retrieves the subscription items for a particular subscription using the corresponding purchase ID. Subscription items contain billing events and the current subscription status, which could be Active, Deactivated, Finished, Grace, Hold, or New.

Reinstate Subscription Items

POST /subscription/reinstatesubscriptionitems

The Reinstate Subscription Items endpoint changes a subscription item status from Deactivated to Active for one or more items that a customer canceled or did not renew. The response returns an OK message when successful, or a web exception if the subscription item status is already Active.

Remove Subscription Item

POST /subscription/removesubscriptionitem

The Remove Subscription Item endpoint permanently deletes a subscription item for a discontinued product or special offer, making it impossible to reactivate the subscription item in the future.

Warning

This resource should be used rarely and with caution.

Renew Subscription

POST /subscription/renewsubscription

The Renew Subscription endpoint triggers an instant renewal of a subscription. If the renewal payment can be processed with the current payment details, then the subscription is renewed, and the customer receives an email confirmation with the delivery details. If the renewal payment cannot be processed with the current payment details, or if an offline paymentClosedOffline payment stands for a group of payment options. With the order confirmation, the customer receives a link with information on how to make the payment. Ordered products are delivered as soon as cleverbridge receives a payment confirmation from the payment provider. is required, then the customer receives an email with payment instructions. You can use this API if a B2B customer has budget left at the end of the year, and they want to renew their auto-renewal subscription before the end of the year.

Update Account

POST /subscription/updateaccount

The Update Account endpoint initiates an account update for the customer's credit card information.

Update Internal Customer ID

POST /subscription/updatecustomer

The Update Internal Customer ID endpoint updates your internal customer ID (CustomerReferenceId) for a subscription. This can be used to synchronize your internal customer ID (CustomerReferenceId) with the cleverbridge customer ID (CustomerId), so that you can more easily identify customers who have multiple subscriptions.

Update Contact

POST /subscription/updatecontact

The Update Contact endpoint updates the customer's subscription profile, such as the email address, billing address, delivery address, and licensee address. The updates will be reflected on the next billing date.

Update Next Billing Date

POST /subscription/updatenextbillingdate

The Update Next Billing Date endpoint modifies or postpones the next billing date for a subscription. It is commonly used to extend a billing period. The response returns an OK message when successful, or a web exception if the billing date lies in the past.

Update Subscription Item

POST /subscription/updatesubscriptionitem

The Update Subscription Item endpoint updates (or creates a preview of an update to) an existing subscription. With this resource, you can modify a subscription item and its details, add a coupon code, adjust the quantity of a subscription item, bill a customer in arrears for usage, replace a single subscription with another subscription, change the product name for the next billing period, and change the billing interval of a subscription.

This resource also allows you to update the price of an item. The response returns a prorated price that will be applied to the next billing event.

Tip

It is possible to use either the /updatesubscriptionitem or the /updatesubscriptionitem resource if the only subscription item properties to be changed are the price, the quantity, or both. However, /updatesubscriptionitem should be used for new developments or for modifying existing code in cases where other subscription data, in addition to price and (optionally) quantity, are changed. On the other hand, /updatesubscriptionitem should be used for new developments in which only the subscription item's price and (optionally) quantity are changed.

Update Subscription Item Price

POST /subscription/updatesubscriptionitemprice

The Update Subscription Item Price enpoint updates (or creates a preview of an update to) the price of an existing subscription. If AlignToCurrentInterval is set to true, the response returns a prorated price that will be applied to the subscription item immediately. Optionally, it also allows you adjust the quantity of a subscription item.

Update Subscription Parameters

POST /subscription/updatesubscriptionparameters

The Update Subscription Parameters endpoint Updates one or more subscription parameters that pertain to a subscription. If the parameter key existed in the subscription, the parameter value will be overwritten. If the parameter key did not exist in the subscription, the parameter key and value pair will be created. The updates will be reflected on the next billing date.

Update Subscription Renewal Type

Important

You can only use this API endpoint with Subscription Management 2.0. For more information, see Subscription Management 1.0 and 2.0.

POST /subscription/updatesubscriptionrenewaltype

The Update Subscription Renewal Type endpoint updates the renewal type of a subscription, independent of the product configuration. Automatic renewal is the default for subscription products set up in the Commerce Assistant. Use this endpoint to implement a "turn off automatic renewal" option in a customer self-service UI.