Skip to main content

Integrate Bold Checkout with commercetools

This document outlines the steps for creating a simple frontend integration between commercetools and Bold Checkout. It includes the following steps:

  1. Create a commercetools access token.
  2. Create a new commercetools cart.
  3. Add the desired line items to the cart.
  4. When the user proceeds to checkout, redirect them to Bold Checkout, encoding relevant details as either URL query parameters or form fields (at a minimum, cart ID, shop hostname, commercetools access token).

From here, Bold Checkout retrieves the cart from commercetools, initializes a checkout session, renders the checkout UI for the customer, and handles the remainder of the checkout process. After checkout is complete, redirect the customer back to the storefront.

Integration approaches

There are at least two approaches to integrating Bold Checkout into a commercetools storefront:

  • When the customer is ready to check out, redirect their browser to Bold Checkout’s frontend. This approach requires the least work, because you don’t have to build a frontend from scratch.
  • Build a self-hosted checkout flow, leveraging Bold’s headless APIs. While this approach is more customizable, it requires substantially more work and time.

This guide walks through the first approach. For a starting point on the second approach, refer to Create a Self-Hosted Checkout Flow.

note

Some context for those new to commercetools:

commercetools is a truly headless platform. There is no customer-facing storefront out of the box; all commercetools provides are APIs. While there are third-party vendors who provide pre-built storefronts for commercetools, in practice we can effectively consider every commercetools storefront to be a unique, bespoke application. Because of this uniqueness, we cannot simply “enable Bold Checkout” on the frontend, as each frontend requires slightly different frontend code changes.

Prerequisites

This guide assumes the following:

  • You have working knowledge of the following:

  • You created a commercetools project and configured a store within it.

  • You connected your commercetools store to Bold Checkout, as described in Create and Connect a Bold Account.

  • You configured a payment gateway, shipping zones, and tax settings, as described in Set up Bold Checkout.

  • You have at least one product in your commercetools project.

  • You can access a set of commercetools credentials using the Mobile & Single-Page Application template. To create these credentials, follow the instructions on the API Clients page of the commercetools documentation, selecting the “Mobile & Single-Page Application” template.

  • You have an existing web storefront (for example, the commercetools Sunrise SPA).

    note

    “Web storefront” is called out explicitly here because Bold Checkout’s frontend requires a web browser to view. If you need to integrate into another type of client, e.g., a mobile application, you may need an alternative approach.

Create a commercetools access token

In order to do anything with commercetools, you first must create an access token. Bold Checkout supports either of the following:

Choose whichever is most appropriate for your use case. Production storefronts likely require both types of access tokens.

note

While commercetools supports a number of different authorization flows, Bold Checkout only supports tokens created by the Anonymous and Password flows.

When successful, both of these flows return a JSON response body with the following shape. In your frontend code’s state, save a copy of the access_token property. You will need to pass this to Bold Checkout.

{
"access_token": "v-dZ10ZCpvbGfwcFniXqfkAj0vq1yZVI",
"expires_in": 172800,
"scope": "view_published_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey} customer:{id}",
"refresh_token": "{projectKey}:OWStLG0eaeVs7Yx3-mHcn8iAZohBohCiJSDdK1UCJ9U",
"token_type": "Bearer"
}

Create a commercetools cart

Once you have an access token, create a customer-scoped cart. To do this, use the appropriate commercetools API endpoint. There are two options:

  • The create my cart endpoint. Use this endpoint if you are not making use of commercetools stores (e.g., if you are an online-only seller with a global catalog).
  • The create my cart in a store endpoint. Use this endpoint if you have multiple commercetools stores and would like the store details captured on the final order entity created in commercetools.
note

commercetools is flexible about cart ownership. It’s possible to create carts that do not belong to any one customer (using the commercetools Create Cart endpoint). However, Bold Checkout does not support unowned carts.

To avoid issues, make sure you only pass customer-scoped carts to Bold Checkout. You can help ensure this by always using one of the endpoints listed above.

These endpoints return fairly large JSON responses. A truncated version is shown below. For the purpose of redirecting to Bold Checkout, we only care about the id property. Make sure your frontend code stores a copy of this - you will need it when redirecting to Bold Checkout’s frontend.

{
"type": "Cart",
"id": "5b468ea7-53af-497d-aa9a-e6d130b293a2",
"version": 1
...
}

Add items to the cart

To add an item to your cart, use the commercetools API update a cart endpoint with the Add LineItem action.

note

A full explanation of commercetools catalog browsing and cart management is beyond the scope of this guide. However, a straightforward way to prove out your integration would be to use the Query Product Projections endpoint and use the first product it returns.

Redirect to Bold Checkout

In order to display the Bold Checkout frontend, redirect the user’s browser to https://cashier.boldcommerce.com/boldplatform/checkout/build_order_begin. Bold Checkout will extract the details it needs from the URL search parameters. Bold then initializes a checkout session and return the HTML and assets for the checkout page. Because this flow uses standard HTTP behavior, it is straightforward to integrate into all sorts of frontends.

  1. Generate the Bold Checkout URL by encoding each of the required properties as URL search parameters. The following code snippet shows an example of what this might look like:

    https://cashier.boldcommerce.com/boldplatform/checkout/build_order_begin
    ?platform=commercetools
    &shop=commercetools-demo.boldcommerce.com
    &cart_id=38bc2974-f094-4368-b9f2-647389cff174
    &user_access_token=kQTP2khu8AYv6tCJZY7D3mz6QSmtvSBK
  2. Redirect the user to this URL. A few possible ways to do so are:

    1. Embed the URL in an HTML anchor tag (for example, the button the user clicks to proceed to checkout). This is the most straightforward approach, and is compatible with both server-rendered technologies (such as PHP) as well as JavaScript frameworks.
    2. Using JavaScript, explicitly set the user’s window.location to the URL. This approach is not compatible with server-rendered technologies. However, if you are using a JavaScript framework (React, Angular, etc.), this may be a simpler to integrate into your existing code.
  3. At this point, the customer is redirected to the standard Bold Checkout frontend (see screenshot below). From here, they can enter their address, select a shipping method, enter discount codes and payment details, and complete their transaction.

  4. Afterwards, they will be redirected back to either the return_url URL search parameter that was used when initiating checkout, or (if none was provided) the hostname that was used when connecting commercetools with Bold Checkout.

Next steps

At this point, you have a basic frontend integration with Bold Checkout. You can generate a commercetools token, create a cart, add a product to it, initiate checkout, and complete a transaction. Some next steps you could take:

Troubleshooting

If you completed your integration but are encountering issues when redirecting to checkout, try the following steps:

Ensure your carts are scoped to customers

commercetools provides at least four ways to create carts:

While all four of these create a cart, only the last two associate that cart with a customer. This is important, because Bold Checkout requires all carts to be attached to a customer.

Double-check that you are using one of the My Carts endpoints when creating your cart, and not the regular Carts endpoints.

note

This does not prevent you from creating guest checkouts. When you create a cart using an anonymous token, commercetools also creates an anonymous customer and associate the new cart with it.

Use a supported authentication flow

commercetools supports several authentication flows, which are used to generate user access tokens. However, Bold Checkout only supports the following:

Double-check that you are using a supported flow to create your commercetools access token.

Ensure the access token passed to Bold is associated with the cart

When you perform the redirect to Bold Checkout, you must pass both the cart ID and a commercetools access token. It is important that the access token has permission to access the provided cart. The easiest way to ensure this happens is to:

  1. Use either the anonymous or password flows when creating the token.
  2. Provide the same access token that was used to create the cart.

Double-check that the token you are passing to Bold Checkout has permission to access the cart.

Appendix A — Bold Checkout Supported URL Parameters

ParameterValueExplanationRequired?
platformcommercetoolsBold Checkout works with several different commerce platforms. This parameter is essential so that Bold Checkout knows which platform to interface with.Required.
shopThe shop hostname registered with Bold Checkout.Bold Checkout uses this hostname as a unique identifier with which to identify your store.Required.
cart_idThe id property of your commercetools cart.Used by Bold Checkout to retrieve the current products in the cart.Required.
user_access_tokenThe access_token property returned from one of the commercetools access token endpoints.Used by Bold Checkout to access the cart and identify the associated shopper.Required.
language_isoSets the language that Bold Checkout uses.Optional.
return_urlThe desired location that users should be returned to when they exit checkout.Sets the URL used if the user clicks the “return to cart” link from the checkout page.Optional. If not provided, the hostname used to register the store with Bold Checkout will be used.
bold_cart_params[currency_iso_name]Sets the currency of the cart.Optional. Will use store default if not provided.

Appendix B — Supporting Materials

  • Create & Connect a Bold Account for instructions on connecting Bold Checkout to your commercetools store.
  • Bold + commercetools Integration Examples - sample GitHub repository, showcasing simple commercetools integration.