Skip to main content
API docs by Redocly

Checkout Remote State Authority (1.0.0)

Download OpenAPI specification:Download

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

The Checkout Remote State Authority API enables Bold to interact with a remote system that owns and has complete control over the state of an order during checkout. When a Remote State Authority (RSA) is configured, Bold Checkout calls the Remote Authority with order information, which manipulates the order and sends an updated order back to Bold Checkout.

This specification file defines the expected server behavior of the Remote State Authority server. Bold applications require the endpoints listed here to be implemented in order to function properly.

For more information about the Checkout RSA, including how to implement it, refer to the guides.

Events

Contains information about checkout events that manipulate the order state.

Process Order Events

Applies various state changes to the order. Events on any given request will only ever correspond to a single order, identified by the public_order_id.

Authorizations:
HMAC
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: SpMIhOL7Q36EDZUagB5GnnPh4TUb9zW9t0DGrWd8PvrwdV1S1PhGpf9wFIJRyZEi

The public order identifier generated when the order is initialized within Bold Checkout.

Request Body schema: application/json
required
cart_id
required
string

The platform-defined identifier of the cart associated with the order.

public_order_id
required
string

The public order identifier generated when the order is initialized within Bold Checkout.

required
object (Incoming Order State)

Represents the current state of the order, as calculated by Bold Checkout.

required
Array of SetShippingAddress (object) or RemoveShippingAddress (object) or SetBillingAddress (object) or RemoveBillingAddress (object) or SetCustomer (object) or RemoveCustomer (object) or SetShippingLine (object) or GetShippingLines (object) or ApplyTaxes (object) or AddDiscountCode (object) or RemoveDiscountCode (object) or AddLineItem (object) or UpdateLineItem (object) or RemoveLineItem (object) or EstimateTax (object) or EstimateShipping (object) non-empty

An array of one or more changes to make to the order state. The RSA must process these events in the order they are received.

Responses

Request samples

Content type
application/json
Example
{
  • "cart_id": "R1F6BiWNxI0Gg9WMfSZtMkTiUoFSlBD6",
  • "public_order_id": "SpMIhOL7Q36EDZUagB5GnnPh4TUb9zW9t0DGrWd8PvrwdV1S1PhGpf9wFIJRyZEi",
  • "order_state": {
    },
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "cart_id": "R1F6BiWNxI0Gg9WMfSZtMkTiUoFSlBD6",
  • "line_items": [
    ],
  • "customer": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "shipping_options": [
    ],
  • "selected_shipping": {
    },
  • "tags": [
    ],
  • "fees": [
    ],
  • "notes": [
    ],
  • "cart_params": {
    }
}

Validate

Contains information about one-off validation for checkout data.

Validate Address

Validates the given address. This will not apply the address, but can allow for ahead-of-time validation of particular fields.

Authorizations:
HMAC
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: SpMIhOL7Q36EDZUagB5GnnPh4TUb9zW9t0DGrWd8PvrwdV1S1PhGpf9wFIJRyZEi

The public order identifier generated when the order is initialized within Bold Checkout.

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

First name.

last_name
string or null

Last name.

address_line_1
string or null

Line 1 of the address.

address_line_2
string or null

Line 2 of the address.

city
string or null

City name.

province
string or null

Province or state name.

province_code
string or null

Province or state code, using ISO-3166 standards.

country
required
string

Country name.

country_code
required
string

Country code, using ISO-3166 standards.

postal_code
string or null

Postal/zip code.

business_name
string or null

The name of the company associated with this address.

phone_number
string or null

Phone number.

Responses

Request samples

Content type
application/json
{
  • "first_name": "Carl",
  • "last_name": "Smith",
  • "address_line_1": "50 Fultz Boulevard",
  • "address_line_2": "Unit 2",
  • "city": "Winnipeg",
  • "province": "Manitoba",
  • "province_code": "MB",
  • "country": "Canada",
  • "country_code": "CA",
  • "postal_code": "R3Y 0L6",
  • "business_name": "Bold Commerce",
  • "phone_number": "204-808-8095"
}

Response samples

Content type
application/json
{ }

Validate Email Address

Validates the customer email address. This will not add the email address to the customer, but can allow for validation before being applied.

Authorizations:
HMAC
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: SpMIhOL7Q36EDZUagB5GnnPh4TUb9zW9t0DGrWd8PvrwdV1S1PhGpf9wFIJRyZEi

The public order identifier generated when the order is initialized within Bold Checkout.

Request Body schema: application/json
required
email_address
required
string

The email address of the customer.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{ }

Validate Discount Code

Validates the given discount code. This will not apply the discount, but can allow for validation before being applied.

Authorizations:
HMAC
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: SpMIhOL7Q36EDZUagB5GnnPh4TUb9zW9t0DGrWd8PvrwdV1S1PhGpf9wFIJRyZEi

The public order identifier generated when the order is initialized within Bold Checkout.

Request Body schema: application/json
required
discount_code
required
string

The discount code that may be applied to the order.

cart_id
required
string

The platform-defined identifier of the cart associated with the order.

Responses

Request samples

Content type
application/json
{
  • "discount_code": "SPRINGSALE2022_Q8RT4"
}

Response samples

Content type
application/json
{ }

Validate Inventory

Validates that there is sufficient inventory to fulfill the order. Bold Checkout can request an inventory check during two different order stages:

  • initial: A preliminary inventory check, typically at (but not restricted to) the beginning of the Checkout flow.
  • final: A final inventory check, which indicates that the order is being finalized and that the customer intends to complete the transaction.
Authorizations:
HMAC
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: SpMIhOL7Q36EDZUagB5GnnPh4TUb9zW9t0DGrWd8PvrwdV1S1PhGpf9wFIJRyZEi

The public order identifier generated when the order is initialized within Bold Checkout.

Request Body schema: application/json
required
cart_id
required
string

The platform-defined identifier of the cart associated with the order.

public_order_id
required
string

The public order identifier generated when the order is initialized within Bold Checkout.

type
required
string
Enum: "initial" "final"

The type of inventory check being performed.

  • initial: A preliminary inventory check, typically at (but not restricted to) the beginning of the Checkout flow.
  • final: A final inventory check, which indicates that the order is being finalized and that the customer intends to complete the transaction.
required
Array of objects >= 0 items
required
object or null (Address)
tags
Array of strings[ items >= 0 items ]

Arbitrary labels to help sort and identify particular orders.

notes
Array of strings[ items >= 0 items ]

Free text fields attached to the order.

cart_params
object or null

Variable data to apply to the cart.

Responses

Request samples

Content type
application/json
{
  • "cart_id": "R1F6BiWNxI0Gg9WMfSZtMkTiUoFSlBD6",
  • "public_order_id": "SpMIhOL7Q36EDZUagB5GnnPh4TUb9zW9t0DGrWd8PvrwdV1S1PhGpf9wFIJRyZEi",
  • "type": "final",
  • "items": [
    ],
  • "shipping_address": {
    },
  • "tags": [
    ],
  • "notes": [
    ],
  • "cart_params": {
    }
}

Response samples

Content type
application/json
{ }