Integrating Other E-commerce Systems with UX1 Marketplace Checkout

This article explains how to integrate an external or an in-house e-commerce system with the checkout in the UX1 Marketplace. To do this, you need CloudBlue Commerce 20.4 or later with UX1 Marketplace 5.7 or later. Additionally, you might want to implement a single sign-on by following these instructions.

The first step is to implement a redirection from the external system to the checkout by a direct link. The link must be formed as follows:

https://<brand-domain>/ccp/v/pa/marketplace/checkout-integration?externalCart=<cart-data>

Where <cart-data> must be replaced by minified and URL-encoded JSON with the following structure and parameters:


{
  "products": [
    {
		"period": {
			"duration": <duration>,
			"unit": "<unit>"
		},
		"billingPlanId": <plan identifier in the Billing system>
		}
	]
}

Where <duration> is the desired duration of subscriptions (the amount of units), <unit> is a duration measurement unit (can be DAYS, MONTHS or YEARS), and <plan identifier in the Billing system> is the numeric identifier of a plan that corresponds to a product in the store.

Note: A different direct link must be formed for each product where redirection is needed.

An example of a resulting URL

With the example values, <brand-domain> = ksPRn.brnd10255a33-a5ac1e.aqa.int.zone, <duration> = 1, <unit> = YEARS, and <plan identifier in the Billing system> = 67, the URL will look similar to the following:

https://ksPRn.brnd10255a33-a5ac1e.aqa.int.zone/ccp/v/pa/marketplace/checkout-integration?externalCart=%7B"products"%3A%5B%7B"billingPlanId"%3A67%2C"period"%3A%7B"duration"%3A1%2C"unit"%3A"YEARS"%7D%7D%5D%7D

Specifying several plans in the URL

You can specify several plans in the URL as the entries of the products array:


 {
	"products": [
		{
			"period": {
				"duration": <duration>,
				"unit": "<unit>"
			},
				"billingPlanId": <plan identifier in the Billing system>
		},
		{
			"period": {
				"duration": <duration>,
				"unit": "<unit>"
			},
				"billingPlanId": <another plan identifier in the Billing system>
		}
	]
 }

Example

JSON


{
	"products": [
		{
			"period": {
				"duration": 1,
				"unit": "YEARS"
			},
				"billingPlanId": 18
		},
		{
			"period": {
				"duration": 1,
				"unit": "MONTHS"
			},
				"billingPlanId": 19
		}
	]
}

The resulting URL

https://dlfkn.brnd10255a33-a5ac1e.aqa.int.zone/ccp/v/pa/marketplace/select-cart-integration?externalCart=%7B%22products%22%3A%5B%7B%22billingPlanId%22%3A18%2C%22period%22%3A%7B%22duration%22%3A1%2C%22unit%22%3A%22YEARS%22%7D%7D%2C%7B%22billingPlanId%22%3A19%2C%22period%22%3A%7B%22duration%22%3A1%2C%22unit%22%3A%22MONTHS%22%7D%7D%5D%7D

Letting customers select their previous cart before the checkout

When a registered customer adds items to a cart but does not check out, the cart stays remembered, and the customer can check out later.

However, if the customer uses a direct link, this remembered content will be automatically replaced by the data specified in the direct link and the customer will not be able to check out the items in the previous cart since that moment.

To override this automatic behavior and let customers decide which of the carts they want to check out, add the offerCartSelection parameter with the true value to the URL.

The new format of a URL, including this parameter, is as follows:

https://<brand-domain>/ccp/v/pa/marketplace/checkout-integration?externalCart=<cart-data>&offerCartSelection=true

The above example of a URL, including this parameter, is as follows: