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:
- Install Bold Checkout on your store.
- Submit a support request.
- Create an API access token.
- Add a guest customer and create an order.
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.
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 support request
You may need to manually provide some information to Bold via a support request. Refer to the following sections for more information.
CORS allowlist information
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.
(Shopify only) Shopify development store information
If you create a password-protected development store on Shopify, you must also include the storefront password in your support request. Production stores do not require this step.
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 2.0 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.
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.
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.
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": "[email protected]",
"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
customerobject, with details about the customer. - An
application_statekey, 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": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"first_name": "John",
"last_name": "Doe",
"email_address": "[email protected]",
"accepts_marketing": true,
"saved_addresses": [
{
"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "Suite 200",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
},
"addresses": {
"shipping": {
"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "Suite 200",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"billing": {
"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "Suite 200",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
},
"line_items": [
{
"product_data": {
"id": "724bca",
"product_title": "Oak Cheese Grater",
"title": "Small",
"image_url": "http://shop.images/oakcheesegrater",
"properties": {
"property1": "string",
"property2": "string"
},
"description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_2643",
"barcode": "1234ABC",
"compare_at_price": 4000,
"weight": 1000,
"weight_unit": "g",
"product_id": "oak-cheese-grater",
"variant_id": "oak-cheese-grater-small",
"requires_shipping": true,
"sku": "OAK_GRATER_SM",
"taxable": true,
"tags": "Kitchen, Cheese Board, Oak",
"vendor": "Cheese Boards Unlimited",
"total_weight": 2000
},
"taxes": [
{
"value": 1000,
"name": "GST",
"is_included": true
}
],
"fees": [
{
"amount": 500,
"name": "Miscellaneous fee."
}
],
"discounts": [
{
"code": "SUMMER5",
"text": "Summer discount code",
"value": 500,
"source": "coupon"
}
],
"fulfilled_quantity": 2
}
],
"fees": [
{
"id": "123456789",
"line_text": "Custom Fee — Added by Plugin",
"fee_type": "fixed",
"value": 10,
"source": "PLUGIN",
"plugin_uuid": "a52589f8-09df-11ed-b30e-f67072e164ee",
"taxable": true,
"show_description": true
}
],
"taxes": [
{
"value": 1000,
"name": "GST",
"is_included": true
}
],
"discounts": [
{
"code": "SUMMER5",
"text": "Summer discount code",
"value": 500,
"source": "coupon"
}
],
"payments": [
{
"gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
"amount": 4700,
"currency": "CAD",
"type": "spreedly",
"display_string": "Credit Card Payment",
"id": "",
"token": "7uZAMRAf80KiEwibsrrM5IB41yU",
"retain": false
}
],
"order_total": 4700,
"order_meta_data": {
"cart_parameters": {
"key": "cp-key1",
"property1": "A cart param.",
"property2": "A cart param."
},
"note_attributes": {
"key": "na-key1",
"property1": "A note attribute",
"property2": "A note attribute"
},
"notes": "A special delivery note.",
"tags": ["order-1"]
},
"shipping": {
"selected_shipping": {
"id": "0",
"description": "Custom weight-based rate: tier 2",
"amount": 450
},
"available_shipping_lines": [
{
"id": "string",
"line": {
"id": "0",
"description": "Custom weight-based rate: tier 2",
"amount": 450
}
}
],
"taxes": [
{
"value": 245,
"name": "GST",
"is_included": false
},
{
"value": 343,
"name": "PST",
"is_included": false
}
],
"discounts": [
{
"code": "SUMMER5",
"text": "Summer discount code",
"value": 500,
"source": "coupon"
}
]
},
"resumable_link": "string",
"flow_id": "external-company-one-page-template",
"currency": {
"iso_code": "CAD",
"iso_numeric_code": 124,
"symbol": "$",
"format": "${{amount}}",
"has_decimal": true,
"show_iso_code": true
},
"created_via": "My_Order_Creating_Plugin",
"is_processed": false,
"order_id": 79047599,
"platform_order_id": "1389wjfalsdf9y4r"
}
}
}
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.