Skip to main content
API docs by Redocly

Checkout Backend (2.0)

Download OpenAPI specification:Download

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

The Checkout Backend API is used to initialize an order through authenticated requests. This includes the ability to create and manipulate orders in Checkout.

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

For more information about Checkout, refer to the Overview.

Customers

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

Delete Customer

Deletes the customer from the order.

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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

Responses

Response samples

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

Create Authenticated Customer

Creates a new authenticated customer.

You cannot create a customer when a customer already exists on the order.

If you wish to add a new authenticated customer to an order, you must first delete the existing customer using the Delete Customer 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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

Request Body schema: application/json
platform_id
required
string or null

The platform identifier for an authenticated customer. For guest customers, the value for this property will be null.

public_id
string or null

The public identifier generated by Checkout for a customer.

first_name
string

The customer's first name.

last_name
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
{
  • "platform_id": "50942578465125",
  • "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email_address": "[email protected]",
  • "accepts_marketing": false
}

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 update information about one or multiple line items.

Update Line Item

Updates the fulfilled_quantity property of a single line item.

For more information, refer to the Fulfill an Order 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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

line_item_key
required
string (LineItemKey)
Example: oak_cheese_grater_2643

A merchant-defined, unique identifier serving to refer to this line throughout Bold Checkout.

Request Body schema: application/json
fulfilled_quantity
integer

The fulfilled quantity of a line item in an order.

Responses

Request samples

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

Response samples

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

Update Line Items

Updates the fulfilled_quantity property of multiple line items.

For more information, refer to the Fulfill an Order 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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

Request Body schema: application/json
Array of objects (Line Item Patch)
Array
line_item_key
required
string (LineItemKey)

A merchant-defined, unique identifier serving to refer to this line throughout Bold Checkout.

fulfilled_quantity
integer

The fulfilled quantity of a line item in an order.

Responses

Request samples

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

Response samples

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

Orders

Contains information about a single order, including the JWT, order ID, and application state. Use these endpoints to initialize, refresh, or cancel an order.

Initialize Order

Initializes an order and retrieves a JWT. You must use the JWT to authorize all requests to the Checkout Frontend API.

The request body of this endpoint is flexible — you can use dynamic data from the platform to provide information about the cart and customer, or leave it blank and populate the order later. If you initialize an empty order, the Populate a Checkout Order page outlines a suggested flow for adding information to the order after calling this endpoint.

Note: You must call this endpoint from your backend application. This endpoint returns information that is not safe to share with the frontend application.

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 Info endpoint.

Request Body schema: application/json
cart_id
string (CartID)

Identifier of an existing cart to load from the platform. This field is unsupported when using a custom platform.

access_token
string (AccessToken)

An optional string token that you can pass to the platform. For example, use this field if your platform requires an authentication token to retrieve cart information (commercetools).

Array of Generic Cart Item (object) or SKU Cart Item (object) or Variant ID Cart Item (object)

An array of items to add to the cart. Note that the "Generic Cart Item" type is only supported by BigCommerce, commercetools, and Shopify.

object (Customer)

An authenticated or guest customer associated with an order.

object (Order Metadata)

Additional information about an order. Metadata can be used as data proxy that Checkout will act upon. It can also be used to include extra information about an order and included when pushed to the platform.

resumable_link
string or null (ResumableLink)

A URL used to resume an order. If provided, the default resumable link generated by Checkout will be overwritten with this URL. This resumable link will be provided in the email and webhook for an abandoned checkout.

flow_id
string or null (FlowId) <= 255 characters

An identifier for the origin checkout flow that created the order. The field is optional for custom checkout flows and other clients, but provides a convenience for determining the order's origin.

Bold-hosted templates provide this field and are identified by the first 4 letters "bold", which are reserved. The value "unassigned" is reserved for when the field is not provided.

For more information, refer to Checkout Flows

api_session_id
string (ApiSessionId) <= 255 characters

An optional alphanumeric identifier used to group orders for the purpose of tracking order completion rates. If this value is not provided, Bold generates one randomly and assumes that the order is not grouped with any others.

For more information, refer to Configure Checkout Flow Metrics.

Responses

Request samples

Content type
application/json
Example
{
  • "cart_id": "1snVSJAWYWWYhfLWq9ABcXMwx8mcvh2U",
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Response samples

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

Resume Order

Use this endpoint to resume an existing order, such as one that was previously abandoned.

You can also use this endpoint can also be used to generate a new JWT for an order. Each JWT expires after 60 minutes.

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 Info endpoint.

Request Body schema: application/json
public_order_id
string (Public Order ID)

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

Responses

Request samples

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

Response samples

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

Create Order

Use this endpoint to create and process a full order without additional API interaction. You can also use this endpoint to create a portion of an order, to be completed at a later time.

For more information about using this endpoint, refer to Programmatically Create an Order.

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 Info endpoint.

Request Body schema: application/json
idempotency_key
required
string

A unique identifier for this transaction. If the API receives multiple requests with the same key, it always picks up where it left off, and no duplicate orders are created.

cart_id
string (CartID)

Identifier of an existing cart to load from the platform. This field is unsupported when using a custom platform.

access_token
string (AccessToken)

An optional string token that you can pass to the platform. For example, use this field if your platform requires an authentication token to retrieve cart information (commercetools).

Array of Generic Cart Item (object) or SKU Cart Item (object) or Variant ID Cart Item (object)

Array of items to add to the cart. If using in conjunction with cart_id, these items will be added to the existing cart alongside existing items in the cart.

object (Customer)

An authenticated or guest customer associated with an order.

object or null (Address)

A shipping or billing address.

object or null (Address)

A shipping or billing address.

object

The order's shipping information.

Array of Existing Discount Code (object) or New Discount (object) (Discounts) >= 0 items

The order's discount information.

Array of objects

The fees applied to order. Note that order-level fees are only supported by Shopify and custom platforms.

Array of Customer default payment method (object) or Payment method (object)

An array of payments to apply to the order. Bold first processes payments with amounts, followed by those without amounts. Within these groups, payments are applied in the order they are received, and Bold stops processing payments when the order total is reached.

currency
string

Currency code for the order, using ISO-4217 standards. If none is given, the store default will be used.

object (Order Metadata)

Additional information about an order. Metadata can be used as data proxy that Checkout will act upon. It can also be used to include extra information about an order and included when pushed to the platform.

object

A list of commands for Bold Checkout to perform on the created order, with integer keys. Bold executes these commands in sorted order based on keys.

flow_id
string or null (FlowId) <= 255 characters

An identifier for the origin checkout flow that created the order. The field is optional for custom checkout flows and other clients, but provides a convenience for determining the order's origin.

Bold-hosted templates provide this field and are identified by the first 4 letters "bold", which are reserved. The value "unassigned" is reserved for when the field is not provided.

For more information, refer to Checkout Flows

api_session_id
string (ApiSessionId) <= 255 characters

An optional alphanumeric identifier used to group orders for the purpose of tracking order completion rates. If this value is not provided, Bold generates one randomly and assumes that the order is not grouped with any others.

For more information, refer to Configure Checkout Flow Metrics.

Responses

Request samples

Content type
application/json
Example
{
  • "cart_items": [
    ],
  • "customer": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "discounts": [
    ],
  • "payments": [
    ],
  • "currency": "USD",
  • "idempotency_key": "2b268b6f-b3c0-4efb-9c43-1aa59d535182",
  • "commands": {
    }
}

Response samples

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

Cancel Order

Cancels an order, voiding any held authorizations. This endpoint fails if the order is already fulfilled or any payments were captured.

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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

Request Body schema: application/json
reason
string

An optional order cancellation reason.

Responses

Request samples

Content type
application/json
{
  • "reason": "Duplicate order."
}

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 capture partial or full payments.

Capture Payment for Arbitrary Amount

Captures a payment for the amount specified against the order total (shipping, taxes, etc., included).

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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

Request Body schema: application/json
reauth
required
boolean
Default: true

Whether or not Checkout should attempt to re-authorize payment if the authorize transaction has been used or expired.

idempotent_key
string

A unique idempotency key generated by the client which the server uses to recognize subsequent retries of the same requests.

capture_data
object

Any data associated with the payment capture request.

amount
required
number

Amount to capture, represented in base currency units, using ISO-4217 standards.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 1200,
  • "reauth": true,
  • "idempotent_key": "2b268b6f-b3c0-4efb-9c43-1aa59d535182",
  • "capture_data": {
    }
}

Response samples

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

Capture Specific Payment

Manually authorizes and charges the amount specified to a payment on the order. The payment must have an awaitingPreAuth status. The payment is applied against the order total (including shipping, taxes, etc.).

This endpoint enables you to delay the payment capture process. Normally, Bold Checkout adds payments to the order with a preAuthed status, indicating they have already been authorized for the given amount. When Bold is set up to only verify the payments, each payment is added to the order with a awaitingPreAuth status.

Notes:

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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

payment_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The identifier assigned to each unique payment.

Request Body schema: application/json
reauth
required
boolean
Default: true

Whether or not Checkout should attempt to re-authorize payment if the authorize transaction has been used or expired.

idempotent_key
string

A unique idempotency key generated by the client which the server uses to recognize subsequent retries of the same requests.

capture_data
object

Any data associated with the payment capture request.

amount
required
number

Amount to capture, represented in base currency units, using ISO-4217 standards.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 1200,
  • "reauth": true,
  • "idempotent_key": "2b268b6f-b3c0-4efb-9c43-1aa59d535182",
  • "capture_data": {
    }
}

Response samples

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

Capture Payment for Full Order Amount

Captures a payment for the full order total amount (including shipping, taxes, etc).

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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

Request Body schema: application/json
reauth
required
boolean
Default: true

Whether or not Checkout should attempt to re-authorize payment if the authorize transaction has been used or expired.

idempotent_key
string

A unique idempotency key generated by the client which the server uses to recognize subsequent retries of the same requests.

capture_data
object

Any data associated with the payment capture request.

Responses

Request samples

Content type
application/json
{
  • "reauth": true,
  • "idempotent_key": "2b268b6f-b3c0-4efb-9c43-1aa59d535182",
  • "capture_data": {
    }
}

Response samples

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

Authorize Payments

Authorizes all payments on the order. Payments must be present on the order before calling this endpoint. When this endpoint is called, Bold Checkout calls the appropriate payment gateways to authorize all payments on the order.

If one payment fails authorization, Bold refunds or voids all payments on the order.

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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

Responses

Response samples

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

Refunds

Contains information about any refunds applied to the order. Use these endpoints to apply partial or full refunds.

Issue Refund for Arbitrary Amount

Issues a refund for the amount specified against any captured transactions on the order. Notifies the connected stock inventory service to restock the returned line items (if applicable).

This endpoint does not perform any currency conversions.

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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

Request Body schema: application/json
reason
string

The note attached to the refund.

email_notification
boolean

Whether or not Checkout will send an email notification. If true, an email will be sent.

refund_order_data
object

(optional) Additional refund transaction data for specific payment gateway integrations.

amount
integer

Total amount requested for refund, represented in base currency units, using ISO-4217 standards.

Responses

Request samples

Content type
application/json
{
  • "amount": 6055,
  • "reason": "Product arrived broken.",
  • "email_notification": true,
  • "refund_meta_data": {
    }
}

Response samples

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

Refund a Specific Payment for an Arbitrary Amount

Issues a refund for the amount specified against a specific transactions on the order, identified by payment_id. Notifies the connected stock inventory service to restock the returned line items (if applicable).

This endpoint does not perform any currency conversions.

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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

payment_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

The identifier assigned to each unique payment.

Request Body schema: application/json
reason
string

The note attached to the refund.

email_notification
boolean

Whether or not Checkout will send an email notification. If true, an email will be sent.

refund_order_data
object

(optional) Additional refund transaction data for specific payment gateway integrations.

amount
integer

Total amount requested for refund, represented in base currency units, using ISO-4217 standards.

Responses

Request samples

Content type
application/json
{
  • "amount": 6055,
  • "reason": "Product arrived broken.",
  • "email_notification": true,
  • "refund_meta_data": {
    }
}

Response samples

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

Issue Refund for Full Order Amount

Issues a refund for the entire order (including shipping, taxes, etc). Restocks line items (if applicable).

This endpoint does not perform any currency conversions.

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 Info endpoint.

public_order_id
required
string
Example: woiph4vhqss9jjr50lR5am7IWurQ8FdbmtdOj4aaFIOfFiFGcvhY6x1t6eT0GoB

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

Request Body schema: application/json
reason
string

The note attached to the refund.

email_notification
boolean

Whether or not Checkout will send an email notification. If true, an email will be sent.

refund_order_data
object

(optional) Additional refund transaction data for specific payment gateway integrations.

Responses

Request samples

Content type
application/json
{
  • "reason": "Product arrived broken.",
  • "email_notification": true,
  • "refund_meta_data": {
    }
}

Response samples

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