Skip to main content
API docs by Redocly

Checkout Frontend (2.0)

Download OpenAPI specification:Download

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

The Checkout Frontend API is used to interact with an order. This includes the ability to get and manipulate order details from a browser.

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

For more information about Checkout, refer to the Overview.

Addresses

A child of the Order resource. Contains information about shipping and billing addresses. Use these endpoints to add shipping and billing addresses to an order.

Set Shipping Address

Sets the shipping address on the order.

Each order can have only one shipping address. If you call this endpoint and a shipping address already exists, the existing address is overwritten.

Set Shipping Address calls Validate Address before setting the shipping address.

Note: Checkout admin settings can override schema requirements for phone_number and business_name. If phone_number or business_name are set to required in the Bold Checkout admin, they are also required in this endpoint.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
first_name
string

The first name of the addressee.

last_name
string

The last name of the addressee.

address_line_1
string

The street address.

address_line_2
string

Any additional street address details (apt #, suite #, etc).

country
required
string

The country name.

city
string

The city name.

province
string

The province or state name, if applicable. If show_province is set to true, this field is required.

country_code
required
string

The country code, in ISO 3166 format.

province_code
string

The province or state code, in ISO 3166 format, if applicable. If show_province is set to true, this field is required.

postal_code
string

The postal/zip code. Required for most countries, including the United States, Canada, and Mexico. Validated on format only when provided.

business_name
string

If applicable, the business name.

phone_number
string

The phone number of the addressee.

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Get Shipping Address

Gets the shipping address on the order.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Responses

Response samples

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

Update Shipping Address

Updates the shipping address on the order.

This endpoint updates all fields of the shipping address. Any value left blank in the request body will be made blank in the updated address. The fields country, country_code, province, and province_code cannot be left blank.

Note: Checkout admin settings can override schema requirements for phone_number and business_name. If phone_number or business_name are set to required in the Bold Checkout admin, they are also required in this endpoint.

Note: If taxes were previously calculated, changes to the shipping address may affect those calculations. Taxes are not recalculated automatically, so you must call the Generate Taxes endpoint to recalculate taxes for the order.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
first_name
string

The first name of the addressee.

last_name
string

The last name of the addressee.

address_line_1
string

The street address.

address_line_2
string

Any additional street address details (apt #, suite #, etc).

country
required
string

The country name.

city
string

The city name.

province
string

The province or state name, if applicable. If show_province is set to true, this field is required.

country_code
required
string

The country code, in ISO 3166 format.

province_code
string

The province or state code, in ISO 3166 format, if applicable. If show_province is set to true, this field is required.

postal_code
string

The postal/zip code. Required for most countries, including the United States, Canada, and Mexico. Validated on format only when provided.

business_name
string

If applicable, the business name.

phone_number
string

The phone number of the addressee.

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Delete Shipping Address

Clears the shipping address from the order.

Note: If taxes were previously calculated, changes to the shipping address may affect those calculations. Taxes are not recalculated automatically, so you must call the Generate Taxes endpoint to recalculate taxes for the order.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Responses

Response samples

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

Set Billing Address

Sets the billing address on the order.

Each order can have only one billing address. If you call this endpoint and a billing address already exists, the existing address will be overwritten.

Set Billing Address calls Validate Address before setting the billing address.

Note: Checkout admin settings can override schema requirements for phone_number and business_name. If phone_number or business_name are set to required in the Bold Checkout admin, they are also required in this endpoint.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
first_name
string

The first name of the addressee.

last_name
string

The last name of the addressee.

address_line_1
string

The street address.

address_line_2
string

Any additional street address details (apt #, suite #, etc).

country
required
string

The country name.

city
string

The city name.

province
string

The province or state name, if applicable. If show_province is set to true, this field is required.

country_code
required
string

The country code, in ISO 3166 format.

province_code
string

The province or state code, in ISO 3166 format, if applicable. If show_province is set to true, this field is required.

postal_code
string

The postal/zip code. Required for most countries, including the United States, Canada, and Mexico. Validated on format only when provided.

business_name
string

If applicable, the business name.

phone_number
string

The phone number of the addressee.

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Get Billing Address

Get the billing address on the order.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Responses

Response samples

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

Update Billing Address

Updates the billing address on the order.

This endpoint updates all fields of the billing address associated with the order, and any value left blank in this request body will be made blank in the updated address. The fields country, country_code, province, and province_code cannot be left blank.

Note: Checkout admin settings can override schema requirements for phone_number and business_name. If phone_number or business_name are set to required in the Bold Checkout admin, they are also required in this endpoint.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
first_name
string

The first name of the addressee.

last_name
string

The last name of the addressee.

address_line_1
string

The street address.

address_line_2
string

Any additional street address details (apt #, suite #, etc).

country
required
string

The country name.

city
string

The city name.

province
string

The province or state name, if applicable. If show_province is set to true, this field is required.

country_code
required
string

The country code, in ISO 3166 format.

province_code
string

The province or state code, in ISO 3166 format, if applicable. If show_province is set to true, this field is required.

postal_code
string

The postal/zip code. Required for most countries, including the United States, Canada, and Mexico. Validated on format only when provided.

business_name
string

If applicable, the business name.

phone_number
string

The phone number of the addressee.

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Delete Billing Address

Clears the billing address from the order.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Responses

Response samples

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

Validate Address

Validates if the given postal code matches up with postal codes from Canada, US, Ireland, Great Britain, France or Singapore. This endpoint also validates the state/province provided, if required by country. Countries that require a state/province in their address are listed in the Country and Province/State Requirements reference.

Calls to the Set Shipping Address, Set Billing Address, Update Shipping Address, or Update Billing Address endpoints apply the same validations applied by this endpoint.

Calling this endpoint does not change the application state or apply the address. While not required, it can be helpful to call this endpoint before setting or updating an address on an order, especially if you want to implement custom error handling in more complicated address scenarios.

Note: Checkout admin settings can override schema requirements for phone_number and business_name. If phone_number or business_name are set to required in the Bold Checkout admin, they are also required in this endpoint.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
first_name
string

The first name of the addressee.

last_name
string

The last name of the addressee.

address_line_1
string

The street address.

address_line_2
string

Any additional street address details (apt #, suite #, etc).

country
required
string

The country name.

city
string

The city name.

province
string

The province or state name, if applicable. If show_province is set to true, this field is required.

country_code
required
string

The country code, in ISO 3166 format.

province_code
string

The province or state code, in ISO 3166 format, if applicable. If show_province is set to true, this field is required.

postal_code
string

The postal/zip code. Required for most countries, including the United States, Canada, and Mexico. Validated on format only when provided.

business_name
string

If applicable, the business name.

phone_number
string

The phone number of the addressee.

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Batch Process

Enables batch processing of certain Checkout Frontend endpoints.

Batch Process

Processes a series of API calls in a single request. Sub-requests are evaluated serially. If one of the sub-requests returns an error, processing halts and any requests after the failed request are not processed.

Not all endpoints support batch processing. For a full list of supported endpoints and additional information, refer to Submit a Batch Processing Request.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
Array of objects (Sub-Request)
Array
endpoint
string

The last sub-route of the endpoint URL for the sub-request. For the full list of supported endpoints, refer to the Submit a Batch Processing Event guide.

method
string

The HTTP method for the sub-request.

payload
object

The complete payload of the sub-request, formatted identically to a non-batch request, as defined in this specification.

Responses

Request samples

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

Response samples

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

Customers

A child of the Order resource. Contains information about guest customers on your store, including name and email. Use these endpoints to add or remove a guest customer to an order.

Create Guest Customer

Creates a new guest customer and associates it with the order.

You cannot create a new guest customer when there is already one on the order.

To add a new guest customer to an order or add an authenticated customer, you must first delete the existing customer using the Delete Customer endpoint.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
first_name
required
string

The customer's first name.

last_name
required
string

The customer's last name.

email_address
required
string

The customer's email address.

accepts_marketing
boolean
Default: false

If the customer would like to receive any sort of marketing emails. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "email_address": "[email protected]",
  • "accepts_marketing": false
}

Response samples

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

Update Guest Customer Deprecated

Note: This endpoint is deprecated. Instead, use the Update Customer endpoint to make edits to the customer on the order.

Updates the guest customer on the order.

Cannot update customer data that was provided from the Initialize Order endpoint.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
first_name
required
string

The customer's first name.

last_name
required
string

The customer's last name.

email_address
required
string

The customer's email address.

accepts_marketing
boolean
Default: false

If the customer would like to receive any sort of marketing emails. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "email_address": "[email protected]",
  • "accepts_marketing": false
}

Response samples

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

Update Customer

Updates the customer on the order. This endpoint does not update the platform_id, public_id, or saved_addresses fields. You can add customers to the order via the Initialize Order, the Create Authenticated Customer and the Create Guest Customer endpoints.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
first_name
required
string

The customer's first name.

last_name
required
string

The customer's last name.

email_address
required
string

The customer's email address.

accepts_marketing
boolean
Default: false

If the customer would like to receive any sort of marketing emails. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "email_address": "[email protected]",
  • "accepts_marketing": false
}

Response samples

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

Get Customer

Retrieves information about the customer on the order.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Responses

Response samples

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

Delete Customer

Deletes the customer from the order.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Responses

Response samples

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

Validate Email Address

Validates the email address and performs an MX check to make sure the domain can accept email.

Note that this endpoint does not validate that the the email address exists on the domain.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

query Parameters
email_address
required
string

The email address to be validated.

Responses

Response samples

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

Discounts

Contains information about discount codes that have been applied to an order. Use these endpoints to manipulate discount codes on an order.

Add Discount Code

Applies a discount code to the current order.

This endpoint applies an order-level discount code with a source of coupon. Each order may have only one coupon discount. If you attempt to add more than one, this endpoint returns an error, and the second discount code is not added.

To add a discount code at the line item level, refer to the discount_line_items plugin action.

Note: This endpoint does not create a new discount code. New discount codes can be created in the Bold Checkout admin.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Request Body schema: application/json
code
required
string

The discount code.

Responses

Request samples

Content type
application/json
{
  • "code": "FREESHIPPING"
}

Response samples

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

List Discount Codes

Retrieves all discount codes applied to the order, shipping, or individual line items, if applicable. If the order is not discounted, the endpoint returns an empty discounts array.

Authorizations:
JWT
path Parameters
shop_identifier
required
string
Example: zp3oafdor9

The identifier of the shop. Can be retrieved by making a request to the Get Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The public order identifier generated when the order is initialized by making a request to the Initialize Order endpoint.

Responses

Response samples

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