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 |
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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
{- "data": {
- "application_state": {
- "customer": [ ],
- "addresses": {
- "shipping": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}, - "billing": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
}, - "line_items": [
- {
- "product_data": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "colour": "red",
- "size": "small"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}
}, - {
- "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
]
}, - {
- "fees": [
- {
- "amount": 500,
- "name": "Miscellaneous fee."
}
]
}, - {
- "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - {
- "fulfilled_quantity": 2
}
], - "fees": [
- {
- "id": "123456789",
- "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
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "payments": [
- {
- "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
- "amount": 4700,
- "currency": "CAD",
- "type": "spreedly",
- "display_string": "Credit Card Payment",
- "id": "",
- "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
- "retain": false
}
], - "order_total": 4700,
- "order_meta_data": {
- "cart_parameters": {
- "key": "cp-key1,",
- "property1": "A cart param.",
- "property2": "A cart param."
}, - "note_attributes": {
- "key": "na-key1",
- "property1": "A note attribute.",
- "property2": "A note attribute."
}, - "notes": "A special delivery note.",
- "tags": [
- "order-1"
]
}, - "shipping": {
- "selected_shipping": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}, - "available_shipping_lines": [
- {
- "id": "string,",
- "line": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - "resumable_link": "string",
- "flow_id": "external-company-one-page-template",
- "currency": {
- "iso_code": "CAD",
- "iso_numeric_code": 124,
- "symbol": "$",
- "format": "${{amount}}",
- "has_decimal": true,
- "show_iso_code": true
}, - "created_via": "My_Order_Creating_Plugin",
- "is_processed": false,
- "order_id": 79047599,
- "platform_order_id": "1389wjfalsdf9y4r"
}
}
}
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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
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 |
Responses
Request samples
- Payload
{- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "first_name": "John",
- "last_name": "Doe",
- "accepts_marketing": false
}
Response samples
- 200
- 422
{- "data": {
- "customer": {
- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "first_name": "John",
- "last_name": "Doe",
- "accepts_marketing": true,
- "saved_addresses": [
- {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
]
}, - "application_state": {
- "customer": {
- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "first_name": "John",
- "last_name": "Doe",
- "accepts_marketing": true,
- "saved_addresses": [
- {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
]
}, - "addresses": {
- "shipping": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}, - "billing": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
}, - "line_items": [
- {
- "product_data": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}, - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "fees": [
- {
- "amount": 500,
- "name": "Miscellaneous fee."
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "fulfilled_quantity": 2
}
], - "fees": [
- {
- "id": "123456789",
- "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
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "payments": [
- {
- "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
- "amount": 4700,
- "currency": "CAD",
- "type": "spreedly",
- "display_string": "Credit Card Payment",
- "id": "",
- "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
- "retain": false
}
], - "order_total": 4700,
- "order_meta_data": {
- "cart_parameters": {
- "key": "cp-key1",
- "property1": "A cart param.",
- "property2": "A cart param."
}, - "note_attributes": {
- "key": "na-key1",
- "property1": "A note attribute.",
- "property2": "A note attribute."
}, - "notes": "A special delivery note.",
- "tags": [
- "order-1"
]
}, - "shipping": {
- "selected_shipping": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}, - "available_shipping_lines": [
- {
- "id": "string",
- "line": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - "flow_id": "external-company-one-page-template",
- "currency": {
- "iso_code": "CAD",
- "iso_numeric_code": 124,
- "symbol": "$",
- "format": "${{amount}}",
- "has_decimal": true,
- "show_iso_code": true
}, - "created_via": "My_Order_Creating_Plugin",
- "is_processed": false,
- "order_id": 79047599,
- "platform_order_id": "1389wjfalsdf9y4r"
}
}
}
Contains a shared secret, which is used to configure the webhooks that your integration uses.
Configure Integration Settings
Configures webhooks to integrate with your shop, using a given shared secret.
Read more about configuring webhook integration in the Register for Webhooks guide.
Authorizations:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
shared_secret required | string A string used to sign callback url requests for webhook subscriptions. |
Responses
Request samples
- Payload
{- "shared_secret": "96c6db504d593697229066dde7c88f2e"
}
Response samples
- 200
- 422
- 500
[ ]
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:
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
- Payload
{- "fulfilled_quantity": 2
}
Response samples
- 200
- 422
{- "data": {
- "line_item": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}, - "application_state": {
- "customer": {
- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "first_name": "John",
- "last_name": "Doe",
- "accepts_marketing": true,
- "saved_addresses": [
- {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
]
}, - "addresses": {
- "shipping": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}, - "billing": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
}, - "line_items": [
- {
- "product_data": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}, - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "fees": [
- {
- "amount": 500,
- "name": "Miscellaneous fee."
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "fulfilled_quantity": 2
}
], - "fees": [
- {
- "id": "123456789",
- "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
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "payments": [
- {
- "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
- "amount": 4700,
- "currency": "CAD",
- "type": "spreedly",
- "display_string": "Credit Card Payment",
- "id": "",
- "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
- "retain": false
}
], - "order_total": 4700,
- "order_meta_data": {
- "cart_parameters": {
- "key": "cp-key1",
- "property1": "A cart param.",
- "property2": "A cart param."
}, - "note_attributes": {
- "key": "na-key1",
- "property1": "A note attribute.",
- "property2": "A note attribute."
}, - "notes": "A special delivery note.",
- "tags": [
- "order-1"
]
}, - "shipping": {
- "selected_shipping": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}, - "available_shipping_lines": [
- {
- "id": "string",
- "line": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - "flow_id": "external-company-one-page-template",
- "currency": {
- "iso_code": "CAD",
- "iso_numeric_code": 124,
- "symbol": "$",
- "format": "${{amount}}",
- "has_decimal": true,
- "show_iso_code": true
}, - "created_via": "My_Order_Creating_Plugin",
- "is_processed": false,
- "order_id": 79047599,
- "platform_order_id": "1389wjfalsdf9y4r"
}
}
}
Update Line Items
Updates the fulfilled_quantity
property of multiple line items.
For more information, refer to the Fulfill an Order guide.
Authorizations:
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
|
Responses
Request samples
- Payload
{- "line_items": [
- {
- "fulfilled_quantity": 1,
- "line_item_key": "oak_cheese_grater_2643"
}, - {
- "fulfilled_quantity": 3,
- "line_item_key": "oak_cheese_grater_3000"
}
]
}
Response samples
- 200
- 422
{- "data": {
- "line_items": [
- {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}
], - "application_state": {
- "customer": {
- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "first_name": "John",
- "last_name": "Doe",
- "accepts_marketing": true,
- "saved_addresses": [
- {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
]
}, - "addresses": {
- "shipping": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}, - "billing": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
}, - "line_items": [
- {
- "product_data": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}, - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "fees": [
- {
- "amount": 500,
- "name": "Miscellaneous fee."
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "fulfilled_quantity": 2
}
], - "fees": [
- {
- "id": "123456789",
- "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
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "payments": [
- {
- "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
- "amount": 4700,
- "currency": "CAD",
- "type": "spreedly",
- "display_string": "Credit Card Payment",
- "id": "",
- "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
- "retain": false
}
], - "order_total": 4700,
- "order_meta_data": {
- "cart_parameters": {
- "key": "cp-key1",
- "property1": "A cart param.",
- "property2": "A cart param."
}, - "note_attributes": {
- "key": "na-key1",
- "property1": "A note attribute.",
- "property2": "A note attribute."
}, - "notes": "A special delivery note.",
- "tags": [
- "order-1"
]
}, - "shipping": {
- "selected_shipping": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}, - "available_shipping_lines": [
- {
- "id": "string",
- "line": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - "flow_id": "external-company-one-page-template",
- "currency": {
- "iso_code": "CAD",
- "iso_numeric_code": 124,
- "symbol": "$",
- "format": "${{amount}}",
- "has_decimal": true,
- "show_iso_code": true
}, - "created_via": "My_Order_Creating_Plugin",
- "is_processed": false,
- "order_id": 79047599,
- "platform_order_id": "1389wjfalsdf9y4r"
}
}
}
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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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 (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 For more information, refer to Checkout Flows |
Responses
Request samples
- Payload
{- "cart_id": "1snVSJAWYWWYhfLWq9ABcXMwx8mcvh2U",
- "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Response samples
- 200
{- "data": {
- "initial_data": {
- "shop_name": "examplestore.com",
- "country_information": [
- {
- "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": 32856,
- "shop_id": 1091521,
- "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\",\"email_address\":\"Email address\",\"email_address_placeholder\":\"Email address\",\"enter_new_address\":\"Enter a new address\",\"log_in\":\"Log in\",\"not_you\":\"Not you?\",\"return_to_cart\":\"Return to cart\",\"return_to_store\":\"Return to store\",\"accepts_marketing\":\"Subscribe to our newsletter\"},\"shipping_address\":{\"address2_field\":\"Apt, suite, etc.\",\"address2_field_optional\":\"Apt, suite, etc. (optional)\",\"address_field\":\"Address\",\"city_field\":\"City\",\"company_field\":\"Company\",\"company_field_optional\":\"Company (optional)\",\"cont_to_shipping\":\"Continue to shipping method\",\"country_field\":\"Country\",\"country_field_placeholder\":\"Choose a country\",\"first_name_field\":\"First name\",\"last_name_field\":\"Last name\",\"optional\":\" (optional)\",\"phone_field\":\"Phone\",\"phone_field_optional\":\"Phone (optional)\",\"postal_code_field\":\"Postal code\",\"province\":\"Province\",\"province_field\":\"Province\",\"province_field_placeholder\":\"Choose a province\",\"select_address\":\"Select an address\",\"select_exist_address\":\"Select an existing address\",\"shipping\":\"Shipping\",\"shipping_address\":\"Shipping address\",\"state\":\"State\"}}}",
- "is_default": true,
- "out_of_date": 0,
- "enabled": 1,
- "source": null,
- "created_at": "2021-08-12T14:30:54.000000Z",
- "updated_at": "2022-10-20T19:54:08.000000Z",
- "deleted_at": null,
- "name": "English",
- "shop_language_id": 32856
}
], - "general_settings": {
- "checkout_process": {
- "company_name_option": "hidden",
- "phone_number_required": false,
- "accepts_marketing_checkbox_option": "unchecked"
}, - "address_autocomplete": {
- "provider": "google",
- "api_key": "awefa9304q9wfqf43jfaw904kfwkaslserfa94"
}
}, - "alternative_payment_methods": [ ]
}, - "application_state": {
- "customer": {
- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "first_name": "John",
- "last_name": "Doe",
- "accepts_marketing": true,
- "saved_addresses": [
- {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
]
}, - "addresses": {
- "shipping": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}, - "billing": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
}, - "line_items": [
- {
- "product_data": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}, - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "fees": [
- {
- "amount": 500,
- "name": "Miscellaneous fee."
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "fulfilled_quantity": 2
}
], - "fees": [
- {
- "id": "123456789",
- "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
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "payments": [
- {
- "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
- "amount": 4700,
- "currency": "CAD",
- "type": "spreedly",
- "display_string": "Credit Card Payment",
- "id": "",
- "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
- "retain": false
}
], - "order_total": 4700,
- "order_meta_data": {
- "cart_parameters": {
- "key": "cp-key1",
- "property1": "A cart param.",
- "property2": "A cart param."
}, - "note_attributes": {
- "key": "na-key1",
- "property1": "A note attribute.",
- "property2": "A note attribute."
}, - "notes": "A special delivery note.",
- "tags": [
- "order-1"
]
}, - "shipping": {
- "selected_shipping": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}, - "available_shipping_lines": [
- {
- "id": "string",
- "line": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - "flow_id": "external-company-one-page-template",
- "currency": {
- "iso_code": "CAD",
- "iso_numeric_code": 124,
- "symbol": "$",
- "format": "${{amount}}",
- "has_decimal": true,
- "show_iso_code": true
}, - "created_via": "My_Order_Creating_Plugin",
- "is_processed": false,
- "order_id": 79047599,
- "platform_order_id": "1389wjfalsdf9y4r"
}, - "jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoX3R5cGUiOiJWMl9BUEkiLCJwYXlsb2FkIjp7InB1YmxpY19vcmRlcl9pZCI6Inlyb0Y2NDNNeUpTZVZRUUpES2R2c2QxYXdXY3BpRVFJbkhOaTJkWlhmWW9PdVI0dmFGVUhpNHBPRG9pRWFpOVQifSwiZXhwIjoxNjMyMzQxMjg3LCJuYmYiOm51bGwsImlhdCI6bnVsbH0.swmYcVBHyK2i86jN-bIOL3WOCzP5VQVLq9Ev-TfIC_c",
- "public_order_id": "nPTPIlIahDoEgZFabZNNvg7uxahLkGb1x4UINz3eqYV3eHewsjq7kubZc5BLAUqC",
- "cart_customer_id": "100000009"
}
}
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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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 identifier generated when the order is initialized by making a request to the Initialize Order endpoint. |
Responses
Request samples
- Payload
{- "public_order_id": "nPTPIlIahDoEgZFabZNNvg7uxahLkGb1x4UINz3eqYV3eHewsjq7kubZc5BLAUqC"
}
Response samples
- 200
- 422
{- "data": {
- "jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdXRoX3R5cGUiOiJWMl9BUEkiLCJwYXlsb2FkIjp7InB1YmxpY19vcmRlcl9pZCI6Inlyb0Y2NDNNeUpTZVZRUUpES2R2c2QxYXdXY3BpRVFJbkhOaTJkWlhmWW9PdVI0dmFGVUhpNHBPRG9pRWFpOVQifSwiZXhwIjoxNjMyMzQxMjg3LCJuYmYiOm51bGwsImlhdCI6bnVsbH0.swmYcVBHyK2i86jN-bIOL3WOCzP5VQVLq9Ev-TfIC_c",
- "initial_data": {
- "shop_name": "examplestore.com",
- "country_information": [
- {
- "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": 32856,
- "shop_id": 1091521,
- "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\",\"email_address\":\"Email address\",\"email_address_placeholder\":\"Email address\",\"enter_new_address\":\"Enter a new address\",\"log_in\":\"Log in\",\"not_you\":\"Not you?\",\"return_to_cart\":\"Return to cart\",\"return_to_store\":\"Return to store\",\"accepts_marketing\":\"Subscribe to our newsletter\"},\"shipping_address\":{\"address2_field\":\"Apt, suite, etc.\",\"address2_field_optional\":\"Apt, suite, etc. (optional)\",\"address_field\":\"Address\",\"city_field\":\"City\",\"company_field\":\"Company\",\"company_field_optional\":\"Company (optional)\",\"cont_to_shipping\":\"Continue to shipping method\",\"country_field\":\"Country\",\"country_field_placeholder\":\"Choose a country\",\"first_name_field\":\"First name\",\"last_name_field\":\"Last name\",\"optional\":\" (optional)\",\"phone_field\":\"Phone\",\"phone_field_optional\":\"Phone (optional)\",\"postal_code_field\":\"Postal code\",\"province\":\"Province\",\"province_field\":\"Province\",\"province_field_placeholder\":\"Choose a province\",\"select_address\":\"Select an address\",\"select_exist_address\":\"Select an existing address\",\"shipping\":\"Shipping\",\"shipping_address\":\"Shipping address\",\"state\":\"State\"}}}",
- "is_default": true,
- "out_of_date": 0,
- "enabled": 1,
- "source": null,
- "created_at": "2021-08-12T14:30:54.000000Z",
- "updated_at": "2022-10-20T19:54:08.000000Z",
- "deleted_at": null,
- "name": "English",
- "shop_language_id": 32856
}
], - "general_settings": {
- "checkout_process": {
- "company_name_option": "hidden",
- "phone_number_required": false,
- "accepts_marketing_checkbox_option": "unchecked"
}, - "address_autocomplete": {
- "provider": "google",
- "api_key": "awefa9304q9wfqf43jfaw904kfwkaslserfa94"
}
}, - "alternative_payment_methods": [ ]
}, - "application_state": {
- "customer": {
- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "first_name": "John",
- "last_name": "Doe",
- "accepts_marketing": true,
- "saved_addresses": [
- {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
]
}, - "addresses": {
- "shipping": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}, - "billing": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
}, - "line_items": [
- {
- "product_data": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}, - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "fees": [
- {
- "amount": 500,
- "name": "Miscellaneous fee."
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "fulfilled_quantity": 2
}
], - "fees": [
- {
- "id": "123456789",
- "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
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "payments": [
- {
- "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
- "amount": 4700,
- "currency": "CAD",
- "type": "spreedly",
- "display_string": "Credit Card Payment",
- "id": "",
- "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
- "retain": false
}
], - "order_total": 4700,
- "order_meta_data": {
- "cart_parameters": {
- "key": "cp-key1",
- "property1": "A cart param.",
- "property2": "A cart param."
}, - "note_attributes": {
- "key": "na-key1",
- "property1": "A note attribute.",
- "property2": "A note attribute."
}, - "notes": "A special delivery note.",
- "tags": [
- "order-1"
]
}, - "shipping": {
- "selected_shipping": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}, - "available_shipping_lines": [
- {
- "id": "string",
- "line": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - "flow_id": "external-company-one-page-template",
- "currency": {
- "iso_code": "CAD",
- "iso_numeric_code": 124,
- "symbol": "$",
- "format": "${{amount}}",
- "has_decimal": true,
- "show_iso_code": true
}, - "created_via": "My_Order_Creating_Plugin",
- "is_processed": false,
- "order_id": 79047599,
- "platform_order_id": "1389wjfalsdf9y4r"
}, - "public_order_id": "nPTPIlIahDoEgZFabZNNvg7uxahLkGb1x4UINz3eqYV3eHewsjq7kubZc5BLAUqC"
}
}
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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
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 | |
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 For more information, refer to Checkout Flows |
Responses
Request samples
- Payload
{- "cart_items": [
- {
- "sku": "KLS_472945",
- "quantity": 2,
- "line_item_key": "db3b1963-6ddd-4115-9f45-64c7edb3867d",
- "line_item_properties": {
- "colour": "red",
- "size": "small"
}
}
], - "customer": {
- "first_name": "Robert",
- "last_name": "Walsh",
- "accepts_marketing": false,
- "public_id": "6xID7o9hrxQ7bkVIKvCxXPD7Cf3P4BP141wplqPTa3CYYwEqM5X9w7JzKWulQe4p"
}, - "shipping_address": {
- "first_name": "Robert",
- "last_name": "Walsh",
- "address_line_1": "2652 John Daniel Drive",
- "city": "Dexter",
- "province": "Missouri",
- "province_code": "MO",
- "country": "United States of America",
- "country_code": "US",
- "postal_code": "63841"
}, - "billing_address": {
- "first_name": "Robert",
- "last_name": "Walsh",
- "address_line_1": "2652 John Daniel Drive",
- "city": "Dexter",
- "province": "Missouri",
- "province_code": "MO",
- "country": "United States of America",
- "country_code": "US",
- "postal_code": "63841"
}, - "discounts": [
- {
- "discount_code": "SPRINGSALE2022_Q8RT4"
}
], - "payments": [
- {
- "public_payment_method_id": "ftziZRlloXJhR8emShyZePgaZxFTp9TN6Ai0tVWOB223g9qCGQQFA27ccW2fx72U"
}
], - "currency": "USD",
- "idempotency_key": "2b268b6f-b3c0-4efb-9c43-1aa59d535182",
- "commands": {
- "0": "calculate_shipping",
- "1": "calculate_tax_rates",
- "2": "authorize_payments",
- "3": "process_order",
- "4": "send_to_platform",
- "5": "charge_payments"
}
}
Response samples
- 200
- 422
{- "data": {
- "application_state": {
- "customer": {
- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "first_name": "John",
- "last_name": "Doe",
- "accepts_marketing": true,
- "saved_addresses": [
- {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
]
}, - "addresses": {
- "shipping": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}, - "billing": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
}, - "line_items": [
- {
- "product_data": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}, - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "fees": [
- {
- "amount": 500,
- "name": "Miscellaneous fee."
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "fulfilled_quantity": 2
}
], - "fees": [
- {
- "id": "123456789",
- "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
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "payments": [
- {
- "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
- "amount": 4700,
- "currency": "CAD",
- "type": "spreedly",
- "display_string": "Credit Card Payment",
- "id": "",
- "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
- "retain": false
}
], - "order_total": 4700,
- "order_meta_data": {
- "cart_parameters": {
- "key": "cp-key1",
- "property1": "A cart param.",
- "property2": "A cart param."
}, - "note_attributes": {
- "key": "na-key1",
- "property1": "A note attribute.",
- "property2": "A note attribute."
}, - "notes": "A special delivery note.",
- "tags": [
- "order-1"
]
}, - "shipping": {
- "selected_shipping": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}, - "available_shipping_lines": [
- {
- "id": "string",
- "line": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - "flow_id": "external-company-one-page-template",
- "currency": {
- "iso_code": "CAD",
- "iso_numeric_code": 124,
- "symbol": "$",
- "format": "${{amount}}",
- "has_decimal": true,
- "show_iso_code": true
}, - "created_via": "My_Order_Creating_Plugin",
- "is_processed": false,
- "order_id": 79047599,
- "platform_order_id": "1389wjfalsdf9y4r"
}, - "public_order_id": "o10KL4Crlb8Lh4zg4t5kImS6CFvdFI1t5Aybxlor1B52GDGAZvn6X85wy6oDfWZP"
}
}
Cancel Order
Cancels an order, voiding any held authorizations. This endpoint fails if the order is already fulfilled or any payments were captured.
Authorizations:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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 An optional order cancellation reason. |
Responses
Request samples
- Payload
{- "reason": "Duplicate order."
}
Response samples
- 200
- 422
{- "data": {
- "application_state": {
- "customer": {
- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "first_name": "John",
- "last_name": "Doe",
- "accepts_marketing": true,
- "saved_addresses": [
- {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
]
}, - "addresses": {
- "shipping": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}, - "billing": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
}, - "line_items": [
- {
- "product_data": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}, - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "fees": [
- {
- "amount": 500,
- "name": "Miscellaneous fee."
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "fulfilled_quantity": 2
}
], - "fees": [
- {
- "id": "123456789",
- "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
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "payments": [
- {
- "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
- "amount": 4700,
- "currency": "CAD",
- "type": "spreedly",
- "display_string": "Credit Card Payment",
- "id": "",
- "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
- "retain": false
}
], - "order_total": 4700,
- "order_meta_data": {
- "cart_parameters": {
- "key": "cp-key1",
- "property1": "A cart param.",
- "property2": "A cart param."
}, - "note_attributes": {
- "key": "na-key1",
- "property1": "A note attribute.",
- "property2": "A note attribute."
}, - "notes": "A special delivery note.",
- "tags": [
- "order-1"
]
}, - "shipping": {
- "selected_shipping": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}, - "available_shipping_lines": [
- {
- "id": "string",
- "line": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - "flow_id": "external-company-one-page-template",
- "currency": {
- "iso_code": "CAD",
- "iso_numeric_code": 124,
- "symbol": "$",
- "format": "${{amount}}",
- "has_decimal": true,
- "show_iso_code": true
}, - "created_via": "My_Order_Creating_Plugin",
- "is_processed": false,
- "order_id": 79047599,
- "platform_order_id": "1389wjfalsdf9y4r"
}
}
}
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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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 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
- Payload
{- "amount": 1200,
- "reauth": true,
- "idempotent_key": "2b268b6f-b3c0-4efb-9c43-1aa59d535182",
- "capture_data": {
- "data": {
- "external_id": "legacy-id-135798642"
}
}
}
Response samples
- 200
- 202
- 422
{- "data": {
- "order_total": 1200,
- "amount_remaining": 600,
- "paid_total": 600,
- "captured_held_total": 0,
- "transactions": [
- {
- "gateway": "Stripe Default Name",
- "gateway_id": "bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi",
- "amount": 600,
- "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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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 Any data associated with the payment capture request. |
Responses
Request samples
- Payload
{- "reauth": true,
- "idempotent_key": "2b268b6f-b3c0-4efb-9c43-1aa59d535182",
- "capture_data": {
- "data": {
- "external_id": "legacy-id-135798642"
}
}
}
Response samples
- 200
- 202
- 422
{- "data": {
- "order_total": 1200,
- "amount_remaining": 600,
- "paid_total": 600,
- "captured_held_total": 0,
- "transactions": [
- {
- "gateway": "Stripe Default Name",
- "gateway_id": "bFH0RUdnWPFPRxmWfK6B1yXi61Hh0svIBTrk1vtGoI1zPYVXntIqMX82pqdrSYhi",
- "amount": 600,
- "transaction_id": "ch_1GvDW4JhIKSKpq8w9SoshRef",
- "reference_transaction_id": null,
- "response_code": "",
- "status": "success"
}
]
}
}
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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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. |
amount | number Total amount requested for refund. |
Responses
Request samples
- Payload
{- "amount": 60.55,
- "reason": "Product arrived broken.",
- "email_notification": true,
- "refund_meta_data": {
- "data": {
- "external_id": "legacy-id-135798642"
}
}
}
Response samples
- 200
- 422
{- "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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
{- "reason": "Product arrived broken.",
- "email_notification": true,
- "refund_meta_data": {
- "data": {
- "external_id": "legacy-id-135798642"
}
}
}
Response samples
- 200
- 422
{- "data": {
- "amount_refunded": 60.55,
- "transaction_details": [
- {
- "success": true,
- "amount": 60.55,
- "transaction_number": "ch_1GvDW4JhIKSKpq8w9SoshRef",
- "created_at": "2021-01-15 01:01:01"
}
]
}
}
Contains information about the webhooks that are registered on a given store. Use these endpoints to manipulate the webhooks registered on your store.
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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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 (WebhookTopicID) The webhook topic identifier. |
callback_url required | string (CallbackURL) The URL that the webhook payload will be sent to. |
Responses
Callbacks
Request samples
- Payload
{- "webhook_topic_id": 1,
}
Response samples
- 200
- 422
{- "data": {
- "webhook_topic_id": 1,
- "webhook_topic_name": "order/created",
- "created_at": "2021-11-17 21:03:36",
- "updated_at": "2021-11-17 21:03:36"
}
}
Callback payload samples
{- "value": {
- "domain": "store-vwd2342klmsdf.mybigcommerce.com",
- "platform_domain": "example.mybigcommerce.com",
- "application_state": {
- "customer": {
- "accepts_marketing": true,
- "first_name": "John",
- "last_name": "Doe",
- "platform_id": "50942578465125",
- "public_id": "pjpTyGh8KzNQ225wPqxgy7LwNuC887h6ecGyp3omwT4XW8SszjVSdHzWHN4NBwqhA",
- "saved_addresses": [ ]
}, - "addresses": {
- "shipping": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}, - "billing": {
- "id": "123",
- "first_name": "John",
- "last_name": "Doe",
- "address_line_1": "50 Fultz Blvd",
- "address_line_2": "Suite 200",
- "country": "Canada",
- "city": "Winnipeg",
- "province": "Manitoba",
- "country_code": "CA",
- "province_code": "MB",
- "postal_code": "R3Y0L6",
- "business_name": "Acme Inc.",
- "phone_number": "8005550101"
}
}, - "line_items": [
- {
- "product_data": {
- "id": "724bca",
- "product_title": "Oak Cheese Grater",
- "title": "Small",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "description": "A handmade oak cheese grater to elevate your cheese-eating experience.",
- "quantity": 2,
- "price": 2350,
- "total_price": 4700,
- "visible": 1,
- "line_item_key": "oak_cheese_grater_2643",
- "barcode": "1234ABC",
- "compare_at_price": 4000,
- "weight": 1000,
- "weight_unit": "g",
- "product_id": "oak-cheese-grater",
- "variant_id": "oak-cheese-grater-small",
- "requires_shipping": true,
- "sku": "OAK_GRATER_SM",
- "taxable": true,
- "tags": "Kitchen, Cheese Board, Oak",
- "vendor": "Cheese Boards Unlimited",
- "total_weight": 2000
}
}, - {
- "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
]
}, - {
- "fees": [
- {
- "amount": 500,
- "name": "Miscellaneous fee."
}
]
}, - {
- "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - {
- "fulfilled_quantity": 2
}
], - "fees": [
- {
- "id": "123456789",
- "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
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
], - "payments": [
- {
- "gateway_public_id": "i7z2xT0sKrDvhGWzex5SLjf5e6ndlQfrRL4AROkfhf3vNBkVT38JKBy5PSjB63qW",
- "amount": 4700,
- "currency": "CAD",
- "type": "spreedly",
- "display_string": "Credit Card Payment",
- "id": "",
- "token": "7uZAMRAf80KiEwibsrrM5IB41yU",
- "retain": false
}
], - "order_total": 4700,
- "order_meta_data": {
- "cart_parameters": {
- "key": "cp-key1",
- "property1": "A cart param.",
- "property2": "A cart param."
}, - "note_attributes": {
- "key": "na-key1",
- "property1": "A note attribute.",
- "property2": "A note attribute."
}, - "notes": "A special delivery note.",
- "tags": [
- "order-1"
]
}, - "shipping": {
- "selected_shipping": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}, - "available_shipping_lines": [
- {
- "id": "string",
- "line": {
- "id": "0",
- "description": "Custom weight-based rate: tier 2",
- "amount": 450
}
}
], - "taxes": [
- {
- "value": 1000,
- "name": "GST",
- "is_included": true
}
], - "discounts": [
- {
- "code": "SUMMER5",
- "text": "Summer discount code",
- "value": 500,
- "source": "coupon"
}
]
}, - "resumable_link": "string",
- "flow_id": "external-company-one-page-template",
- "currency": {
- "iso_code": "CAD",
- "iso_numeric_code": 124,
- "symbol": "$",
- "format": "${{amount}}",
- "has_decimal": true,
- "show_iso_code": true
}, - "created_via": "My_Order_Creating_Plugin",
- "is_processed": false,
- "order_id": 79047599,
- "platform_order_id": "1389wjfalsdf9y4r"
}, - "public_order_id": "4U2bwe9SAQY039WGUKM5b2KoxKUKcgyLNvuEKB03Z2HzWbjYB1n4MoC7HuhLT45M",
- "order_id": 829,
- "platform_order_id": "",
- "platform_friendly_identifier": "",
- "order_source": "e3b37c97-8544-4fee-b8f3-cf33deb28be5",
- "order_source_name": "api_v2",
- "fulfillment_status": "unfulfilled",
- "fulfillment_data": [ ]
}
}
List Webhooks
Retrieves a list of registered webhooks.
Authorizations:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
{- "data": [
- {
- "webhook_topic_id": 1,
- "webhook_topic_name": "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",
- "created_at": "2022-11-23 17:11:06",
- "updated_at": "2022-11-23 17:11:06"
}
]
}
Update Webhook
Updates the webhook callback URL. Webhook topics cannot be updated.
Learn more about updating webhooks in the Webhooks guide.
Authorizations:
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. |
webhook_topic_id required | string The webhook topic id. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
callback_url required | string (CallbackURL) The URL that the webhook payload will be sent to. |
Responses
Request samples
- Payload
{
}
Response samples
- 200
- 422
{- "data": {
- "webhook_topic_id": 1,
- "webhook_topic_name": "order/created",
- "created_at": "2021-11-17 21:03:36",
- "updated_at": "2021-11-17 21:03:36"
}
}
Delete Webhook
Removes an existing webhook.
Learn more about removing webhooks in the Webhooks guide.
Authorizations:
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. |
webhook_topic_id required | string The webhook topic id. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
[ ]
List Webhook Topics
Gets the list of available webhook topics.
Possible webhook topics from Checkout Backend API are:
order/processed
order/created
order/fulfilled
order/abandoned
order/failed
gift_card/created
Read about webhook topics in the Webhook Topics guide.
Authorizations:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
{- "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"
}
]
}
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:
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. |
header Parameters
Authorization required | string <Bearer-Token> Example: 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
{- "data": {
- "checkout_process": {
- "company_name_option": "hidden",
- "phone_number_required": false,
- "accepts_marketing_checkbox_option": "unchecked"
}, - "address_autocomplete": {
- "provider": "google",
- "api_key": "awefa9304q9wfqf43jfaw904kfwkaslserfa94"
}
}
}