This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

commercetools Checkout Browser SDK

commercetools Checkout Browser SDK lets you integrate commercetools Checkout both on regular websites and JavaScript web applications, either implemented in libraries or frameworks like React, Vue, or Angular.

Configuration overview

commercetools Checkout can be integrated either as a browser script or as an npm module. In both cases, you must provide a checkoutConfig object with the following properties. For further information on the values to replace placeholders, see this table.

Property	Value	Required
`projectKey`	`{projectKey}`	Yes
`applicationKey`	`{applicationKey}`	Yes
`cartId`	`{cartId}`	Yes
`accessToken`	`{accessToken}`	Yes
`host`	`{host}`	Yes
`returnUrl`	`{returnUrl}`	No
`locale`	`{locale}`	No
`logInfo`	`true`/`false`	No (default: `false`)
`logWarn`	`true`/`false`	No (default: `false`)
`logError`	`true`/`false`	No (default: `false`)
`onInfo`	function	No
`onWarn`	function	No
`onError`	function	No
`styles`	`{styles}`	No
`languageOverrides`	`{languageOverrides}`	No
`showTaxes`	`{showTaxes}`	No
`currencyLocale`	`{currencyLocale}`	No

Browser script

To integrate commercetools Checkout as a browser script, add the following code between the opening and closing <head> tags of each page on which you want to activate the start of the checkout process.

Integrate commercetools Checkout as a browser scriptJavaScript

<script>
  (function(w, d, s){
    if (w.ctc) {return;}
    var js, fjs = d.getElementsByTagName(s)[0];
    var q = [];
    w.ctc = w.ctc || function() { q.push(arguments); }
    w.ctc.q = q;
    js = d.createElement(s);
    js.type = 'text/javascript';
    js.async = true;
    js.src = 'https://unpkg.com/@commercetools/checkout-browser-sdk@latest/browser/sdk.js';
    fjs.parentNode.insertBefore(js, fjs);
  }(window, document, 'script'));
  ctc('init', {
    checkoutConfig: {
      projectKey: '{projectKey}',
      applicationKey: '{applicationKey}',
      host: 'https://app.checkout.{region}.commercetools.com',
      returnUrl: '{returnUrl}',
      cartId: '{cartId}',
      accessToken: '{accessToken}',
      locale: '{locale}'
    }
  });
</script>

Calling the init method is optional. For further information, see init and checkout methods.

Versioning

The versioning of commercetools Checkout Browser SDK is handled through npm and follows the principles of semantic versioning.

When you load the script using https://unpkg.com/@commercetools/checkout-browser-sdk@latest/browser/sdk.js, @latest serves as an alias indicating that the latest version should be loaded.

For information on the available versions of commercetools Checkout Browser SDK, see this page.

npm module

Prerequisites

Node v12.22.7 (or later)
Either npm v6 (or later) or yarn v1.22.17 (or later)

Install the SDK package

To install the SDK package, run one of the following commands:

npm install @commercetools/checkout-browser-sdk
yarn add @commercetools/checkout-browser-sdk

npm script

Integrate commercetools Checkout as an npm moduleJavaScript

import { init } from '@commercetools/checkout-browser-sdk';

init({
  checkoutConfig: {
    projectKey: '{projectKey}',
    applicationKey: '{applicationKey}',
    host: 'https://app.checkout.{region}.commercetools.com',
    returnUrl: '{returnUrl}',
    cartId: '{cartId}',
    accessToken: '{accessToken}',
    locale: '{locale}',
  },
});

Calling the init method is optional. For further information, see init and checkout methods.

init and checkout methods

The init method lets you specify the configuration options that remain constant throughout the customers's website session, such as the host, projectKey, and applicationKey. Additionally, it lets you subscribe to the messages sent by commercetools Checkout. Since calling this method is optional and doesn't start the checkout process, any configuration parameters within the checkoutConfig object can be modified later, when calling the checkout method.

The checkout method is used to start the checkout process. At this stage, you must provide any missing information from the checkoutConfig object that wasn't previously provided with the init method. With the checkout method you can update the information you previously provided with the init method, but you cannot subscribe to the messages sent by commercetools Checkout. To subscribe to the messages, you must use the init method.

Call the checkout method with configuration parametersJavaScript

import { checkout } from '@commercetools/checkout-browser-sdk';

checkout({
  cartId: '{cartId}',
  accessToken: '{accessToken}',
  locale: '{locale}',
});

When calling the checkout method, the commercetools Checkout UI component for the specified cartId opens. If the customer quits the checkout process before completing it, you can call this method again with the same cartId and accessToken, while the token is still valid. If the token has expired, you can refresh it and open the Checkout UI component again with the new token.

By default, when calling the checkout method, the Checkout UI component appears full screen in an absolutely positioned <div> element that hides other content on your page. The Checkout UI component renders a header with your preconfigured logo, the input fields, and the Leave checkout button. By clicking the Leave checkout button, the Checkout UI component disappears and the content of your page becomes visible again.

Otherwise, you can display the Checkout UI component inline with your content by using a <div> or <span> element with the data-ctc attribute in it (for example, <div data-ctc />). By doing so, the header and the Leave checkout button do not appear, and you can render any other content around the Checkout UI component, such as a custom header or footer.

Checkout completion

Once the customer completes the checkout process successfully, the SDK will close commercetools Checkout. After this happens, there are two ways to recover the control of the flow, either through the returnUrl configuration parameter or by reacting to the checkout_completed message.

Callback URL

If a returnUrl was provided through the init or checkout methods, the SDK redirects the customer to this URL and adds the orderId parameter to the URL with the ID of the Order created as its value. For example, https://example-url/callback-url?orderId=123.

Checkout completed message

When the customer completes the checkout process, commercetools Checkout sends a checkout_completed message with the following format.

You can react to this message to display on your website a feedback for the customer. For example, a message or a dialog.

checkout_completed messagejson

{
  "type": "info:app:status",
  "code": "checkout_completed",
  "message": "Checkout for {orderId} completed",
  "payload": {
    "order": {
      "id": "{orderId}"
    }
  }
}

React to messages

The messages from commercetools Checkout can be of three severity levels: info, warn, or error.

To react to these message, you can use:

The onInfo, onWarn, and onError handlers
The logInfo, logWarn, and logError methods
The subscribe method

onInfo, onWarn, and onError

You can subscribe to the info, warn, or error messages by passing the optional onInfo, onWarn, or onError message handlers in the checkoutConfig object in the init method. The handlers will receive the message as a parameter.

In the following examples, we subscribe to all info messages and log into the console a Received note followed by the message code.

Use onInfo with the browser script to subscribe to info messagesJavaScript

import { ctc } from '@commercetools/checkout-browser-sdk';

ctc('init', {
  onInfo: function (message) {
    console.error('Received: ' + message.code);
  },
});

Use onInfo with the npm module to subscribe to info messagesJavaScript

import { init } from '@commercetools/checkout-browser-sdk';

init({
  onInfo: (message) => {
    console.error('Received: ' + message.code);
  },
});

logInfo, logWarn, and logError

You can use the logInfo, logWarn, and logError methods to log messages in the console for debugging purposes. We recommend not enabling them in production since, usually, these logs are not useful for end users.

In the following examples, we log all the info and error messages, but not the warn ones.

Use logInfo and logError with the browser script to log info and error messagesJavaScript

import { ctc } from '@commercetools/checkout-browser-sdk';

ctc('init', {
  logInfo: true,
  logWarn: false,
  logError: true,
});

Use logInfo and logError with the npm module to log info and error messagesJavaScript

import { init } from '@commercetools/checkout-browser-sdk';

init({
  logInfo: true,
  logWarn: false,
  logError: true,
});

The SDK exposes a subscribe method that lets you pass a pattern matching a message type and a handler function that will receive the messages as a parameter if they match the specified pattern. You can add as many subscriptions as you want.

Following are the patters that you can pass to subscribe to messages.

Pattern	Description
`*`	Subscribe to all messages.
`{level}:*`	Subscribe to all messages of a specific level. For example, `info:`, `warn:`, or `error:*`.
`{level}:{entity}:*`	Subscribe to all messages of a specific level and entity. For example, `error:init:*`.
`{level}:{entity}:{type}`	Subscribe to all messages of a specific level, entity, and type. For example, `error:init:bad_config`.

In the following examples, we subscribe to all error messages and log into the console a Received note followed by the message code.

Use subscribe with the browser script to subscribe to all error messagesJavaScript

import { ctc } from '@commercetools/checkout-browser-sdk';

ctc('subscribe', 'error:*', function (message) {
  console.error('Received: ' + message.code);
});

Use subscribe with the npm module to subscribe to all error messagesJavaScript

import { subscribe } from '@commercetools/checkout-browser-sdk';

subscribe('error:*', (message) => {
  console.error('Received: ' + message.code);
});