Getting Started

The checkout is an essential part of the ecommerce flow. Use the Bold Checkout APIs to customize your store's checkout experience to include everything you need and nothing you don’t.

In this guide, get started using the Checkout APIs by accomplishing the following tasks:

1. Install Bold Checkout on your store.
2. Submit a CORS allowlist request
3. Create an API access token.
4. Create an order and add a guest customer.

Install Bold Checkout

To call the Checkout APIs, you must have the Bold Commerce app installed on your store. The installation process varies slightly based on your store's platform. Refer to the following articles in the Help Center for more information and instructions.

• Install on BigCommerce.
• Install on commercetools.
• Install on WooCommerce.

note

Bold Checkout is called Bold Cashier on Shopify. Bold Cashier is only available to merchants who installed the app prior to January 20, 2020. New enterprise customers can submit a request to Shopify to use Bold Cashier. Please reach out to our Partners Team for more information.

Submit a CORS allowlist request

The Bold Checkout APIs are protected by a restrictive Cross-Origin Resource Sharing (CORS) policy, which blocks frontend JavaScript code from calling the APIs. In order to make calls to the Bold APIs from a browser, you must first request that your stores are added to the CORS allowlist. Failing to make this request will result in errors from your browser or a failure of your browser to load the checkout frontend.

Submit a support request, and indicate the store domains (including a development store, if applicable) that need to be added to the allowlist.

Create an API access token

An API access token gives you access to the Bold APIs. The process to generate this token depends on the type of integration you build:

• For private integrations, which are installed on a single store and are not available in the Integrations Marketplace, create your API access token through the Bold Account Center. Complete the steps in the Quick Start guide to generate this token and make your first API calls.
• For public integrations, which can be made available in the Integrations Marketplace, create your API access token through an OAuth flow. Complete the steps in the Building Public Integrations guide to generate this token and make your first API calls.

When prompted to specify the scopes of your API access token, select the following scopes:

Category	Scope	Permissions
Core	Customers	Read & Write
Core	Orders	Read & Write
Core	Shop Settings	Read & Write
Core	Shops	Read
Checkout	Payments	Write

Add a guest customer

The following steps show you how to perform some basic API calls to initialize a Checkout order and add a guest customer to the order.

note

These examples are written using cURL, but you can also use other API testing platforms — such as Postman or Stoplight – to become familiar with the APIs.

Find the shop identifier

If you haven't done so already, find the shop_identifier for your store by calling the Get Info endpoint. This identifies your store to the API and is required for all Checkout endpoints, so it may be wise to store it somewhere easily accessible.

The following example shows retrieving the shop_identifier using the API access token you previously created:

curl --request GET 'https://api.boldcommerce.com/shops/v1/info' \
     --header 'Authorization: Bearer {api_access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01'

A successful API call returns a JSON object with information about your shop. The shop_identifier value is required for the following step.

Create a new order

You can now create a new order using the Initialize Order endpoint of the Checkout Backend API. This endpoint also retrieves a JSON Web Token (JWT), which is required in all calls to the Checkout Frontend API to authenticate the customer.

Products can be added to orders through two methods:

• Through cart params, which include all necessary data about each product in the customer's cart.
• Through API endpoints, such as a combination of List Products and Add Line Item.

note

For the purpose of demonstration in this tutorial, we create an order with a generic product instead of items from your store.

The following snippet shows an example of initializing a new order:

curl --request POST 'https://api.boldcommerce.com/checkout/orders/{shop_identifier}/init' \
     --header 'Authorization: Bearer {api_access_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "cart_items": [
             {
                 "platform_id": "12345",
                 "quantity": 3,
                 "line_item_key": "red_sweater",
                 "line_item_properties": {
                     "key": "value",
                     "key2": "sub_value",
                     "key4": "value4"
                 }
             }
         ]
     }'

A successful API call returns data, a JSON object with information about the order. The jwt_token and public_order_id values from this response are required for the following step.

Add a new guest customer

If no customer information was provided from the Initialize Order endpoint, you can associate a guest customer with the order using the Add Guest Customer endpoint.

note

To use this endpoint, the authentication header of the request must include the jwt_token retrieved in the previous step instead of your API access token.

The following snippet shows an example of adding a guest customer to the order:

curl --request POST 'https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/customer/guest' \
     --header 'Authorization: Bearer {jwt_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01' \
     --header 'Content-Type: application/json' \
     --data '{
         "first_name": "John",
         "last_name": "Doe",
         "email_address": "john.doe@example.com",
         "accepts_marketing": true
     }'

A successful API call returns data, a JSON object with information about the order, including updated customer information.

Checkout Frontend API responses

Note that each POST or PATCH call to the Checkout Frontend APIs returns a data JSON object, which is composed of two parts:

• A key and value pair corresponding to the data that changed in the request. For example, the call made in the Add a new guest customer step includes a customer object, with details about the customer.
• An application_state key, the value of which forms the full status of the order, including customer information, shipping and billing addresses, the items included in the order, etc. This portion of the response is helpful for validating changes made to an order.

For example, the following code snippet shows the object returned in response to a Generate Taxes call:

Expand to see full example.

{
  "data": {
    "taxes": [
      {
        "value": 245,
        "name": "GST",
        "is_included": false
      },
      {
        "value": 343,
        "name": "PST",
        "is_included": false
      }
    ],
    "application_state": {
      "customer": {
        "platform_id": "2",
        "public_id": "u52Cn9USfOZWn0FHZHPBaYj4W6ekmXiCkDzvoZ9HD7AR8j67nPWyKVgxubmhm0vH",
        "first_name": "",
        "last_name": "",
        "email_address": "john.do@example.com",
        "accepts_marketing": false,
        "saved_addresses": [
          {
            "first_name": "John",
            "last_name": "Doe",
            "address_line_1": "50 Fultz Blvd",
            "address_line_2": "",
            "province": "Manitoba",
            "city": "Winnipeg",
            "country_code": "CA",
            "country": "Canada",
            "province_code": "MB",
            "postal_code": "R3Y0L6",
            "business_name": "",
            "phone_number": "8005550100"
          }
        ]
      },
      "addresses": {
        "shipping": {
          "id": null,
          "first_name": "John",
          "last_name": "Doe",
          "address_line_1": "50 Fultz Blvd",
          "address_line_2": "",
          "country": "Canada",
          "city": "Winnipeg",
          "province": "Manitoba",
          "country_code": "CA",
          "province_code": "MB",
          "postal_code": "R3L0L6",
          "business_name": "",
          "phone_number": "8005550101"
        },
        "billing": {
          "id": null,
          "first_name": "John",
          "last_name": "Doe",
          "address_line_1": "50 Fultz Blvd",
          "address_line_2": "",
          "country": "Canada",
          "city": "Winnipeg",
          "province": "Manitoba",
          "country_code": "CA",
          "province_code": "MB",
          "postal_code": "R3Y0L6",
          "business_name": "",
          "phone_number": "8005550102"
        }
      },
      "line_items": [
        {
          "product_data": {
            "id": "175057980",
            "product_title": "[Sample] Fog Linen Chambray Towel - Beige Stripe",
            "title": "Size XS / Color Silver",
            "image_url": "",
            "properties": [],
            "description": "",
            "quantity": 1,
            "price": 4900,
            "total_price": 4900,
            "visible": 1,
            "line_item_key": "key1",
            "barcode": "",
            "compare_at_price": 4900,
            "weight": 1000,
            "weight_unit": "g",
            "product_id": "77",
            "variant_id": "1",
            "requires_shipping": true,
            "sku": "SLCTBS-A9615491",
            "taxable": true,
            "tags": "",
            "vendor": ""
          },
          "taxes": [
            {
              "value": 245,
              "name": "GST",
              "is_included": false
            },
            {
              "value": 343,
              "name": "PST",
              "is_included": false
            }
          ],
          "fees": [],
          "discounts": [],
          "fulfilled_quantity": 0
        }
      ],
      "fees": [],
      "taxes": [
        {
          "value": 245,
          "name": "GST",
          "is_included": false
        },
        {
          "value": 343,
          "name": "PST",
          "is_included": false
        }
      ],
      "discounts": [],
      "payments": [],
      "order_total": 5988,
      "order_meta_data": {
        "cart_parameters": [],
        "note_attributes": [],
        "notes": "",
        "tags": []
      },
      "shipping": {
        "selected_shipping": {
          "id": "0",
          "description": "Cheap",
          "amount": 500
        },
        "available_shipping_lines": [
          {
            "id": "0",
            "description": "Cheap",
            "amount": 500
          }
        ],
        "taxes": [],
        "discounts": []
      },
      "resumable_link": null
    }
  }
}

At any point, you can call the Get Application State endpoint to see the state of the order.

Next steps

The Building a Headless Checkout page has instructions for creating a fully customized headless checkout.

Payments are processed through a Payment Isolation Gateway Interface (PIGI) iframe. Refer to the Payment Interface page for information on setting up the PIGI.