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

Delete Discount Code

Removes the discount code and its discounts 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.

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

Validate Discount Code

Validates the given discount code against the current order state and shop settings. Calling this endpoint does not change the application state or apply the discount.

It is not required to call this endpoint before calling the Add Discount Code endpoint, but it can be helpful if you want to implement custom error handling in more complicated discount code scenarios.

For more information about discount validation, refer to Validate Discount Codes.

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
discount_code
required
string
Example: discount_code=TESTCODE

The discount code to be validated.

Responses

Response samples

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

Line Items

A child of the Order resource. Contains information about the product and the taxes, fees, and discounts associated with it. Use these endpoints to manipulate line items on an order.

Add Line Item

Adds a new line item to the order.

Only products that have already been synced to Checkout can be added from the frontend. One of either the sku or the platform_id is required.

This endpoint can also add a gift card to an 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
platform_id
string

An identifier of the product on the platform.

sku
string

A merchant-defined stock-keeping unit of the line item.

quantity
required
integer

The quantity of the line item to be added to the order.

line_item_key
required
string (LineItemKey)

A unique identifier, set by the merchant, serving to refer to this line item throughout Bold Checkout. You can retrieve this value using the Products API and looking for the id on each product.

Additional Properties (object) or Gift Card Properties (object) or No properties (object) (Line Item Properties)

Any arbitrary property that you want to associate with this item. Line Items can also be Gift Cards, which have specific and unique properties.

Responses

Request samples

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

Response samples

Content type
application/json
Example
{
  • "platform_id": 5423,
  • "sku": "OAK_GRATER_SM",
  • "quantity": 2,
  • "line_item_key": "ABC123",
  • "line_item_properties": {
    }
}

List Line Items

Retrieves a list of all the items on the order. This endpoint returns the product_data for each line item 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 Line Item Quantity

Updates the quantity of the line item on the order. Refer to the line to be updated by line_item_key.

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
platform_id
string

An identifier of the product on the platform.

sku
string

A merchant-defined stock-keeping unit of the line item.

quantity
required
integer

The quantity of the line item to be added to the order.

line_item_key
required
string (LineItemKey)

A unique identifier, set by the merchant, serving to refer to this line item throughout Bold Checkout. You can retrieve this value using the Products API and looking for the id on each product.

Additional Properties (object) or Gift Card Properties (object) or No properties (object) (Line Item Properties)

Any arbitrary property that you want to associate with this item. Line Items can also be Gift Cards, which have specific and unique properties.

Responses

Request samples

Content type
application/json
{
  • "platform_id": "5423",
  • "sku": "OAK_GRATER_SM",
  • "quantity": 2,
  • "line_item_key": "ABC123",
  • "line_item_properties": {
    }
}

Response samples

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

Delete Line Item

Removes a line item from an order. Refer to the line to remove by line_item_key.

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
platform_id
string

An identifier of the product on the platform.

sku
string

A merchant-defined stock-keeping unit of the line item.

quantity
required
integer

The quantity of the line item to be added to the order.

line_item_key
required
string (LineItemKey)

A unique identifier, set by the merchant, serving to refer to this line item throughout Bold Checkout. You can retrieve this value using the Products API and looking for the id on each product.

Additional Properties (object) or Gift Card Properties (object) or No properties (object) (Line Item Properties)

Any arbitrary property that you want to associate with this item. Line Items can also be Gift Cards, which have specific and unique properties.

Responses

Request samples

Content type
application/json
{
  • "platform_id": "5423",
  • "sku": "OAK_GRATER_SM",
  • "quantity": 2,
  • "line_item_key": "ABC123",
  • "line_item_properties": {
    }
}

Response samples

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

Metadata

A child of the Order resource. Contains metadata about the order, including cart parameters, note attributes, nots, and tags. Use these endpoints to manipulate the metadata on an order.

Append Order Metadata

Append to any of the metadata attached to an 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
Cart parameters (object) or Array of No cart parameters (strings)

Extra information about an order that Checkout can act upon.

Note attributes (object) or Array of No note attributes (strings)

Extra information added to the order and pushed to the platform.

notes
string

Notes that can be attached to the order.

tags
Array of strings

Tags attached to the order.

Responses

Request samples

Content type
application/json
Example
{
  • "cart_parameters": {
    },
  • "note_attributes": {
    },
  • "notes": "A different delivery instruction.",
  • "tags": [
    ]
}

Response samples

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

Clear Order Metadata

Clears the order of all the metadata.

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

List Order Metadata

List All the Metadata Attached to an 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
Example
{
  • "data": {
    }
}

Overwrite Order Metadata

Add Metadata to an 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

Any existing metadata will be overwritten by the values provided in this request.

Cart parameters (object) or Array of No cart parameters (strings)

Extra information about an order that Checkout can act upon.

Note attributes (object) or Array of No note attributes (strings)

Extra information added to the order and pushed to the platform.

notes
string

Notes that can be attached to the order.

tags
Array of strings

Tags attached to the order.

Responses

Request samples

Content type
application/json
{
  • "cart_parameters": {
    },
  • "note_attributes": {
    },
  • "notes": "Special delivery instruction.",
  • "tags": [
    ]
}

Response samples

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

Orders

Contains information about a single order, including the full application state of the order. Use these endpoints to retrieve the application state, manipulate order metadata, process the order, and complete other order-related functions.

Process Order

Triggers the backend processing of the order.

Before processing the order, Bold completes a series of checks to ensure taxes are calculated and the order contains payments that equal the order total.

During processing, Bold completes the following steps:

  • Taxes are calculated and present on order.
  • Verify that inventory is adequate to fulfill the order (optional, based on platform settings).
  • Pre-authorize any pending payments.
  • Finalize and apply discounts.

If these steps complete successfully, this endpoint returns a success message.

Once order processing is complete, Bold asynchronously pushes each order to the platform and charges authorized payments.

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

Pre-Process Order

Prompts Bold Checkout to execute all the checks required before processing an order, without actually completing the order processing.

These steps include an inventory check, order validation and payment authorization. For a full list, refer to the Process Order description.

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

Handle Amendment

Prompts Bold Checkout to handle any amendments that have been made to the order, such as product upsells and other pre-processing order adjustments.

Bold re-checks the order for an outstanding balance. If one exists, Bold copies the existing payment on the order and creates a separate authorization.

Note: If the order value has changed, handle_amendment can only add and authorize the required additional payment if:

  • There is only one payment method on the order.
  • That payment is either a credit card or PayPal payment.
  • The gateway used to process that payment is not PayPal Complete Payments (PPCP).
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": {
    }
}

Get Application State

Gets a refreshed copy of the application state. Useful if there are other plugins or applications that might be interacting with 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": {
    }
}

Dispatch App Hook Event

Dispatches the app_hook plugin event to the plugin with the matching client ID provided in the request (given this plugin is registered for the app_hook event). For more information about the app_hook event, refer to Create Custom Events with App Hooks.

The plugin processes the request, and returns a response that indicates the actions to be executed by Checkout. Checkout completes these actions, and this endpoint then returns an up-to-date version of the application_state.

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
uuid
required
string

The unique identifier of the plugin that is expected to receive the app_hook event. The client ID was sent to the developer upon creation of the plugin.

hook
required
string

The name of the app_hook event to send to the plugin.

app_hook_data
object

Data that will be provided as part of the app_hook plugin Event payload.

Responses

Request samples

Content type
application/json
{
  • "uuid": "93225ea4-d701-41f9-a30a-bfe66f5d0479",
  • "hook": "age_verified",
  • "app_hook_data": {
    }
}

Response samples

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

Check Order Inventory

Triggers an inventory check on the items in the cart. The check can only be performed if the store enabled inventory checks; otherwise, this endpoint returns a not_enabled response. Functionally, this means that Checkout may proceed as if the check had passed.

If the inventory check is enabled, Checkout looks for an inventory override present on the order. If one is present, Checkout calls the override endpoint and returns the results yielded by that endpoint. If no override is present, Checkout uses the inventory policy on the store platform to determine whether the items on the order are in stock. For more information about inventory overrides, refer to the Plugin Actions Reference.

If Checkout is able to complete the inventory check, it returns a result of either pass or fail depending on the result of the check. If the result is fail, Checkout also returns a list of the items that failed the check, along with their available quantities.

If Checkout is unable to complete the inventory check for some external reason (for example, due to a network failure), Checkout returns an error response indicating that the check could not be completed.

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
stage
string
Default: "initial"
Enum: "initial" "final"

The context in which the inventory check is to be performed. Specify this value only when using an inventory override. The override provider must interpret this value, as it has no impact on Bold Checkout functionality. Allowable values are initial or final. For most use cases, the value should be initial to indicate that the order has not been processed. Checkout automatically performs an inventory check when an order is being processed and uses the value final if an inventory override is place at this time.

Responses

Response samples

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

Payments

A child of the Order resource. Contains information about the payments on an order. Use these endpoints to manipulate the payments on an order.

Create Payment

Adds a new payment to 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

The payment gateway_public_id tells Bold Checkout which payment gateway to use and is therefore required. The token key is also required.

The amount is optional. If this value is left empty, Bold Checkout sets the payment amount to the order total or to the maximum value that the payment method supports (e.g., for a gift card payment).

gateway_public_id
required
string

A public identifier of the payment gateway used with the payment.

amount
number

The payment amount, represented in cents/base currency units, using ISO-4217 standards.

currency
string

The currency of the payment, using ISO-4217 standards.

type
string

The payment gateway that accepted the payment.

display_string
string

A description of the payment to visually display to the customer.

token
required
string

A token generated by the payment gateway to identify the payment.

wallet_pay_type
string
Enum: "applepay" "paywithgoogle" "paypal"

The identifier for a wallet/express payment provider, if applicable for the payment.

The current supported wallet/express payment providers are:

  • Apple Pay (applepay)
  • Pay with Google (paywithgoogle)
  • PayPal (paypal)
retain
boolean
Default: false

Indicates whether the payment method will be saved for future orders. Checkout only stores a tokenized version of the payment method.

payment_parameters
object

Additional payment data, if necessary for the payment gateway.

If payment_parameters is empty, its value is an empty array ([]).

Responses

Request samples

Content type
application/json
{
  • "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
  • "amount": 4700,
  • "currency": "CAD",
  • "type": "spreedly",
  • "display_string": "Credit Card Payment",
  • "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
  • "wallet_pay_type": "applepay",
  • "retain": false,
  • "payment_parameters": {
    }
}

Response samples

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

List Payments

Lists the payments that have been applied to 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 Payment

Updates the value of the payment. Only the amount of payment can be changed.

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
gateway_public_id
required
string

A public identifier of the payment gateway used with the payment.

amount
number

The payment amount, represented in cents/base currency units, using ISO-4217 standards.

currency
string

The currency of the payment, using ISO-4217 standards.

type
string

The payment gateway that accepted the payment.

display_string
string

A description of the payment to visually display to the customer.

token
required
string

A token generated by the payment gateway to identify the payment.

wallet_pay_type
string
Enum: "applepay" "paywithgoogle" "paypal"

The identifier for a wallet/express payment provider, if applicable for the payment.

The current supported wallet/express payment providers are:

  • Apple Pay (applepay)
  • Pay with Google (paywithgoogle)
  • PayPal (paypal)
retain
boolean
Default: false

Indicates whether the payment method will be saved for future orders. Checkout only stores a tokenized version of the payment method.

payment_parameters
object

Additional payment data, if necessary for the payment gateway.

If payment_parameters is empty, its value is an empty array ([]).

Responses

Request samples

Content type
application/json
{
  • "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
  • "amount": 4700,
  • "currency": "CAD",
  • "type": "spreedly",
  • "display_string": "Credit Card Payment",
  • "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
  • "wallet_pay_type": "applepay",
  • "retain": false,
  • "payment_parameters": {
    }
}

Response samples

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

Remove Payment

Removes the payment by token.

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
gateway_public_id
required
string

A public identifier of the payment gateway used with the payment.

amount
number

The payment amount, represented in cents/base currency units, using ISO-4217 standards.

currency
string

The currency of the payment, using ISO-4217 standards.

type
string

The payment gateway that accepted the payment.

display_string
string

A description of the payment to visually display to the customer.

token
required
string

A token generated by the payment gateway to identify the payment.

wallet_pay_type
string
Enum: "applepay" "paywithgoogle" "paypal"

The identifier for a wallet/express payment provider, if applicable for the payment.

The current supported wallet/express payment providers are:

  • Apple Pay (applepay)
  • Pay with Google (paywithgoogle)
  • PayPal (paypal)
retain
boolean
Default: false

Indicates whether the payment method will be saved for future orders. Checkout only stores a tokenized version of the payment method.

payment_parameters
object

Additional payment data, if necessary for the payment gateway.

If payment_parameters is empty, its value is an empty array ([]).

Responses

Request samples

Content type
application/json
{
  • "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
  • "amount": 4700,
  • "currency": "CAD",
  • "type": "spreedly",
  • "display_string": "Credit Card Payment",
  • "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
  • "wallet_pay_type": "applepay",
  • "retain": false,
  • "payment_parameters": {
    }
}

Response samples

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

Remove Gift Card Payment

Removes a gift card payment by ID.

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
id
string (Gift Card Payment ID)

The ID of the gift card payment. Find the ID by reading the application state payments array. Refer to Get Application State.

Responses

Request samples

Content type
application/json
{
  • "id": "2"
}

Response samples

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

Payment Iframes

Contains information about the Secure Payments Interface (SPI). Use these endpoints to manipulate the SPI iFrame.

Create CSS Styling for SPI

Use this endpoint to style the Secure Payments Interface (SPI) using CSS and media queries for a single order.

After calling this endpoint, you must update the SPI iframe with the new styling. Use the Update Media Match Action to send the new styling to your SPI event listener.

For more information, refer to the SPI documentation.

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

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

Shipping Lines

A child of the Order resource. Contains information about the order's shipping line, which is created via the Bold Checkout admin. Use these endpoints to manipulate the shipping lines set on an order.

Set Shipping Line

Sets the shipping line to one of the available shipping lines on the order. Shipping lines can only be set by index and cannot be set directly.

Use the Bold Checkout admin to create and configure shipping lines for your store.

Note: Checkout admin settings can override schema representation for shipping lines. If "Default Shipping Option" is set to Least/Most expensive first in the Bold Checkout admin, the shipping lines returned in this endpoint are ordered according to that setting.

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
index
string

The index of a shipping line. Find the desired shipping line index using the List Shipping Lines endpoint.

Responses

Request samples

Content type
application/json
{
  • "index": "0"
}

Response samples

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

List Shipping Lines

Retrieves the shipping lines configured on the store.

Use the Bold Checkout admin to create and configure shipping lines for your store.

Note: Checkout admin settings can override schema representation for shipping lines. If "Default Shipping Option" is set to Least/Most expensive first in the Bold Checkout admin, the shipping lines returned in this endpoint are ordered according to that setting.

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

Estimate Shipping Line

Generates an estimate for the order's shipping line and shipping cost based on the shipping address provided.

Based on the address provided, this endpoint adds a shipping_address and an additional entry in the available_shipping_lines array. It does not, however, select that shipping line for the order.

Note: This endpoint is only supported on stores that use a Remote State Authority (RSA). With RSA set up, this endpoint triggers the estimate_shipping event.

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
string

The country name.

city
string

The city name.

province
string

The province or state name, if applicable.

country_code
string

The country code, in ISO 3166 format.

province_code
string

The province or state code, in ISO 3166 format, if applicable.

postal_code
string

The postal/zip code. Validated on format only when provided.

business_name
string

The business name, if applicable.

phone_number
string

The phone number of the addressee.

Responses

Request samples

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

Taxes

A child of the Order resource. Contains information about order-level taxes. Use these endpoints to generate order-level taxes.

Generate Taxes

Calculates and applies taxes to the order. Calculated taxes must be present in the application_state before you call the Process Order endpoint. Otherwise, the API returns an error and does not process the order.

Before calling this endpoint, configure your store's tax settings in the Bold Checkout admin, including tax zones, the tax provider, and whether the price of shipping should be taxed.

Taxes are calculated for each line item, for the shipping (if applicable), and for the whole order — the returned application_state reflects all of these calculations.

Taxes are not automatically recalculated, so you must call this endpoint after you make any changes to the shipping address. Bold recommends calling this endpoint after calling the Set Shipping Line 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.

Responses

Response samples

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

Estimate Taxes

Generates an estimate for the order's taxes. For an accurate calculation, provide the shipping address in the request body.

This endpoint adds the shipping address to the application state but does NOT apply the estimated tax calculation to the order.

Note: This endpoint is only supported on stores that use a Remote State Authority (RSA). With RSA set up, this endpoint triggers the estimate_tax event.

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
string

The country name.

city
string

The city name.

province
string

The province or state name, if applicable.

country_code
string

The country code, in ISO 3166 format.

province_code
string

The province or state code, in ISO 3166 format, if applicable.

postal_code
string

The postal/zip code. Validated on format only when provided.

business_name
string

The business name, if applicable.

phone_number
string

The phone number of the addressee.

Responses

Request samples

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

Wallet Pay

Contains information about wallet payments. Use these endpoints to create, update, and capture wallet pay orders. These endpoints currently support PayPal only.

Create Wallet Pay Order

Triggers the creation of an order in a "wallet pay" payment gateway. Bold uses the public_order_id to retrieve order information, including payment data. Bold then sends the request body and additional order information to the payment gateway. The payment gateway uses the order information to create a new order on its platform, and returns the created order's identifier.

The specified payment gateway must already be configured in your Bold admin. To read more about connecting a payment gateway in Bold checkout, refer to the Help Center.

Note: This endpoint does not create or update orders within Bold. To do so, use Initialize Order or Create Order. To add or update a payment on an order, use Create Payment or Update Payment.

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

The data required for the order sent to the payment gateway.

Refer to the schemas below to see the required data for each supported gateway.

gateway_type
string
Value: "paypal"

The payment gateway where the order will be created. Currently supports: paypal.

PayPalGatewayOrder (object)

The properties required for the gateway (specified by gateway_type) to create an order. These properties vary between gateways.

Responses

Request samples

Content type
application/json
{
  • "gateway_type": "paypal",
  • "payment_data": {
    }
}

Response samples

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

Update Shipping Address for Wallet Pay

Handles a shipping address change event for wallet pay orders. Bold uses the provided shipping address from the payment gateway to calculate taxes and get the shipping lines.

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

The data required for the order sent to the payment gateway.

Refer to the schemas below to see the required data for each supported gateway.

gateway_type
string
Value: "paypal"

The payment gateway where the order is created. Currently supports: paypal.

PayPalWalletPayOnShipping (object)

Properties required for the gateway (specified by gateway_type) to handle this request. These properties vary between gateways.

Responses

Request samples

Content type
application/json
{
  • "gateway_type": "paypal",
  • "payment_data": {
    }
}

Response samples

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

Capture Payment for Wallet Pay

Sends the payment information to the wallet pay for capture when the user authorizes the payment. Bold calls the payment gateway to get the order details and updates the customer information, shipping address, billing address, and taxes of the order.

Note: This endpoint does NOT add the payment to the order. To add a payment, use Add Payment.

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

The data required for the order sent to the payment gateway.

Refer to the schemas below to see the required data for each supported gateway.

gateway_type
string
Value: "paypal"

The payment gateway where the order is created. Currently supports: paypal.

PayPalWalletPayOnApprove (object)

Any properties required for the gateway (specified by gateway_type) to handle this request. These properties vary between gateways.

Responses

Request samples

Content type
application/json
{
  • "gateway_type": "paypal",
  • "payment_data": {
    }
}

Response samples

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