Skip to main content
API docs by Redocly

Checkout Admin (2.0)

Download OpenAPI specification:Download

URL: https://developer-dashboard.boldcommerce.com/default/contactus Terms of Service

Use the Checkout Admin API to configure store-level settings. This includes the ability to configure overrides.

Refer to the changelog for the latest updates to this API.

For more information about Checkout, refer to the Overview.

Cross Origin Resource Sharing (CORS)

Contains information about the domains that can access the Bold Checkout APIs. Use these endpoints to manage the approved domains.

Add Domain to CORS Allowlist

Adds a domain to the list of domains with permission to call the Bold Checkout APIs.

Use this endpoint if you are self-hosting your checkout. This endpoint is also required to enable self-hosted development stores to call the Bold Checkout APIs.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
domain
string (CORSDomain)

A domain used to call the Bold Checkout APIs. The string must consist of a fully qualified domain name (FQDN) and the protocol used to access it.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get CORS Allowlist

Retrieves the list of domains with permission to call the Bold Checkout APIs.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
Example
{}

Delete Domain from CORS Allowlist

Deletes a domain from the list of domains with permission to call the Bold Checkout APIs. Specify the domain to be deleted using the domain_id in the request route.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

domain_id
required
number
Example: 1

The identifier of the domain. Retrieve the identifier using the Get CORS Allowlist endpoint.

Responses

Response samples

Content type
application/json
[
  • null
]

External Payment Gateways

Contains information about an external payment gateway that can be integrated into a store's checkout experience. Use these endpoints to manipulate the external payment gateways for a store.

Create External Payment Gateway

Adds an external payment gateway to a store.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
name
required
string

The name of the external payment gateway resource.

base_url
required
string

The base URL that Checkout calls when performing payment operations.

iframe_url
string or null

The URL to be embedded into the payment iframe.

location
string

The location during checkout that the payment iframe will be rendered.

Array of objects (Key Value Pair) [ items >= 0 items ]

An array of headers to add to requests to base_url.

api_token
string or null

An API token associated with the external payment gateway, defined by the sender. If provided, Bold includes this token in the authentication header when sending requests to this external payment gateway. For more information, refer to Verify requests from Bold Checkout.

partial_capture
required
boolean

If true, the external payment gateway supports partial payment captures.

additional_order_details
required
boolean

If true, additional metadata can be included on payments added to orders.

provider_id
required
string

The identifier, generated by the external payment gateway, that Checkout sends in payment-related requests to the gateway.

The identifier must be a unique value for each store that installs the external payment gateway.

currency
required
string = 3 characters

The currency supported by the external payment gateway, in ISO-4217 format.

Responses

Request samples

Content type
application/json
{
  • "name": "External Payment Gateway",
  • "base_url": "www.example.com/payments",
  • "iframe_url": "www.example.com/gateway",
  • "api_token": "XjqnSQWYAZXt",
  • "partial_capture": true,
  • "additional_order_details": true,
  • "provider_id": "8ad85ccf-7fd6-4f4b-a1a2-dff42fb3e228",
  • "currency": "CAD",
  • "http_headers": [
    ],
  • "location": "payment_method_below"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List External Payment Gateways

Lists external payment gateways for a given store.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update External Payment Gateway

Updates an external payment gateway on a store.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

public_gateway_id
required
string

The public identifier generated by Bold Checkout adds a payment gateway to a store.

Request Body schema: application/json
name
required
string

The name of the external payment gateway resource.

base_url
required
string

The base URL that Checkout calls when performing payment operations.

iframe_url
string or null

The URL to be embedded into the payment iframe.

location
string

The location during checkout that the payment iframe will be rendered.

Array of objects (Key Value Pair) [ items >= 0 items ]

An array of headers to add to requests to base_url.

api_token
string or null

An API token associated with the external payment gateway, defined by the sender. If provided, Bold includes this token in the authentication header when sending requests to this external payment gateway. For more information, refer to Verify requests from Bold Checkout.

partial_capture
required
boolean

If true, the external payment gateway supports partial payment captures.

additional_order_details
required
boolean

If true, additional metadata can be included on payments added to orders.

provider_id
required
string

The identifier, generated by the external payment gateway, that Checkout sends in payment-related requests to the gateway.

The identifier must be a unique value for each store that installs the external payment gateway.

currency
required
string = 3 characters

The currency supported by the external payment gateway, in ISO-4217 format.

Responses

Request samples

Content type
application/json
{
  • "name": "External Payment Gateway",
  • "base_url": "www.example.com/payments",
  • "iframe_url": "www.example.com/gateway",
  • "api_token": "XjqnSQWYAZXt",
  • "partial_capture": true,
  • "additional_order_details": true,
  • "provider_id": "8ad85ccf-7fd6-4f4b-a1a2-dff42fb3e228",
  • "currency": "CAD",
  • "http_headers": [
    ],
  • "location": "payment_method_below"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete External Payment Gateway

Removes an external payment gateway from a store.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

public_gateway_id
required
string

The public identifier generated by Bold Checkout adds a payment gateway to a store.

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

Gift Cards

Contains information about Gift Cards on a given store. Use this endpoint to get all data associated with a Gift Card for a store.

Get Gift Card

Gets a gift card on a given shop, specified by either the public_payment_method_id or a combination of the card_token and card_pin.

For more information, refer to the Manage Gift Cards guide.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

query Parameters
required
Public Payment Method Id (object) or Card Token and Pin (object)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Integrations

Contains a shared secret, which is used to configure the webhooks that your integration uses.

Configure Integration Settings

Configures webhooks to integrate with your shop, using a given shared secret.

Read more about configuring webhook integration in the Register for Webhooks guide.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
shared_secret
required
string

A string used to sign callback url requests for webhook subscriptions.

Responses

Request samples

Content type
application/json
{
  • "shared_secret": "96c6db504d593697229066dde7c88f2e"
}

Response samples

Content type
application/json
[ ]

Lightweight Frontend Experience (LiFE) Elements

Contains information about the Checkout Lightweight Frontend Experience (LiFE) Elements, which enable you to add custom elements into your checkout experience. Use these endpoints to add, edit, and delete elements.

Create Element

Adds a LiFE element to the store's checkout at a specific location. For more information about the locations and where they are, refer to the Checkout LiFE guide.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
location
required
string
Enum: "customer_info" "shipping" "billing_address_after" "shipping_lines" "below_actions" "summary_above_header" "payment_gateway" "thank_you_message" "order_confirmation" "order_details" "main_content_beginning" "main_content_end" "payment_method_above" "paypal_additional_information"

The location where the LiFE element will be rendered. For more information about possible element locations, refer to the Checkout LiFE guide.

input_type
required
string
Enum: "text" "checkbox" "html" "textarea" "dropdown" "datepicker"

The input type of the LiFE element.

input_default
string or null

The default input. The behavior of this field depends on the input_type:

  • text or textarea: Set this value to your chosen string. The shopper deletes the input_default and adds their own value.
  • checkbox: Set this value to "true" to make the checkbox automatically selected.
  • html: Set this value to the HTML you would like the element to display.
  • dropdown: Set the value to a comma-separated string of the options you would like the element to display.
  • datepicker: Set the value to a date string with the format of YYYY/MM/DD. If the input_default is not set, the date picker defaults to the current date.
input_label
string or null

If the element requires shopper input, this is the label for the input.

input_placeholder
string or null

The input placeholder value of the LiFE element. The behavior of this field depends on the input_type:

  • text or textarea: This value appears in the input field and disappears when the shopper begins typing.
  • checkbox: This value appears below the input_label.
  • dropdown: This value appears in the drop-down box before it is expanded.
  • datepicker: This value appears in the input field and disappears when the shopper selects a date.
input_required
required
boolean or null

Indicates whether input from the shopper is required.

input_regex
string or null

The regular expression that validates the input for text and textarea elements.

meta_data_field
required
string

The metadata key from the order's application_state that will be used to store the user's entered value.

order_asc
required
integer

The index of the element. If multiple elements appear in one location, this value indicates the order in which they appear.

Responses

Request samples

Content type
application/json
{
  • "location": "customer_info",
  • "input_type": "text",
  • "input_default": "initial value",
  • "input_label": "Shipping notes",
  • "input_placeholder": "Shipping notes here",
  • "input_required": true,
  • "input_regex": "[0-9]{4}",
  • "meta_data_field": "shipping_notes",
  • "order_asc": 1
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Elements

Lists the LiFE elements that are associated with a given store's checkout.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Element

Updates a LiFE element that already exists on a store's checkout. You can edit any of the element's attributes using this endpoint.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

public_element_id
required
string
Example: VfYRxzOjRkwG6B2xWbxhPQ

The Bold-generated identifier of the LiFE elements.

Request Body schema: application/json
location
required
string
Enum: "customer_info" "shipping" "billing_address_after" "shipping_lines" "below_actions" "summary_above_header" "payment_gateway" "thank_you_message" "order_confirmation" "order_details" "main_content_beginning" "main_content_end" "payment_method_above" "paypal_additional_information"

The location where the LiFE element will be rendered. For more information about possible element locations, refer to the Checkout LiFE guide.

input_type
required
string
Enum: "text" "checkbox" "html" "textarea" "dropdown" "datepicker"

The input type of the LiFE element.

input_default
string or null

The default input. The behavior of this field depends on the input_type:

  • text or textarea: Set this value to your chosen string. The shopper deletes the input_default and adds their own value.
  • checkbox: Set this value to "true" to make the checkbox automatically selected.
  • html: Set this value to the HTML you would like the element to display.
  • dropdown: Set the value to a comma-separated string of the options you would like the element to display.
  • datepicker: Set the value to a date string with the format of YYYY/MM/DD. If the input_default is not set, the date picker defaults to the current date.
input_label
string or null

If the element requires shopper input, this is the label for the input.

input_placeholder
string or null

The input placeholder value of the LiFE element. The behavior of this field depends on the input_type:

  • text or textarea: This value appears in the input field and disappears when the shopper begins typing.
  • checkbox: This value appears below the input_label.
  • dropdown: This value appears in the drop-down box before it is expanded.
  • datepicker: This value appears in the input field and disappears when the shopper selects a date.
input_required
required
boolean or null

Indicates whether input from the shopper is required.

input_regex
string or null

The regular expression that validates the input for text and textarea elements.

meta_data_field
required
string

The metadata key from the order's application_state that will be used to store the user's entered value.

order_asc
required
integer

The index of the element. If multiple elements appear in one location, this value indicates the order in which they appear.

Responses

Request samples

Content type
application/json
{
  • "location": "customer_info",
  • "input_type": "text",
  • "input_default": "initial value",
  • "input_label": "Shipping notes",
  • "input_placeholder": "Shipping notes here",
  • "input_required": true,
  • "input_regex": "[0-9]{4}",
  • "meta_data_field": "shipping_notes",
  • "order_asc": 1
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Element

Removes a LiFE element from a store's checkout.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

public_element_id
required
string
Example: VfYRxzOjRkwG6B2xWbxhPQ

The Bold-generated identifier of the LiFE elements.

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

Overrides

Contains information about the API overrides on a given store, such as the override type, redirect URL, and shared secret. Use these endpoints to manipulate overrides for a store.

Create API Override

Creates an API override for a given store. The API override is used to customize base functionality. Store level API overrides will apply to all orders, but per-order overrides may take priority. For more information, refer to API Overrides.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
override_type
required
string (OverrideType)
Enum: "address_validate" "shipping" "discount" "inventory" "tax"

The Checkout functionality that is overridden by this API override.

url
required
string (OverrideURL)

The destination URL at which a request will be made when functionality relating to this override_type is triggered in Checkout.

shared_secret
required
string (OverrideSharedSecret) [ 8 .. 255 ] characters

Your shared secret, a random string of sufficient length. Bold uses this string and the current date to create a signature for each override request.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

List API Overrides

Retrieves a list of registered API overrides for a given store.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{}

Update API Override

Updates the given override. Enables the caller to update the url property, the override_type property, or both, for a given API override. A store can have more than one API override of the same type.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

public_id
required
string

The identifier for the affected API override.

Request Body schema: application/json
override_type
required
string (OverrideType)
Enum: "address_validate" "shipping" "discount" "inventory" "tax"

The Checkout functionality that is overridden by this API override.

url
required
string (OverrideURL)

The destination URL at which a request will be made when functionality relating to this override_type is triggered in Checkout.

shared_secret
required
string (OverrideSharedSecret) [ 8 .. 255 ] characters

Your shared secret, a random string of sufficient length. Bold uses this string and the current date to create a signature for each override request.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete API Override

Delete an API override from the given store.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

public_id
required
string

The identifier for the affected API override.

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

Payment CSS

Contains information about the CSS used to style the Secure Payments Interface (SPI). Use these endpoints to manipulate the SPI iFrame for all orders on a store.

Get Shop Payment Styling

Gets the CSS styling that is currently applied to the SPI iframe.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create Shop Payment Styling

Create and apply a series of CSS rules and media rules to the SPI iframe. Using this endpoint applies these changes to all orders placed in the checkout.

Note that if you are using Bold-hosted checkout, these settings will be overridden by any changes to the CSS in the Bold Checkout Admin. Refer to Style the Checkout with CSS for more information.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
Array of objects

A set of CSS rules to be applied to the SPI iframe.

Array of objects

A set of media queries to be applied to the SPI iframe.

Responses

Request samples

Content type
application/json
{
  • "css_rules": [
    ],
  • "media_rules": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Shop Payment Styling

Removes all styling from the SPI iframe.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_token",
  • "error_description": "The access token is invalid or has expired"
}

Remote State Authority

Contains information about the Remote State Authority on a given store, such as the URL and shared secret. Use these endpoints to manipulate configuration details for the Remote State Authority for a store. Refer to Create a Checkout Remote State Authority for more information.

Connect Remote State Authority

Connects Remote State Authority to a given shop.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
url
required
string

The destination URL to which a request will be made when order state changes occur.

shared_secret
required
string [ 8 .. 255 ] characters

Your shared secret, which can be any string you choose. Bold uses this string and the current date to create a signature for each request.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Update Remote State Authority Connection

Updates connection to a Remote State Authority for a given shop.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
url
string

The destination URL to which a request will be made when order state changes occur.

shared_secret
string [ 8 .. 255 ] characters

Your shared secret, which can be any string you choose. Bold uses this string and the current date to create a signature for each request.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get Remote State Authority

Gets Remote State Authority connection details for a given shop.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
Example
{}

Delete Remote State Authority

Removes Remote State Authority functionality for a given shop.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Saved Payment Methods

Contains information about customers' payment methods. Use these endpoints to retrieve or modify saved payment methods.

List Saved Payment Methods

Lists all saved payment methods for a specific customer.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

public_customer_id
required
string
Example: uqw94joiefrqwo4

The public identifier for a customer, returned as the public_id field by the Create Authenticated Customer endpoint.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "cards": [
    ]
}

Delete Saved Payment Method

Deletes the saved payment method associated with a public payment identifier.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

public_payment_id
required
string
Example: W0fe4CNraY09ooQ6DUlXb0hNUBHk7LF9wZOEmVOL92qvggIUKq0ne9qcbfCSnDwZ

The public identifier for a saved payment method.

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "defaultCardId": 1
}

Shops

Contains information about the store's checkout configuration, which is set in the Bold Checkout admin.

Get Shop General Settings

Retrieves basic settings from the shop's General Settings section in the Bold Checkout admin.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Shop General Settings

Updates basic settings from the shop's General Settings section in the Bold Checkout admin.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
object

A unique value that Bold generates and uses to track orders.

enabled
boolean

Indicates whether the bold_cashier_public_order_id appears in the order's note_attributes.

Responses

Request samples

Content type
application/json
{
  • "public_order_id": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Phone Number Requirement

Updates the phone number requirement setting for a store. This setting can also be edited from the store's General Settings section in the Bold Checkout admin.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
phone_number_required
boolean

Indicates whether customers are required to enter their phone number during checkout.

Responses

Request samples

Content type
application/json
{
  • "phone_number_required": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Inventory Check Requirement

Updates the inventory check requirement setting for a store. If required, an inventory check is performed in response to the Process Order endpoint, and the endpoint returns a 422 error if there is not enough inventory to complete the order.

The inventory check is required by default. You can use this endpoint to disable the inventory check requirement during order processing.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
require_inventory_check
boolean

Indicates whether an inventory check is required when processing an order.

Responses

Request samples

Content type
application/json
{
  • "require_inventory_check": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Platform Customer Creation Setting

Updates the platform customer creation setting for a store. On many platforms, whenever Bold creates a new order, it also creates a new customer if it does not already exist on the platform. Some platforms, such as Adobe Commerce, do not behave this way natively, and attempting to create a customer during order creation can cause unexpected errors. Updating this setting to false prevents Bold from attempting to create a customer on the platform when a new order is created.

This setting defaults to true.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
create_platform_customer
boolean

Indicates whether customers should be created on the platform during order creation.

Responses

Request samples

Content type
application/json
{
  • "create_platform_customer": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get PMMC Session

Retrieves a Payment Method Management for Checkout (PMMC) session. Use this endpoint to retrieve the information necessary to load the <iframe> that enables an authenticated customer to edit their saved payment methods.

Include the either the customer's bold_customer_id or platform_customer_id as a query parameter to retrieve their payment method information.

Refer to the PMMC Guide for more information about using this information to load the PMMC <iframe> for the customer.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

query Parameters
platform_customer_id
string
Example: platform_customer_id=a90w4q2kopP23F3

A platform-generated identifier of the customer.

bold_customer_id
string
Example: bold_customer_id=uqw94joiefrqwo4

A Bold-generated identifier of the customer.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Tax Zone Settings

Contains information about tax providers for individual tax zones.

Create Tax Zone Setting

Creates or updates a tax zone setting for a tax zone. There can only be one tax zone setting for a tax zone.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

zone_id
required
integer

The identifier Bold Checkout uses for a zone. Refer to Create Zone.

Request Body schema: application/json
tax_provider
required
string
Enum: "custom" "bold" "avalara" "taxjar" "vertex" "override"

The tax provider for the tax zone. If you intend to use a tax override for the shop, set this value to override.

Responses

Request samples

Content type
application/json
{
  • "tax_provider": "override"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Tax Zone Settings

Deletes a tax zone setting for a tax zone.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

zone_id
required
integer

The identifier Bold Checkout uses for a zone. Refer to Create Zone.

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

Get Tax Zone Settings

Lists all tax zone settings for a shop.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Warehouses

Contains information about the warehouses for a given store. This information is required to retrieve shipping rates and calculate taxes.

Create Warehouse

Adds a warehouse to a given shop. Each warehouse must belong to an existing warehouse zone, and a zone can have only one warehouse. Refer to Create Zone.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

zone_id
required
integer

The identifier Bold Checkout uses for a zone. Refer to Create Zone.

Request Body schema: application/json
address
required
string

The street address of the warehouse.

address2
string or null

An additional address line.

city
required
string

The city of the warehouse.

province_code
string or null

The ISO-3166 two-letter state or province code of the warehouse.

province
string or null

The state or province of the warehouse.

country_code
required
string

The ISO-3166 two-letter country code of the warehouse.

country
required
string

The country of the warehouse.

postal_code
required
string

The postal code or zip code of the warehouse.

extended_postal_code
string or null

Additional postal code data.

Responses

Request samples

Content type
application/json
{
  • "address": "123 Main St.",
  • "address2": "c/o Buck Skaggstein",
  • "city": "American Fork",
  • "province_code": "UT",
  • "province": "Utah",
  • "country_code": "US",
  • "country": "United States",
  • "postal_code": "84003",
  • "extended_postal_code": "52"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Warehouse

Updates a warehouse.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

zone_id
required
integer

The identifier Bold Checkout uses for a zone. Refer to Create Zone.

Request Body schema: application/json
address
string

The street address of the warehouse.

address2
string or null

An additional address line.

city
string

The city of the warehouse.

province_code
string or null

The ISO-3166 two-letter state or province code of the warehouse.

province
string or null

The state or province of the warehouse.

country_code
string

The ISO-3166 two-letter country code of the warehouse.

country
string

The country of the warehouse.

postal_code
string

The postal code or zip code of the warehouse.

extended_postal_code
string or null

Additional postal code data.

Responses

Request samples

Content type
application/json
{
  • "address": "123 Main St.",
  • "address2": "c/o Buck Skaggstein",
  • "city": "American Fork",
  • "province_code": "UT",
  • "province": "Utah",
  • "country_code": "US",
  • "country": "United States",
  • "postal_code": "84003",
  • "extended_postal_code": "52"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Warehouse

Deletes a warehouse.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

zone_id
required
integer

The identifier Bold Checkout uses for a zone. Refer to Create Zone.

Responses

Response samples

Content type
application/json
{
  • "data": { }
}

List Warehouses

Lists all warehouses for a given shop.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Webhooks

Contains information about the webhooks registered on a given store. Use these endpoints to manipulate the webhooks registered on your store.

Create Webhook

Create a webhook registration by specifying the destination URL and topic.

For more information on Checkout webhooks, refer to Register for Webhooks.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
webhook_topic_id
required
integer (WebhookTopicID)

The webhook topic identifier.

callback_url
required
string (CallbackURL)

The URL that the webhook payload will be sent to.

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {}
}

Callback payload samples

Callback
Content type
application/json
{
  • "value": {
    }
}

List Webhooks

Retrieves a list of registered webhooks.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{}

Update Webhook

Updates the webhook callback URL. Webhook topics cannot be updated.

Learn more about updating webhooks in the Webhooks guide.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

webhook_topic_id
required
string

The webhook topic id.

Request Body schema: application/json
callback_url
required
string (CallbackURL)

The URL that the webhook payload will be sent to.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {}
}

Delete Webhook

Removes an existing webhook.

Learn more about removing webhooks in the Webhooks guide.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

webhook_topic_id
required
string

The webhook topic id.

Responses

Response samples

Content type
application/json
[ ]

List Webhook Topics

Gets the list of available webhook topics.

Possible webhook topics from Checkout Backend API are:

  • order/processed
  • order/created
  • order/fulfilled
  • order/abandoned
  • order/failed
  • gift_card/created

Read about webhook topics in the Webhook Topics guide.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Zones

Contains information about the zones for a given store. Use these endpoints to manipulate the shipping zones, tax zones, and warehouse zones for a store.

Tip: Some operations in Checkout require at least one zone to be created. If you have no interest in specific regions, you can use a default zone instead.

Create Zone

Adds a warehouse, shipping, or tax zone.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Request Body schema: application/json
name
required
string

A user-friendly name for the zone.

type
required
string
Enum: "shipping" "tax" "warehouse"

The type of zone to create.

default
boolean
Default: false

Whether this zone should be used in the absence of any other applicable zone. There may only be one default zone for each zone type.

enabled
boolean
Default: true

Whether this zone can be used during Checkout.

required
Array of objects (Regions) [ items >= 0 items ]

An array of regions encompassed by this zone.

Responses

Request samples

Content type
application/json
{
  • "name": "Western Region",
  • "type": "warehouse",
  • "regions": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Zones

Lists all zones for a shop.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Zone

Updates an existing zone. Note that it is not possible to update an existing zone's type.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

zone_id
required
integer

The identifier Bold Checkout uses for a zone. Refer to Create Zone.

Request Body schema: application/json
name
string

A user-friendly name for the zone.

default
boolean
Default: false

Whether this zone should be used if no other zone is applicable. There may only be one default zone for each zone type.

enabled
boolean
Default: true

Whether this zone can be used during checkout.

Array of objects (Regions) [ items >= 0 items ]

An array of regions encompassed by this zone.

Responses

Request samples

Content type
application/json
{
  • "name": "Western Region",
  • "default": true,
  • "enabled": false,
  • "regions": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Zone

Deletes an existing zone. Any regions, tax zone settings, and warehouses associated with the zone will also be deleted.

Authorizations:
OAuthTokenAPIAccessToken
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop, which can be retrieved by making a request to the Get Shop Info endpoint.

zone_id
required
integer

The identifier Bold Checkout uses for a zone. Refer to Create Zone.

Responses

Response samples

Content type
application/json
{
  • "data": { }
}