Skip to main content
Documentation Powered 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.

Authentication

OAuthToken

Authenticates an API request from a public integration. Generate this token in the Developer Dashboard. Refer to Build Public Integrations for more information.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://apps.boldapps.net/accounts/dashboard/authorize
Token URL: https://api.boldcommerce.com/auth/oauth2/token

APIAccessToken

Authenticates an API request from a private integration. Generate this token in the Bold Account Center. Refer to the Quick Start for more information.

Security Scheme Type API Key
Header parameter name: API Access Token

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:
OAuthToken
    APIAccessToken
      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:
      OAuthToken
        APIAccessToken
          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:
          OAuthToken
            APIAccessToken
              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:
              OAuthToken
                APIAccessToken
                  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[ items ]
                  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:
                  OAuthToken
                    APIAccessToken
                      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 Cart Item (object) or SKU Cart Item (object) or Variant ID Cart Item (object)[ items ]

                      Array of items to add to the cart. Note that the "Cart Item" type is only supported by 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

                      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:
                      OAuthToken
                        APIAccessToken
                          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:
                          OAuthToken
                            APIAccessToken
                              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 Cart Item (object) or SKU Cart Item (object) or Variant ID Cart Item (object)[ items ]

                              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 [ items ]

                              The order's discount information.

                              Array of objects[ items ]

                              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)[ items ]

                              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

                              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:
                              OAuthToken
                                APIAccessToken
                                  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:
                                  OAuthToken
                                    APIAccessToken
                                      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 Payment for Full Order Amount

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

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

                                          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:
                                          OAuthToken
                                            APIAccessToken
                                              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
                                              number

                                              Total amount requested for refund.

                                              Responses

                                              Request samples

                                              Content type
                                              application/json
                                              {
                                              • "amount": 60.55,
                                              • "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:
                                              OAuthToken
                                                APIAccessToken
                                                  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": {
                                                    }
                                                  }