Checkout Backend (2.0)

Download OpenAPI specification:Download

URL: https://developer.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

Clears the customer from the Order.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier required	string The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
public_order_id required	string The public order id generated when the order is initialized by making a request to the Initialize Order endpoint.

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Responses

Response samples

200
422

Content type

application/json

{"data": {"application_state": {"customer": {"platform_id": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@mydomain.com",
"saved_addresses": [{"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
},
"addresses": {"billing": {"id": "2947",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"shipping": {"id": "47294",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
},
"line_items": [{"product_data": {"id": "999",
"product_title": "Oak Cheese Grater",
"title": "Ultra Cool Variant",
"image": "http://www.example.com/oakcheesegrater",
"properties": [ ],
"description": "",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_1",
"barcode": "",
"compare_at_price": 4700,
"weight": 1000,
"weight_unit": "g",
"product_id": "123product",
"variant_id": "80",
"requires_shipping": true,
"sku": "OCG",
"taxable": true,
"tags": "",
"vendor": "",
"total_weight": 2000
},
"taxes": [{"value": 750,
"name": "GST",
"is_included": true
}
],
"fees": [{"value": 500,
"name": "Miscellaneous Fee"
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
}
]
}
],
"fees": [{"id": "3245",
"line_text": "Custom Fee - Added by Plugin",
"fee_type": "fixed",
"value": 10,
"source": "PLUGIN",
"plugin_uuid": "a52589f8-09df-11ed-b30e-f67072e164ee",
"taxable": true,
"show_description": true
}
],
"shipping": {"select _shipping_line": {"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
"available_shipping_lines": [{"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
{"id": "1",
"desciption": "Custom Price based rate - tier 1",
"amount": 600
}
],
"taxes": [{"value": 250,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
]
},
"taxes": [{"value": 1000,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
},
{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
],
"payments": [{"gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
"amount": 4700,
"currency": "CAD",
"type": "spreedly",
"display_string": "Credit Card Payment",
"id": "",
"token": "7uZAMRAf80KiEwibsrrM5IB41yU",
"retain": false
}
],
"order_meta_data": {"cart_parameters": {"cp-key1": "A cart param"
},
"note_attributes": {"na-key1": "A note attribute"
},
"notes": "A special delivery note.",
"tags": ["order-1"
]
},
"flow_id": "external-company-one-page-template"
}
}
}

Create Authenticated Customer

"Creates a new authenticated customer.

Cannot create a customer when a customer was already provided by the Initialize Order endpoint or the Create Authenticated Customer endpoint.

If you wish to add a new authenticated customer to an order or add a guest customer you must first delete the existing customer using the Delete Customer endpoint"

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier required	string The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
public_order_id required	string The public order id generated when the order is initialized by making a request to the Initialize Order endpoint.

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Request Body schema: application/json

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.
platform_id required	string The customer's platform identifier.
public_id	string The customer's public identifier.
accepts_marketing	boolean Default: false If the customer would like to receive any sort of marketing emails.
	Array of objects or null (Address) [ items ] The saved addresses of an authenticated customer stored from the platform.

Responses

Request samples

Payload

Content type

application/json

{"first_name": "John",
"last_name": "doe",
"email_address": "john.doe@mydomain.com",
"platform_id": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"accepts_marketing": true,
"saved_addresses": [{"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
}

Response samples

200
422

Content type

application/json

{"data": {"customer": {"platform_id": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@mydomain.com",
"saved_addresses": [{"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
},
"application_state": {"customer": {"platform_id": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@mydomain.com",
"saved_addresses": [{"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
},
"addresses": {"billing": {"id": "2947",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"shipping": {"id": "47294",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
},
"line_items": [{"product_data": {"id": "999",
"product_title": "Oak Cheese Grater",
"title": "Ultra Cool Variant",
"image": "http://www.example.com/oakcheesegrater",
"properties": [ ],
"description": "",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_1",
"barcode": "",
"compare_at_price": 4700,
"weight": 1000,
"weight_unit": "g",
"product_id": "123product",
"variant_id": "80",
"requires_shipping": true,
"sku": "OCG",
"taxable": true,
"tags": "",
"vendor": "",
"total_weight": 2000
},
"taxes": [{"value": 750,
"name": "GST",
"is_included": true
}
],
"fees": [{"value": 500,
"name": "Miscellaneous Fee"
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
}
]
}
],
"fees": [{"id": "3245",
"line_text": "Custom Fee - Added by Plugin",
"fee_type": "fixed",
"value": 10,
"source": "PLUGIN",
"plugin_uuid": "a52589f8-09df-11ed-b30e-f67072e164ee",
"taxable": true,
"show_description": true
}
],
"shipping": {"select _shipping_line": {"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
"available_shipping_lines": [{"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
{"id": "1",
"desciption": "Custom Price based rate - tier 1",
"amount": 600
}
],
"taxes": [{"value": 250,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
]
},
"taxes": [{"value": 1000,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
},
{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
],
"payments": [{"gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
"amount": 4700,
"currency": "CAD",
"type": "spreedly",
"display_string": "Credit Card Payment",
"id": "",
"token": "7uZAMRAf80KiEwibsrrM5IB41yU",
"retain": false
}
],
"order_meta_data": {"cart_parameters": {"cp-key1": "A cart param"
},
"note_attributes": {"na-key1": "A note attribute"
},
"notes": "A special delivery note.",
"tags": ["order-1"
]
},
"flow_id": "external-company-one-page-template"
}
}
}

Integrations

Contains a shared secret, which is used to configure the webhooks that your integration uses.

Configure Integration Settings

Used to configure the Shop integration.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier

required

string

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

Request Body schema: application/json

shared_secret

required

string

A string used to sign callback url requests for webhook subscriptions.

Responses

Request samples

Payload

Content type

application/json

{"shared_secret": "example_shared_secret"
}

Response samples

200
422
500

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 Items

Updates the fulfilled_quantity property of multiple line items. For more information, refer to the Fulfill an Order page.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier required	string The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
public_order_id required	string 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 user-defined unique identifier serving to refer to this line throughout Bold Checkout.
fulfilled_quantity	integer

Responses

Request samples

Payload

Content type

application/json

{"line_items": [{"fulfilled_quantity": 1,
"line_item_key": "abcdefg"
},
{"fulfilled_quantity": 3,
"line_item_key": "hijklmop"
}
]
}

Response samples

200
422

Content type

application/json

{"data": {"line_items": {"product_data": {"id": "999",
"product_title": "Oak Cheese Grater",
"title": "Ultra Cool Variant",
"image": "http://www.example.com/oakcheesegrater",
"properties": [ ],
"description": "",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_1",
"barcode": "",
"compare_at_price": 4700,
"weight": 1000,
"weight_unit": "g",
"product_id": "123product",
"variant_id": "80",
"requires_shipping": true,
"sku": "OCG",
"taxable": true,
"tags": "",
"vendor": "",
"total_weight": 2000
},
"taxes": [{"value": 750,
"name": "GST",
"is_included": true
}
],
"fees": [{"value": 500,
"name": "Miscellaneous Fee"
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
}
]
},
"application_state": {"customer": {"platform_id": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@mydomain.com",
"saved_addresses": [{"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
},
"addresses": {"billing": {"id": "2947",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"shipping": {"id": "47294",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
},
"line_items": [{"product_data": {"id": "999",
"product_title": "Oak Cheese Grater",
"title": "Ultra Cool Variant",
"image": "http://www.example.com/oakcheesegrater",
"properties": [ ],
"description": "",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_1",
"barcode": "",
"compare_at_price": 4700,
"weight": 1000,
"weight_unit": "g",
"product_id": "123product",
"variant_id": "80",
"requires_shipping": true,
"sku": "OCG",
"taxable": true,
"tags": "",
"vendor": "",
"total_weight": 2000
},
"taxes": [{"value": 750,
"name": "GST",
"is_included": true
}
],
"fees": [{"value": 500,
"name": "Miscellaneous Fee"
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
}
]
}
],
"fees": [{"id": "3245",
"line_text": "Custom Fee - Added by Plugin",
"fee_type": "fixed",
"value": 10,
"source": "PLUGIN",
"plugin_uuid": "a52589f8-09df-11ed-b30e-f67072e164ee",
"taxable": true,
"show_description": true
}
],
"shipping": {"select _shipping_line": {"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
"available_shipping_lines": [{"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
{"id": "1",
"desciption": "Custom Price based rate - tier 1",
"amount": 600
}
],
"taxes": [{"value": 250,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
]
},
"taxes": [{"value": 1000,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
},
{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
],
"payments": [{"gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
"amount": 4700,
"currency": "CAD",
"type": "spreedly",
"display_string": "Credit Card Payment",
"id": "",
"token": "7uZAMRAf80KiEwibsrrM5IB41yU",
"retain": false
}
],
"order_meta_data": {"cart_parameters": {"cp-key1": "A cart param"
},
"note_attributes": {"na-key1": "A note attribute"
},
"notes": "A special delivery note.",
"tags": ["order-1"
]
},
"flow_id": "external-company-one-page-template"
}
}
}

Update Line Item

Updates the fulfilled_quantity property of a single line item. For more information, refer to the Fulfill an Order page.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier required	string The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
public_order_id required	string 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) A user-defined unique identifier serving to refer to this line throughout Bold Checkout.

Request Body schema: application/json

fulfilled_quantity

integer

Responses

Request samples

Payload

Content type

application/json

{"fulfilled_quantity": 2
}

Response samples

200
422

Content type

application/json

{"data": {"line_item": {"product_data": {"id": "999",
"product_title": "Oak Cheese Grater",
"title": "Ultra Cool Variant",
"image": "http://www.example.com/oakcheesegrater",
"properties": [ ],
"description": "",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_1",
"barcode": "",
"compare_at_price": 4700,
"weight": 1000,
"weight_unit": "g",
"product_id": "123product",
"variant_id": "80",
"requires_shipping": true,
"sku": "OCG",
"taxable": true,
"tags": "",
"vendor": "",
"total_weight": 2000
},
"taxes": [{"value": 750,
"name": "GST",
"is_included": true
}
],
"fees": [{"value": 500,
"name": "Miscellaneous Fee"
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
}
]
},
"application_state": {"customer": {"platform_id": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@mydomain.com",
"saved_addresses": [{"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
},
"addresses": {"billing": {"id": "2947",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"shipping": {"id": "47294",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
},
"line_items": [{"product_data": {"id": "999",
"product_title": "Oak Cheese Grater",
"title": "Ultra Cool Variant",
"image": "http://www.example.com/oakcheesegrater",
"properties": [ ],
"description": "",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_1",
"barcode": "",
"compare_at_price": 4700,
"weight": 1000,
"weight_unit": "g",
"product_id": "123product",
"variant_id": "80",
"requires_shipping": true,
"sku": "OCG",
"taxable": true,
"tags": "",
"vendor": "",
"total_weight": 2000
},
"taxes": [{"value": 750,
"name": "GST",
"is_included": true
}
],
"fees": [{"value": 500,
"name": "Miscellaneous Fee"
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
}
]
}
],
"fees": [{"id": "3245",
"line_text": "Custom Fee - Added by Plugin",
"fee_type": "fixed",
"value": 10,
"source": "PLUGIN",
"plugin_uuid": "a52589f8-09df-11ed-b30e-f67072e164ee",
"taxable": true,
"show_description": true
}
],
"shipping": {"select _shipping_line": {"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
"available_shipping_lines": [{"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
{"id": "1",
"desciption": "Custom Price based rate - tier 1",
"amount": 600
}
],
"taxes": [{"value": 250,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
]
},
"taxes": [{"value": 1000,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
},
{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
],
"payments": [{"gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
"amount": 4700,
"currency": "CAD",
"type": "spreedly",
"display_string": "Credit Card Payment",
"id": "",
"token": "7uZAMRAf80KiEwibsrrM5IB41yU",
"retain": false
}
],
"order_meta_data": {"cart_parameters": {"cp-key1": "A cart param"
},
"note_attributes": {"na-key1": "A note attribute"
},
"notes": "A special delivery note.",
"tags": ["order-1"
]
},
"flow_id": "external-company-one-page-template"
}
}
}

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

Used to initialize an order and retrieve a JWT. The JWT will be used to authorize all the storefront requests.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier

required

string

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

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Request Body schema: application/json

cart_id	string Identifier of an existing cart to load from the platform. This field is unsupported when using a custom platform.
access_token	string 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 (WooCommerce & 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)
	object Additional information about an order. This information is for the use of the store or integration, so Bold Checkout does not do anything with this metadata. It can also be used to include extra information about an order and included when pushed to the platform.
resumable_link	string 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 An identifier for the origin checkout flow that created the order. Bold-hosted templates provide this field and are identified by the first 4 letters `"bold"`, which are reserved. The field is optional for custom checkout flows and other clients, but provides a convenience for determining the order's origin. For more information, refer to Checkout Flows

Responses

Request samples

Payload

Content type

application/json

Example

Cart Token

{"cart_id": "1snVSJAWYWWYhfLWq9ABcXMwx8mcvh2U",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Response samples

200

Content type

application/json

{"data": {"jwt_token": "example_jwt",
"initial_data": {"shop_name": "mytestshop.com",
"country_info": [{"iso_code": "CA",
"name": "Canada",
"show_province": true,
"province_label": "province",
"show_postal_code": true,
"provinces": [{"iso_code": "MB",
"name": "Manitoba",
"valid_for_shipping": true,
"valid_for_billing": true
}
],
"valid_for_shipping": true,
"valid_for_billing": true
}
],
"supported_languages": [{"id": 123,
"shop_id": 100,
"iso_language": "en",
"language_name": "English",
"language_blob": "{\"language_name\":\"English\",\"terms\":{\"customer_information\":{\"already_have_an_account\":\"Already have an account with us?\",\"customer_info\":\"Customer information\",\"email\":\"Email\"}}}",
"is_default": true,
"out_of_date": 1,
"enabled": 1,
"source": "yappn",
"created_at": "2019-05-13T21:00:01.000000Z",
"updated_at": "2022-05-13T21:00:01.000000Z",
"deleted_at": null,
"name": "English",
"shop_language_id": 123
}
],
"general_settings": {"checkout_process": {"company_name_option": "optional",
"phone_number_required": false,
"accepts_marketing_checkbox_option": "unchecked"
},
"address_autocomplete": {"provider": "google",
"api_key": "testapikey"
}
}
},
"application_state": {"customer": {"platform_id": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@mydomain.com",
"saved_addresses": [{"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
},
"addresses": {"billing": {"id": "2947",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"shipping": {"id": "47294",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
},
"line_items": [{"product_data": {"id": "999",
"product_title": "Oak Cheese Grater",
"title": "Ultra Cool Variant",
"image": "http://www.example.com/oakcheesegrater",
"properties": [ ],
"description": "",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_1",
"barcode": "",
"compare_at_price": 4700,
"weight": 1000,
"weight_unit": "g",
"product_id": "123product",
"variant_id": "80",
"requires_shipping": true,
"sku": "OCG",
"taxable": true,
"tags": "",
"vendor": "",
"total_weight": 2000
},
"taxes": [{"value": 750,
"name": "GST",
"is_included": true
}
],
"fees": [{"value": 500,
"name": "Miscellaneous Fee"
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
}
]
}
],
"fees": [{"id": "3245",
"line_text": "Custom Fee - Added by Plugin",
"fee_type": "fixed",
"value": 10,
"source": "PLUGIN",
"plugin_uuid": "a52589f8-09df-11ed-b30e-f67072e164ee",
"taxable": true,
"show_description": true
}
],
"shipping": {"select _shipping_line": {"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
"available_shipping_lines": [{"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
{"id": "1",
"desciption": "Custom Price based rate - tier 1",
"amount": 600
}
],
"taxes": [{"value": 250,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
]
},
"taxes": [{"value": 1000,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
},
{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
],
"payments": [{"gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
"amount": 4700,
"currency": "CAD",
"type": "spreedly",
"display_string": "Credit Card Payment",
"id": "",
"token": "7uZAMRAf80KiEwibsrrM5IB41yU",
"retain": false
}
],
"order_meta_data": {"cart_parameters": {"cp-key1": "A cart param"
},
"note_attributes": {"na-key1": "A note attribute"
},
"notes": "A special delivery note.",
"tags": ["order-1"
]
},
"flow_id": "external-company-one-page-template"
},
"public_order_id": "AbC123",
"cart_customer_id": "100000009"
}
}

Refresh JWT

This endpoint can be used to generate a new JWT for the order. The initial JWT expires after 60 minutes.

This endpoint can also be use to resume an existing order (ie. Abandoned orders).

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier

required

string

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

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Request Body schema: application/json

public_order_id

string (Public Order ID)

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

Responses

Request samples

Payload

Content type

application/json

{"public_order_id": "AbC123"
}

Response samples

200
422

Content type

application/json

{"data": {"jwt_token": "example_jwt",
"initial_data": {"shop_name": "mytestshop.com",
"country_info": [{"iso_code": "CA",
"name": "Canada",
"show_province": true,
"province_label": "province",
"show_postal_code": true,
"provinces": [{"iso_code": "MB",
"name": "Manitoba",
"valid_for_shipping": true,
"valid_for_billing": true
}
],
"valid_for_shipping": true,
"valid_for_billing": true
}
],
"supported_languages": [{"id": 123,
"shop_id": 100,
"iso_language": "en",
"language_name": "English",
"language_blob": "{\"language_name\":\"English\",\"terms\":{\"customer_information\":{\"already_have_an_account\":\"Already have an account with us?\",\"customer_info\":\"Customer information\",\"email\":\"Email\"}}}",
"is_default": true,
"out_of_date": 1,
"enabled": 1,
"source": "yappn",
"created_at": "2019-05-13T21:00:01.000000Z",
"updated_at": "2022-05-13T21:00:01.000000Z",
"deleted_at": null,
"name": "English",
"shop_language_id": 123
}
],
"general_settings": {"checkout_process": {"company_name_option": "optional",
"phone_number_required": false,
"accepts_marketing_checkbox_option": "unchecked"
},
"address_autocomplete": {"provider": "google",
"api_key": "testapikey"
}
}
},
"application_state": {"customer": {"platform_id": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@mydomain.com",
"saved_addresses": [{"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
},
"addresses": {"billing": {"id": "2947",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"shipping": {"id": "47294",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
},
"line_items": [{"product_data": {"id": "999",
"product_title": "Oak Cheese Grater",
"title": "Ultra Cool Variant",
"image": "http://www.example.com/oakcheesegrater",
"properties": [ ],
"description": "",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_1",
"barcode": "",
"compare_at_price": 4700,
"weight": 1000,
"weight_unit": "g",
"product_id": "123product",
"variant_id": "80",
"requires_shipping": true,
"sku": "OCG",
"taxable": true,
"tags": "",
"vendor": "",
"total_weight": 2000
},
"taxes": [{"value": 750,
"name": "GST",
"is_included": true
}
],
"fees": [{"value": 500,
"name": "Miscellaneous Fee"
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
}
]
}
],
"fees": [{"id": "3245",
"line_text": "Custom Fee - Added by Plugin",
"fee_type": "fixed",
"value": 10,
"source": "PLUGIN",
"plugin_uuid": "a52589f8-09df-11ed-b30e-f67072e164ee",
"taxable": true,
"show_description": true
}
],
"shipping": {"select _shipping_line": {"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
"available_shipping_lines": [{"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
{"id": "1",
"desciption": "Custom Price based rate - tier 1",
"amount": 600
}
],
"taxes": [{"value": 250,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
]
},
"taxes": [{"value": 1000,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
},
{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
],
"payments": [{"gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
"amount": 4700,
"currency": "CAD",
"type": "spreedly",
"display_string": "Credit Card Payment",
"id": "",
"token": "7uZAMRAf80KiEwibsrrM5IB41yU",
"retain": false
}
],
"order_meta_data": {"cart_parameters": {"cp-key1": "A cart param"
},
"note_attributes": {"na-key1": "A note attribute"
},
"notes": "A special delivery note.",
"tags": ["order-1"
]
},
"flow_id": "external-company-one-page-template"
},
"public_order_id": "AbC123"
}
}

Cancel Order

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

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier required	string The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
public_order_id required	string The public order id generated when the order is initialized by making a request to the Initialize Order endpoint.

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Request Body schema: application/json

reason

string

Optional order cancellation reason.

Responses

Request samples

Payload

Content type

application/json

{"reason": "Duplicate order"
}

Response samples

200
422

Content type

application/json

{"data": {"application_state": {"customer": {"platform_id": "50942578465125",
"public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@mydomain.com",
"saved_addresses": [{"id": "123",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
]
},
"addresses": {"billing": {"id": "2947",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
},
"shipping": {"id": "47294",
"first_name": "John",
"last_name": "Doe",
"address_line_1": "50 Fultz Blvd",
"address_line_2": "",
"country": "Canada",
"city": "Winnipeg",
"province": "Manitoba",
"country_code": "CA",
"province_code": "MB",
"postal_code": "R3Y0L6",
"business_name": "Acme Inc.",
"phone_number": "8005550101"
}
},
"line_items": [{"product_data": {"id": "999",
"product_title": "Oak Cheese Grater",
"title": "Ultra Cool Variant",
"image": "http://www.example.com/oakcheesegrater",
"properties": [ ],
"description": "",
"quantity": 2,
"price": 2350,
"total_price": 4700,
"visible": 1,
"line_item_key": "oak_cheese_grater_1",
"barcode": "",
"compare_at_price": 4700,
"weight": 1000,
"weight_unit": "g",
"product_id": "123product",
"variant_id": "80",
"requires_shipping": true,
"sku": "OCG",
"taxable": true,
"tags": "",
"vendor": "",
"total_weight": 2000
},
"taxes": [{"value": 750,
"name": "GST",
"is_included": true
}
],
"fees": [{"value": 500,
"name": "Miscellaneous Fee"
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
}
]
}
],
"fees": [{"id": "3245",
"line_text": "Custom Fee - Added by Plugin",
"fee_type": "fixed",
"value": 10,
"source": "PLUGIN",
"plugin_uuid": "a52589f8-09df-11ed-b30e-f67072e164ee",
"taxable": true,
"show_description": true
}
],
"shipping": {"select _shipping_line": {"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
"available_shipping_lines": [{"id": "0",
"desciption": "Custom Weight based rate - tier 2",
"amount": 450
},
{"id": "1",
"desciption": "Custom Price based rate - tier 1",
"amount": 600
}
],
"taxes": [{"value": 250,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
]
},
"taxes": [{"value": 1000,
"name": "GST",
"is_included": true
}
],
"discounts": [{"code": "DC43KJ81",
"text": "Miscellaneous Discount",
"value": 500,
"valid": true
},
{"code": "SH12345",
"text": "Tax Free Shipping Discount",
"value": 250,
"valid": true
}
],
"payments": [{"gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
"amount": 4700,
"currency": "CAD",
"type": "spreedly",
"display_string": "Credit Card Payment",
"id": "",
"token": "7uZAMRAf80KiEwibsrrM5IB41yU",
"retain": false
}
],
"order_meta_data": {"cart_parameters": {"cp-key1": "A cart param"
},
"note_attributes": {"na-key1": "A note attribute"
},
"notes": "A special delivery note.",
"tags": ["order-1"
]
},
"flow_id": "external-company-one-page-template"
}
}
}

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 The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
public_order_id required	string The public order id generated when the order is initialized by making a request to the Initialize Order endpoint.

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Request Body schema: application/json

amount required	number Amount to capture, represented in base currency units, using ISO-4217 standards.
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

Responses

Request samples

Payload

Content type

application/json

Example

Amount provided

{"amount": 120,
"reauth": true,
"idempotent_key": "your_idempotent_key_here",
"capture_data": {"data": "Some kind of payment gateway data"
}
}

Response samples

200
202
422

Content type

application/json

{"data": {"order_total": 120,
"amount_remaining": 60,
"paid_total": 60,
"captured_held_total": 0,
"transactions": [{"gateway": "Stripe Default Name",
"gateway_id": "bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi",
"amount": 60,
"transaction_id": "ch_1GvDW4JhIKSKpq8w9SoshRef",
"reference_transaction_id": null,
"response_code": "",
"status": "success"
}
]
}
}

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 The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
public_order_id required	string The public order id generated when the order is initialized by making a request to the Initialize Order endpoint.

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

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

Responses

Request samples

Payload

Content type

application/json

{"reauth": true,
"idempotent_key": "your_idempotent_key_here",
"capture_data": {"data": "Some kind of payment gateway data"
}
}

Response samples

200
202
422

Content type

application/json

{"data": {"order_total": 120,
"amount_remaining": 0,
"paid_total": 120,
"captured_held_total": 0,
"transactions": [{"gateway": "Stripe Default Name",
"gateway_id": "bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi",
"amount": 120,
"transaction_id": "ch_1GvDW4JhIKSKpq8w9SoshRef",
"reference_transaction_id": null,
"response_code": "",
"status": "success"
}
]
}
}

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. Restocks line items (if applicable). This endpoint does not perform any currency conversions.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier required	string The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
public_order_id required	string The public order id generated when the order is initialized by making a request to the Initialize Order endpoint.

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Request Body schema: application/json

amount	number Amount to refund, represented in base currency units, using ISO-4217 standards.
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_meta_data	object (optional) Additional refund transaction data for specific payment gateway integrations.

Responses

Request samples

Payload

Content type

application/json

{"amount": 60.55,
"reason": "Product arrived broken.",
"email_notification": true,
"refund_meta_data": {"data": "Some kind of payment gateway data"
}
}

Response samples

200
422

Content type

application/json

{"data": {"amount_refunded": 60.55,
"transaction_details": [{"success": true,
"amount": 60.55,
"transaction_number": "ch_1GvDW4JhIKSKpq8w9SoshRef",
"created_at": "2021-01-15 01:01:01"
}
]
}
}

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 The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
public_order_id required	string The public order id generated when the order is initialized by making a request to the Initialize Order endpoint.

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

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

Payload

Content type

application/json

{"reason": "Product arrived broken.",
"email_notification": true,
"refund_meta_data": {"data": "Some kind of payment gateway data"
}
}

Response samples

200
422

Content type

application/json

{"data": {"amount_refunded": 120.99,
"transaction_details": [{"success": true,
"amount": 60.55,
"transaction_number": "ch_1GvDW4JhIKSKpq8w9SoshRef",
"created_at": "2021-01-15 01:01:01"
}
]
}
}

Webhooks

Contains information about the webhooks that are registered on a given store. Use these endpoints to manipulate the webhooks registered on your store.

List Webhooks

Retrieves a list of registered webhooks.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier

required

string

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

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Responses

Response samples

200

Content type

application/json

{"data": [{"webhook_topic_id": 1,
"webhook_topic_name": "order/created",
"callback_url": "https://my-app.com/webhooks/order/created",
"created_at": "2022-11-23 17:11:06",
"updated_at": "2022-11-23 17:11:06"
},
{"webhook_topic_id": 4,
"webhook_topic_name": "order/failed",
"callback_url": "https://my-app.com/webhooks/order/failed",
"created_at": "2022-11-23 17:11:06",
"updated_at": "2022-11-23 17:11:06"
}
]
}

Create Webhook

Register for a webhook by specifying the destination URL and topic.

For more information on Checkout webhooks, refer to Register for Webhooks.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier

required

string

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

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Request Body schema: application/json

webhook_topic_id required	integer The webhook topic id.
callback_url required	string The URL that the webhook payload will be sent to.

Responses

Callbacks

Request samples

Payload

Content type

application/json

{"webhook_topic_id": 1,
"callback_url": "https://my-app.com/webhooks/order/created"
}

Response samples

200
422

Content type

application/json

{"data": {"webhook_topic_id": 1,
"webhook_topic_name": "order/created",
"callback_url": "https://my-app.com/webhooks/order/created",
"created_at": "2022-11-23 17:11:06",
"updated_at": "2022-11-23 17:11:06"
}
}

Callback payload samples

Callback

POST: {$request.body#/callback_url}

Content type

application/json

{"customer": {"accepts_marketing": true,
"email_address": "johnny.bananas@boldapps.net",
"first_name": "Johnny",
"last_name": "Bananas",
"platform_id": null,
"public_id": "sTaGXlJuMIz1fzdnE8HSXkK1m2ym9FRbrwxqiS2t7XylVEMBT7YX1Xeep6V7cT53",
"saved_addresses": [ ]
},
"line_items": [{"discounts": [ ],
"fees": [ ],
"product_data": {"barcode": "",
"compare_at_price": 20000,
"description": "",
"id": "141368",
"image_url": "https://cdn11.bigcommerce.com/s-ivlj0jltli/products/103/images/334/naturalcanvascart2.1543864024.386.513.jpg?c=2",
"line_item_key": "key1",
"price": 20000,
"product_id": "103",
"properties": { },
"quantity": 1,
"requires_shipping": true,
"sku": "CLC",
"tags": "",
"taxable": true,
"title": "Default Title",
"total_price": 20000,
"variant_id": "71",
"vendor": "",
"visible": true,
"weight": 1,
"weight_unit": "kg"
},
"taxes": [ ]
}
],
"order_meta_data": {"cart_parameters": {"ca-key1": "Some kind of cart parameter."
},
"note_attributes": {"na-key1": "Some kind of note attributes."
},
"notes": "Some kind of special delivery note.",
"tags": ["tag-1"
]
},
"public_order_id": "nPTPIlIahDoEgZFabZNNvg7uxahLkGb1x4UINz3eqYV3eHewsjq7kubZc5BLAUqC",
"resumable_link": "https://mycheckout.com/resume"
}

Update Webhook

Update the destination URL for a specific webhook.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier required	string The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
webhook_topic_id required	string The webhook topic id.

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Request Body schema: application/json

The only property that can be changed for a webhook configuration is the callback url. Webhook topics cannot be updated, if any existing webhook is no longer required it must be deleted using the Delete Webhook endpoint. Or if registering for a new webhook, use the Create Webhook endpoint.

callback_url

required

string

Responses

Request samples

Payload

Content type

application/json

{"callback_url": "https://my-app.com/webhooks/different_callback_url"
}

Response samples

200
422

Content type

application/json

{"data": {"webhook_topic_id": 1,
"webhook_topic_name": "order/created",
"callback_url": "https://my-app.com/webhooks/different_callback_url",
"created_at": "2022-11-23 17:11:06",
"updated_at": "2022-11-23 17:11:06"
}
}

Delete Webhook

Unregister a webhook.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier required	string The identifier of the shop, which can be retrieved by making a request to the Get Info endpoint.
webhook_topic_id required	string The webhook topic id.

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Responses

Response samples

200
422

Content type

application/json

[ ]

List Webhook Topics

Gets the list of available webhook topics.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier

required

string

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

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Responses

Response samples

200

Content type

application/json

{"data": [{"webhook_topic_id": 1,
"webhook_topic_name": "order/created"
},
{"webhook_topic_id": 2,
"webhook_topic_name": "order/processed"
},
{"webhook_topic_id": 3,
"webhook_topic_name": "order/fulfilled"
}
]
}

Shops

Contains information about the store's checkout configuration, which is set in the Bold Checkout admin.

Get Shop General Settings

Retrieves basic settings from the shop's General Settings section in Checkout Admin.

Authorizations:

OAuthToken

APIAccessToken

path Parameters

shop_identifier

required

string

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

header Parameters

Authorization

required

string <Bearer-Token>

Example: Bearer yroF643MyJSeVQQJDKdvsd1awWcpiEQInHNi2dZXfYoOuR4vaFUHi4pODoiEai9T

Authenticates the API request. The expected token can either be generated from the "Developer Settings" page in the Account Center admin or through the Oauth installation. For more information about generating an API access token, refer to the Quick Start.

Responses

Response samples

200

Content type

application/json

{"data": {"checkout_process": {"company_name_option": "optional",
"phone_number_required": false,
"accepts_marketing_checkbox_option": "unchecked"
},
"address_autocomplete": {"provider": "google",
"api_key": "testapikey"
}
}
}