Cart API Guide

1. You use proprietary subscription software and do not need to use the subscription options offered in the Cleverbridge platform.
2. A customer places a subscription order on your platform. The subscription details are stored in your platform and Cleverbridge treats it as a normal (non-subscription) purchase.
3. Rather than managing the details of the subscription, Cleverbridge handles only the billing and delivery details of every rebilling interval.

You produce gaming applications with built-in order processing buttons, for example. There are two scenarios for this use case:

Update

1. A customer buys the game application.
2. After playing for several weeks, the customer clicks the update button. The application uses the ProcessCart API to provide information to Cleverbridge (for example: customer ID, product ID).

Free-to-Paid

1. A customer uses a free trial version of the game application.
2. After playing for several weeks, the customer clicks the buy button.
3. Cleverbridge has no records for this customer, so the ProcessCart API returns a link to your system that redirects the customer to the checkout page. This link can also be sent to the customer by email if you prefer.
4. The customer completes the order.

1. A customer orders a technical support product based on the number of hours of support provided.
2. After two months, the customer would like more hours, so the customer goes to your website and purchases more technical support hours.
3. The ProcessCart API handles the upgrade as a one-off billing event.

You manage subscription events using your own subscription platform with the contingency that you inform Cleverbridge in case rebilling is required.

Requirements

• Cleverbridge flags you as responsible for handling your own subscriptions.
• You must create and configure subscription products.
• The referenced subscription must have a status of "Handled by Client".

Scenario

1. A customer uses the Cleverbridge checkout process to place an initial subscription purchase. At the time of the initial purchase, Cleverbridge captures the payment information and creates a subscription with the status "Handled by Client".
2. You receive the paid order notification that contains the Cleverbridge subscription ID. You must save this ID into its own subscription system so that the ID is included in future rebilling requests, identifying the new purchases as part of that subscription.

   Warning

   If you do not include the ID with the request, a new subscription will be created in the Cleverbridge database.

   The subscription ID has the following structure in the JSON notification:

   {
   "recurringBilling":
     {
       "subscriptionId": "S9073119"
       …
     }
   }

3. No further actions are taken by Cleverbridge; Cleverbridge waits for the next purchase, which must be initiated by you.

To trigger a rebilling, you must create an API call containing:

• Subscription ID
• Default language ID
• Product ID
• Quantity
• Additional name (optional)
• Dynamic product name (optional)
• Dynamic price (optional)

{
"processCartRequest": 
  {
    "cart":
      ...
    "defaultCountryId": "String",
    "defaultLanguageId": "String",
    "extraParameters":
      ...
    "processCartMode": {},
      ...
    "subscription": {"subscriptionId": "S9073119"}
  }
}
 

You can control the behavior of the API (for example, how to handle errors like incomplete payment information). There are two modes:

Interactive (Default)

In the interactive mode, you can interact directly with the customer if any information is outdated, such as when the credit card expires or is invalid. This method returns a session URL that you can use to redirect the customer to the Cleverbridge checkout process. All available information, such as the first name and address, will be included if it exists, and only the wrong or missing data needs to be changed by the customer. Incomplete or invalid payment information is the most common reason for an error.

With the interactive mode, Cleverbridge does not save the information or create a purchase in the database. The submitted information is temporarily stored for 72 hours and accessible through a session URL that is returned by the API.

If all required information is complete and valid, but the payment is declined, Cleverbridge creates the purchase and returns an existing reference ID and a URL for a page where the customer can change the payment details or select another payment type.

Note

A session URL is only valid for 72 hours before it expires.

Non Interactive

If you cannot ensure that the customer will access the URL within 72 hours, the non-interactive mode is the best mode. In this mode, the purchase is saved and the API returns a URL for the checkout process so that the customer can complete the information required to process the order.

With ExtraParameterMode, you can control whether the x-parameters are added to the initial purchase of the subscription (PurchaseOnly), all subsequent billing events (SubscriptionOnly), or both the initial purchase of the subscription and all subsequent billing events (Default). This parameter only lets you add x-parameters to subsequent billing events of new subscriptions. If you want to add x-parameters to subsequent billing events of an existing subscription, you must update the underlying subscription using POST /subscription/updatesubscriptionparameters. For more information, see Update Subscription Parameters.

You can add additional information to the purchase with the ProcessCart API by using x-parameters. X-parameters are components of the request and they are used to pass information through the API, such as:

• Sources of revenue (revenue tracking)
• Customer information
• Affiliate and partner information
• Any other information you would like to pass

X-parameters are configured for attributes initiated outside the Cleverbridge platform. You create x-parameters based on an information need that is not inherently included in the Cleverbridge platform, such as a user ID number or the name of a campaign. X-parameters must begin with x-. X-parameters are included in Cleverbridge notifications.

You can submit more information using x-parameters on both the shopping cart and individual cart item levels. These x-parameters are received through notifications, which contain additional custom data, such as tracking and licensing information, for more detailed reporting.

Include an X-Parameter

To include x-parameters per cart item or per cart, you must add a list of key/value pairs to the request.

It is important that all keys begin with x- so that this information can be identified in the Cleverbridge system.

The submitted x-parameters are included in the notifications. For example, you can assign the purchase to a customer in your system.

{
  "extraParameters": 
   {
     "extraParameter": 
       {
        "key": "x-customerid",
        "value": "51254"
       },    
  "extraParameter": 
    {
      "key": "x-vendors-subscription-id",
      "value": "544920"
    }
  }
}

In order to receive the required customer information, such as the payment information, it is required to submit an identifier so that Cleverbridge can find it. The API offers several ways to identify the customer:

• LogonPurchaseId — Former purchase ID of the customer.
• CustomerReferenceId — Client-unique identifier of the customer. You must submit this value by the first purchase or when the customer is created so that Cleverbridge can store the value.
• SubscriptionId — If you handle the subscription yourself, it is possible to identify the customer by the Cleverbridge subscription ID. This ID is reported with the notifications after the first purchase.

It is recommended that you use the LogonPurchaseId; or, if you handle the subscriptions yourself, use the SubscriptionId.