Integrate commercetools Checkout

Integrate commercetools Checkout with web applications, using the commercetools Checkout Browser SDK, or with React Native applications, using a WebView component.

Placeholder values

The code samples in this documentation contain placeholders which must be replaced with the following values.

PlaceholderTypeRequiredReplace with
{projectKey}stringYesThe identifier of your commercetools Checkout entity and the project_key of your Project.
{applicationKey}stringYesThe identifier of an application.
{cartId}stringYesThe id of the Cart you created.
{accessToken}stringYesA valid access token to manage the Cart. The access token can created using the password flow or the anonymous session flow.
{commercetoolsCheckoutHost}stringYesThe URL for commercetools Checkout provided to you by your Customer Success Manager.
{region}stringYesThe Region where the commercetools Checkout application is hosted. For example, europe-west1.gcp.
{storeKey}stringNoThe key of a Store to which you grant permissions for commercetools Checkout.
{returnUrl}stringNoThe absolute or relative URL to which your customers will be redirected after a successful checkout, once the Order has been created.
{locale}stringNoYour customer’s locale (default is English). If the provided locale is not found, English will be used.
{anonymousId}stringNoThe anonymousId generated using the anonymous session flow. It is the value of the anonymous_id scope in the scope key of the response body. It is required only if you create a Cart with the Carts API.
{styles}objectNoAn object containing accepted CSS variables to customize the style of commercetools Checkout.
{languageOverrides}objectNoAn object containing accepted properties to customize the texts and labels of commercetools Checkout.
{showTaxes}BooleanNoSet it to true to display tax information from Composable Commerce in the price summary of your checkout page.
{currencyLocale}StringNoThe locale to set the currency formatting for prices. When it is not set, locale determines the price formatting as a default. If set, the locale for price formatting is overridden. For example, if the locale is set to fr, Swiss prices display as 10,00 CHF. If currencyLocale is set to de-CH, the prices display as CHF 10.00.


The following prerequisites apply both for integrating commercetools Checkout using the commercetools Checkout Browser SDK and the WebView component.

  • A Composable Commerce Project

  • A commercetools Checkout account with at least one Application configured

  • A Composable Commerce public API Client with the following scopes:

    • view_published_products:{projectKey}
    • view_categories:{projectKey}
    • manage_my_profile:{projectKey} or manage_my_profile:{projectKey}:{storeKey}
    • manage_my_payments:{projectKey}
    • manage_my_orders:{projectKey} or manage_my_orders:{projectKey}:{storeKey}
    • manage_my_shopping_lists:{projectKey}
    • create_anonymous_token:{projectKey}
  • If you want to create your Carts with a private API Client, the API Client must have at least the following scope:

    • manage_orders:{projectKey} or manage_orders:{projectKey}:{storeKey}

    To create a public API Client, you can use the Mobile & single-page application client template. To create a private API Client, you can use the Admin client template.

Create a Cart

To initialize commercetools Checkout, you must always provide the {cartId} of a Cart. You can create a Cart with one of the following Composable Commerce APIs:

  • My Carts: using the public API Client, which has the required manage_my_orders:{projectKey} scope.

  • Carts: using the private API Client, which has the required manage_orders:{projectKey} scope.

    To create a Cart with the Carts API, you first need to do one of the following:

    • Create an access token with the anonymous session flow and then provide the {anonymousId} as the value of the anonymousId field of the CartDraft.
    • Create an access token with the password flow and then provide the {customerId} as the value of the customerId field of the CartDraft.


When initializing commercetools Checkout, setting the locale ensures that the checkout process is translated into the preferred language, and it also affects the formatting of numbers, such as the decimal separator for prices.

If an unsupported locale is set, the checkout process will automatically revert to en, which is the default locale.

LocaleLanguagePrice formatting
en (fallback locale)English€10,000.00
deGerman10.000,00 €
en-usEnglish - United States$10,000.00
frFrench10.000,00 €
itItalian10.000,00 €

Regions and hosts

The commercetools Checkout application is available at the following hosts.

RegionApplication URL
Europe (Google Cloud, Belgium)
North America (Google Cloud, Iowa)