Skip to main content

Using Bold Checkout with commercetools Carts

In order to make use of the Bold Checkout APIs with commercetools, you must have both a cart and an access token. This document outlines the steps for how to get this information from commercetools so that you can get started creating orders. It includes the following steps:

  1. Create a commercetools access token.
  2. Create a commercetools cart.
  3. Add items to the cart.
  4. Initialize a Checkout Order.
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.

Prerequisites​

This guide assumes the following:

  • You have working knowledge of:
  • 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.

Create a commercetools access token​

In order to make a call to 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. Make sure to save a copy of the access_token value as you will need this to Initialize a Checkout Order.

{
  "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

Bold Checkout does not support unowned carts. While it is possible to create carts that do not belong to any one customer (using the commercetools Create Cart endpoint), you cannot use this kind of cart with Bold Checkout.

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. We only care about the id property, as this is needed to Initialize a Checkout Order.

{
  "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.

Initialize a Checkout Order​

Now that there is a cart and it is populated with items, you can Initialize an Order.

The following cURL example shows how to pass in the cart_id and access_token:

curl --request POST 'https://api.boldcommerce.com/checkout/orders/{shop_identifier}/init' \
     --header 'Authorization: Bearer {access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "cart_id": "commercetools_cart_id",
         "access_token": "commercetools_user_access_token"
     }'

From here, Bold Checkout retrieves the cart from commercetools, initializes a checkout session, and you are now ready to Populate the Order.

note

To add items to the Order after it has been initialized, use the Add Line Item endpoint. Make sure to add the corresponding item to the commercetools cart as mentioned above.

Next steps​

At this point, you have a basic commercetools integration with Bold Checkout. You can generate a commercetools token, create a cart, add a product to it, and initiate checkout. Now you are ready to Populate a Checkout Order.