openapi: 3.0.0
info:
title: Checkout Admin
version: '2.0'
description: |-
Use the Checkout Admin API to configure store-level settings. This includes the ability to configure overrides.
Refer to the changelog for the latest updates to this API.
termsOfService: https://boldcommerce.com/terms-of-service
contact:
name: Contact Us
url: https://developer-dashboard.boldcommerce.com/default/contactus
servers:
- url: https://api.boldcommerce.com
security:
- OAuthToken: []
- APIAccessToken: []
tags:
- name: Cross Origin Resource Sharing (CORS)
description: Contains information about the domains that can access the Bold Checkout APIs. Use these endpoints to manage the approved domains.
- name: External Payment Gateways
description: Contains information about an external payment gateway that can be integrated into a store's checkout experience. Use these endpoints to manipulate the external payment gateways for a store.
- name: Gift Cards
description: Contains information about Gift Cards on a given store. Use this endpoint to get all data associated with a Gift Card for a store.
- name: Integrations
description: Contains a shared secret, which is used to configure the webhooks that your integration uses.
- name: Lightweight Frontend Experience (LiFE) Elements
description: Contains information about the Checkout Lightweight Frontend Experience (LiFE) Elements, which enable you to add custom elements into your checkout experience. Use these endpoints to add, edit, and delete elements.
- name: Overrides
description: Contains information about the API overrides on a given store, such as the override type, redirect URL, and shared secret. Use these endpoints to manipulate overrides for a store.
- name: Payment CSS
description: Contains information about the CSS used to style the [Secure Payments Interface (SPI)](/guides/checkout/resources/glossary#secure-payments-interface-spi). Use these endpoints to manipulate the SPI iFrame for all orders on a store.
- name: Remote State Authority
description: Contains information about the Remote State Authority on a given store, such as the URL and shared secret. Use these endpoints to manipulate configuration details for the Remote State Authority for a store. Refer to [Create a Checkout Remote State Authority](/default/guides/platform-connector/rsa/create-checkout-rsa) for more information.
- name: Saved Payment Methods
description: Contains information about customers' payment methods. Use these endpoints to retrieve or modify saved payment methods.
- name: Shops
description: Contains information about the store's checkout configuration, which is set in the [Bold Checkout admin](https://apps.boldapps.net/accounts/app/4).
- name: Tax Zone Settings
description: Contains information about tax providers for individual tax zones.
- name: Warehouses
description: Contains information about the warehouses for a given store. This information is required to retrieve shipping rates and calculate taxes.
- name: Webhooks
description: Contains information about the webhooks registered on a given store. Use these endpoints to manipulate the webhooks registered on your store.
- name: Zones
description: |
Contains information about the [zones](/guides/checkout/resources/glossary#zone) for a given store. Use these endpoints to manipulate the [shipping zones](/guides/checkout/resources/glossary#shipping-zone), [tax zones](/guides/checkout/resources/glossary#tax-zone), and [warehouse zones](/guides/checkout/resources/glossary#warehouse-zone) for a store.
> **Tip:** Some operations in Checkout require at least one zone to be created. If you have no interest in specific regions, you can use a [default zone](/guides/checkout/resources/glossary#default-zone) instead.
externalDocs:
description: For more information about Checkout, refer to the Overview.
url: https://developer.boldcommerce.com/guides/checkout
paths:
/checkout/shop/{shop_identifier}/cors:
parameters:
- $ref: '#/components/parameters/shop_identifier'
post:
summary: Add Domain to CORS Allowlist
operationId: AddDomainCORSAllowlist
tags:
- Cross Origin Resource Sharing (CORS)
description: |-
Adds a domain to the list of domains with permission to call the Bold Checkout APIs.
Use this endpoint if you are self-hosting your checkout. This endpoint is also required to enable self-hosted development stores to call the Bold Checkout APIs.
requestBody:
content:
application/json:
schema:
type: object
properties:
domain:
$ref: '#/components/schemas/CORSDomain'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CORSDomainList'
examples:
CORSDomains:
$ref: '#/components/examples/CORSDomainsExample'
'500':
$ref: '#/components/responses/UnknownError'
get:
summary: Get CORS Allowlist
operationId: GetCORSAllowlist
tags:
- Cross Origin Resource Sharing (CORS)
description: Retrieves the list of domains with permission to call the Bold Checkout APIs.
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- type: object
description: The list of domains on the CORS allowlist.
properties:
data:
type: array
items:
$ref: '#/components/schemas/CORSDomainList'
- type: object
description: An empty object, indicating that there are no domains in the CORS allowlist.
properties:
data:
type: object
maxProperties: 0
examples:
CORSDomains:
$ref: '#/components/examples/CORSDomainsExample'
NoCORSDomains:
value:
data: {}
'500':
$ref: '#/components/responses/UnknownError'
/checkout/shop/{shop_identifier}/cors/{domain_id}:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- $ref: '#/components/parameters/domain_id'
delete:
summary: Delete Domain from CORS Allowlist
operationId: DeleteDomainFromCORSAllowlist
tags:
- Cross Origin Resource Sharing (CORS)
description: Deletes a domain from the list of domains with permission to call the Bold Checkout APIs. Specify the domain to be deleted using the `domain_id` in the request route.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
maxLength: 0
items: {}
'404':
description: Domain ID does not exist
content:
application/json:
schema:
type: array
maxLength: 0
items: {}
/checkout/shop/{shop_identifier}/life_elements:
parameters:
- $ref: '#/components/parameters/shop_identifier'
post:
summary: Create Element
operationId: CreateElement
tags:
- Lightweight Frontend Experience (LiFE) Elements
description: Adds a LiFE element to the store's checkout at a specific location. For more information about the locations and where they are, refer to the [Checkout LiFE guide](/guides/checkout/life).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LiFE_element'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
life_elements:
$ref: '#/components/schemas/LiFE_element'
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
NameFieldIsRequired:
value:
errors:
- code: 02-94
type: life_element.invalid_life_element_data
message: The meta_data_field is required.
details: {}
get:
summary: List Elements
operationId: ListElements
tags:
- Lightweight Frontend Experience (LiFE) Elements
description: Lists the LiFE elements that are associated with a given store's checkout.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
life_elements:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/LiFE_element'
/checkout/shop/{shop_identifier}/life_elements/{public_element_id}:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- $ref: '#/components/parameters/public_element_id'
patch:
summary: Update Element
operationId: UpdateElement
tags:
- Lightweight Frontend Experience (LiFE) Elements
description: Updates a LiFE element that already exists on a store's checkout. You can edit any of the element's attributes using this endpoint.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
life_elements:
$ref: '#/components/schemas/LiFE_element'
'422':
description: Unprocessable request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
LifeElementNotFound:
value:
errors:
- code: 02-94
type: life_element.life_element_not_configured
message: LiFE element with the given `public_id` not found.
details: {}
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LiFE_element'
delete:
summary: Delete Element
operationId: DeleteElement
description: Removes a LiFE element from a store's checkout.
tags:
- Lightweight Frontend Experience (LiFE) Elements
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
'422':
description: Unprocessable request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
LifeElementNotFound:
value:
errors:
- code: 02-91
type: life_element.life_element_not_configured
message: LiFE element with the given `public_id` not found.
details: {}
/checkout/shop/{shop_identifier}/external_payment_gateways:
parameters:
- $ref: '#/components/parameters/shop_identifier'
post:
summary: Create External Payment Gateway
operationId: CreateExternalPaymentGateway
tags:
- External Payment Gateways
description: Adds an external payment gateway to a store.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
external_payment_gateway:
$ref: '#/components/schemas/ExternalPaymentGateway'
examples:
example-1:
value:
data:
external_payment_gateway:
public_id: VfYRxzOjRkwG6B2xWbxhPQ
name: External Payment Gateway
base_url: www.example.com/payments
iframe_url: www.example.com/gateway
api_token: XjqnSQWYAZXt
partial_capture: true
additional_order_details: true
provider_id: 8ad85ccf-7fd6-4f4b-a1a2-dff42fb3e228
currency: CAD
location: payment_method_below
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
NameFieldIsRequired:
value:
errors:
- code: 02-91
type: external_payment_gateway.invalid_external_payment_gateway_data
message: The name field is required.
details: {}
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalPaymentGateway'
examples:
example-1:
value:
name: External Payment Gateway
base_url: www.example.com/payments
iframe_url: www.example.com/gateway
api_token: XjqnSQWYAZXt
partial_capture: true
additional_order_details: true
provider_id: 8ad85ccf-7fd6-4f4b-a1a2-dff42fb3e228
currency: CAD
http_headers:
- key: foo
value: bar
location: payment_method_below
get:
summary: List External Payment Gateways
operationId: ListExternalPaymentGateways
tags:
- External Payment Gateways
description: Lists external payment gateways for a given store.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
external_payment_gateways:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ExternalPaymentGateway'
examples:
example-1:
value:
data:
external_payment_gateways:
- public_id: SqCAft3jGmwDVK8aQbhi2R
name: First External Payment Gateway
base_url: www.example-1.com/payments
iframe_url: www.example-1.com/gateway
api_token: XjqnSQWYAZXt
partial_capture: true
additional_order_details: true
provider_id: 5dgg27kce-2jd7-1h8v-j2f5-xsgn2di9s764
currency: CAD
location: payment_method_below
http_headers:
- key: foo
value: bar
- public_id: VfYRxzOjRkwG6B2xWbxhPQ
name: Second External Payment Gateway
base_url: www.example-2.com/payments
iframe_url: www.example-2.com/gateway
api_token: PjqnSQWYAZXz
partial_capture: true
additional_order_details: true
provider_id: 8ad85ccf-7fd6-4f4b-a1a2-dff42fb3e228
currency: CAD
location: payment_method_below
http_headers: null
/checkout/shop/{shop_identifier}/external_payment_gateways/{public_gateway_id}:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- $ref: '#/components/parameters/public_gateway_id'
patch:
summary: Update External Payment Gateway
operationId: UpdateExternalPaymentGateway
tags:
- External Payment Gateways
description: Updates an external payment gateway on a store.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
external_payment_gateway:
$ref: '#/components/schemas/ExternalPaymentGateway'
examples:
example-1:
value:
data:
external_payment_gateway:
public_id: VfYRxzOjRkwG6B2xWbxhPQ
name: External Payment Gateway
base_url: www.example.com/payments
iframe_url: www.example.com/gateway
api_token: XjqnSQWYAZXt
partial_capture: true
additional_order_details: true
provider_id: 8ad85ccf-7fd6-4f4b-a1a2-dff42fb3e228
currency: CAD
http_headers:
- key: foo
value: bar
location: payment_method_below
'422':
description: Unprocessable request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
PaymentGatewayNotFound:
value:
errors:
- code: 02-91
type: external_payment_gateway.not_found
message: External payment gateway with the given `public_id` not found.
details: {}
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalPaymentGateway'
examples:
example-1:
value:
name: External Payment Gateway
base_url: www.example.com/payments
iframe_url: www.example.com/gateway
api_token: XjqnSQWYAZXt
partial_capture: true
additional_order_details: true
provider_id: 8ad85ccf-7fd6-4f4b-a1a2-dff42fb3e228
currency: CAD
http_headers:
- key: foo
value: bar
location: payment_method_below
delete:
summary: Delete External Payment Gateway
operationId: DeleteExternalPaymentGateway
description: Removes an external payment gateway from a store.
tags:
- External Payment Gateways
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
'422':
description: Unprocessable request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
PaymentGatewayNotFound:
value:
errors:
- code: 02-91
type: external_payment_gateway.not_found
message: External payment gateway with the given `public_id` not found.
details: {}
/checkout/shop/{shop_identifier}/customer/{public_customer_id}/payment_methods:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- $ref: '#/components/parameters/public_customer_id'
get:
summary: List Saved Payment Methods
operationId: ListSavedPaymentMethods
tags:
- Saved Payment Methods
description: Lists all saved payment methods for a specific customer.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CustomerPaymentMethods'
example:
success: true
cards:
- type: credit_card
public_id: ZdtkGke3jqR4qeI9IvtrHaRQZxdobJ5SaGdcX7V22O0v2U5bBqDGb6FHAkpPk4KS
is_default: false
cc_type: Visa
last_four: '1111'
expiration:
date: 2023-11
/checkout/shop/{shop_identifier}/customer/stored-cards/{public_payment_id}:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- $ref: '#/components/parameters/public_payment_id'
delete:
summary: Delete Saved Payment Method
operationId: DeleteSavedPaymentMethod
tags:
- Saved Payment Methods
description: Deletes the saved payment method associated with a public payment identifier.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/DeletePaymentMethod'
examples:
OneOrMorePaymentMethodsRemaining:
value:
success: true
defaultCardId: 1
NoRemainingPaymentMethods:
value:
success: true
defaultCardId: ''
/checkout/shop/{shop_identifier}/overrides:
parameters:
- $ref: '#/components/parameters/shop_identifier'
post:
summary: Create API Override
operationId: CreateAPIOverride
tags:
- Overrides
description: Creates an API override for a given store. The API override is used to customize base functionality. Store level API overrides will apply to all orders, but per-order overrides may take priority. For more information, refer to [API Overrides](/guides/checkout/api-overrides).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OverrideRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/OverrideConfig'
examples:
example-1:
value:
data:
public_id: '1'
override_type: discount
url: https://example.com/overrides/callback_url
created_at: '2021-11-17 21:03:36'
updated_at: '2021-11-17 21:03:36'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsV1'
examples:
OverrideTypeDoesNotExist:
value:
errors:
- message: The override_type does not exist.
type: api_override
field: override_type
severity: validation
sub_type: api_override
InvalidURL:
value:
errors:
- message: The `url` field must be a valid url.
type: api_override
field: url
severity: validation
sub_type: api_override
get:
summary: List API Overrides
operationId: ListAPIOverrides
tags:
- Overrides
description: Retrieves a list of registered API overrides for a given store.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/OverrideConfig'
examples:
example-1:
value:
data:
- public_id: '1'
override_type: discount
url: https://example.com/overrides/discount
created_at: '2021-11-17 21:03:36'
updated_at: '2021-11-17 21:03:36'
- public_id: '2'
override_type: shipping
url: https://example.com/overrides/shipping
created_at: '2021-11-17 21:03:36'
updated_at: '2021-11-17 21:03:36'
/checkout/shop/{shop_identifier}/overrides/{public_id}:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- schema:
type: string
name: public_id
in: path
required: true
description: The identifier for the affected API override.
patch:
summary: Update API Override
operationId: UpdateAPIOverride
tags:
- Overrides
description: Updates the given override. Enables the caller to update the `url` property, the `override_type` property, or both, for a given API override. A store can have more than one API override of the same type.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OverrideRequest'
example:
override_type: discount
url: https://example.com/overrides/updated_callback_url
shared_secret: aq9834g4aqkdwa0
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/OverrideConfig'
examples:
UpdatedCallbackURL:
value:
data:
public_id: '1'
override_type: discount
url: https://example.com/overrides/updated_callback_url
created_at: '2021-11-17 21:03:36'
updated_at: 2021-11-20 215:09:22
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsV1'
examples:
OverrideTypeDoesNotExist:
value:
errors:
- message: The override_type does not exist.
type: api_override
field: override_type
severity: validation
sub_type: api_override
InvalidURL:
value:
errors:
- message: The `url` field must be a valid url.
type: api_override
field: url
severity: validation
sub_type: api_override
delete:
summary: Delete API Override
operationId: DeleteAPIOverride
tags:
- Overrides
description: Delete an API override from the given store.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorsV1'
examples:
MissingPublicID:
value:
errors:
- message: The `public id` field is required.
type: api_override
field: public_id
severity: validation
sub_type: api_override
/checkout/shop/{shop_identifier}/rsa_config:
parameters:
- $ref: '#/components/parameters/shop_identifier'
post:
summary: Connect Remote State Authority
operationId: ConnectRemoteStateAuthority
tags:
- Remote State Authority
description: Connects Remote State Authority to a given shop.
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The destination URL to which a request will be made when order state changes occur.
example: https://example.com/my_remote_state_authority
shared_secret:
type: string
description: Your shared secret, which can be any string you choose. Bold uses this string and the current date to create a signature for each request.
minLength: 8
maxLength: 255
example: d5210fa5563dd4f5b06f00d0
required:
- url
- shared_secret
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/RemoteStateAuthorityConfig'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Invalid URL:
value:
errors:
- code: 02-89
type: remote_state_authority.rsa_already_configured
message: Remote State Authority already configured. Please update configuration instead.
patch:
summary: Update Remote State Authority Connection
operationId: UpdateRemoteStateAuthorityConnection
tags:
- Remote State Authority
description: Updates connection to a Remote State Authority for a given shop.
requestBody:
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The destination URL to which a request will be made when order state changes occur.
example: https://example.com/my_remote_state_authority
shared_secret:
type: string
description: Your shared secret, which can be any string you choose. Bold uses this string and the current date to create a signature for each request.
minLength: 8
maxLength: 255
example: d5210fa5563dd4f5b06f00d0
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/RemoteStateAuthorityConfig'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Invalid URL:
value:
errors:
- code: 02-89
type: remote_state_authority.rsa_not_configured
message: Remote State Authority not configured.
get:
summary: Get Remote State Authority
operationId: GetRemoteStateAuthority
tags:
- Remote State Authority
description: Gets Remote State Authority connection details for a given shop.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/RemoteStateAuthorityConfig'
examples:
ConfigurationFound:
value:
data:
remote_state_authority:
url: https://example.com/my_remote_state_authority
ConfigurationNotFound:
value:
data:
remote_state_authority: null
delete:
summary: Delete Remote State Authority
operationId: DeleteRemoteStateAuthority
tags:
- Remote State Authority
description: Removes Remote State Authority functionality for a given shop.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
remote_state_authority: {}
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Remote State Authority not configured:
value:
errors:
- code: 02-89
type: remote_state_authority.rsa_not_configured
message: Remote State Authority not configured.
/checkout/shop/{shop_identifier}/gift_card:
parameters:
- $ref: '#/components/parameters/shop_identifier'
get:
summary: Get Gift Card
operationId: GetGiftCard
tags:
- Gift Cards
description: |-
Gets a gift card on a given shop, specified by either the `public_payment_method_id` or a combination of the `card_token` and `card_pin`.
For more information, refer to the [Manage Gift Cards](/guides/checkout/gift-cards) guide.
parameters:
- in: query
name: params
required: true
style: form
explode: true
schema:
type: object
oneOf:
- type: object
title: Public Payment Method Id
properties:
public_payment_method_id:
type: string
description: The payment public ID of the gift card, assigned when configured as a customer's payment method.
example: i5uATT2QVKlozoDA2msg89w3mWAdPTIeLtED44R1SJYUVuI7jO4NqHdM8vjoqq7A7P
required:
- public_payment_method_id
- type: object
title: Card Token and Pin
properties:
card_token:
type: string
description: The gift card token.
example: AJPG-TPOE-FNAA-MDEH
card_pin:
type: string
description: The gift card PIN.
example: '937'
required:
- card_token
- card_pin
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
gift_card:
$ref: '#/components/schemas/GiftCard'
examples:
GiftCardFound:
value:
data:
gift_card:
card_token: OAVXDVRAJUGFMHEK
amount: 5000
balance: 2575
recipient_name: John
recipient_email: john.smith@example.com
message: Enjoy this gift certificate from us.
expiry_date: '2025-04-01'
customer_name: Jane
customer_email: jane.doe@example.com
'422':
description: Unprocessable entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Provide either public_payment_method_id or card_token and PIN:
value:
errors:
- code: 02-50
type: gift_cards.invalid_gift_card_data
message: Please provide one of `public payment method id` or `card token` and `card pin`.
The card_pin is required:
value:
errors:
- code: 02-50
type: gift_cards.invalid_gift_card_data
message: The card pin field is required when the `card token` field is present.
Gift Card not found:
value:
errors:
- code: 02-87
type: gift_cards.gift_card_not_found
message: The gift card was not found.
'500':
$ref: '#/components/responses/UnknownError'
/checkout/shop/{shop_identifier}/integration/config:
parameters:
- $ref: '#/components/parameters/shop_identifier'
post:
summary: Configure Integration Settings
operationId: ConfigureIntegrationSettings
tags:
- Integrations
description: |-
Configures webhooks to integrate with your shop, using a given shared secret.
Read more about configuring webhook integration in the [Register for Webhooks guide](/guides/checkout/webhooks#configure-the-shared-secret).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigureIntegrationBody'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
minItems: 0
maxItems: 0
items: {}
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntity'
examples:
MissingSharedSecret:
value:
errors:
- message: The shared secret field is required.
type: integration_config
field: shared_secret
severity: validation
sub_type: ''
'500':
description: Occurs if the shop could not be determined.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorV2'
examples:
CouldNotFindShop:
value:
code: 11-13
type: integration_config.shop_could_not_be_determined
message: shop could not be determined
/checkout/shop/{shop_identifier}/zones/{zone_id}/tax_zone_settings:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- $ref: '#/components/parameters/zone_id'
post:
summary: Create Tax Zone Setting
operationId: CreateTaxZoneSetting
tags:
- Tax Zone Settings
description: Creates or updates a tax zone setting for a tax zone. There can only be one tax zone setting for a tax zone.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TaxZoneSettingRequest'
example:
tax_provider: override
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TaxZoneSettingConfig'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Missing Request Data:
value:
errors:
- code: 02-50
type: tax_zone_setting.invalid_tax_zone_setting_data
message: The tax_provider field is required.
Invalid Zone ID:
value:
errors:
- code: 02-38
type: tax_zone_setting.zone_not_found
message: No zone found with id 282.
delete:
summary: Delete Tax Zone Settings
operationId: DeleteTaxZoneSetting
tags:
- Tax Zone Settings
description: Deletes a tax zone setting for a tax zone.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Missing Request Data:
value:
errors:
- code: 02-50
type: tax_zone_setting.invalid_tax_zone_setting_data
message: The `zone_id` field must be of type Integer.
/checkout/shop/{shop_identifier}/zones/tax_zone_settings:
parameters:
- $ref: '#/components/parameters/shop_identifier'
get:
summary: Get Tax Zone Settings
operationId: GetTaxZoneSetting
tags:
- Tax Zone Settings
description: Lists all tax zone settings for a shop.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
tax_zone_settings:
type: array
items:
$ref: '#/components/schemas/TaxZoneSettingConfig'
/checkout/shop/{shop_identifier}/zones/{zone_id}/warehouses:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- $ref: '#/components/parameters/zone_id'
post:
summary: Create Warehouse
operationId: CreateWarehouse
tags:
- Warehouses
description: Adds a warehouse to a given shop. Each warehouse must belong to an existing warehouse zone, and a zone can have only one warehouse. Refer to [Create Zone](checkout-admin#operation/CreateZone).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WarehouseRequest'
example:
address: 123 Main St.
address2: c/o Buck Skaggstein
city: American Fork
province_code: UT
province: Utah
country_code: US
country: United States
postal_code: '84003'
extended_postal_code: '52'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/WarehouseConfig'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Invalid Zone ID:
value:
errors:
- code: 02-37
type: zone.zone_not_found
message: No zone found with id 282.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Missing Request Data:
value:
errors:
- code: 02-50
type: warehouse.invalid_warehouse_data
message: The address field is required.
- code: 02-50
type: warehouse.invalid_warehouse_data
message: The postal_code field is required.
Warehouse Already Exists:
value:
errors:
- code: 02-39
type: warehouse.warehouse_already_exists
message: A warehouse already exists for this zone. Please delete it before creating a new one.
details:
warehouse:
$ref: '#/components/schemas/WarehouseConfig'
patch:
summary: Update Warehouse
operationId: UpdateWarehouse
tags:
- Warehouses
description: Updates a warehouse.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WarehouseUpdateRequest'
example:
address: 123 Main St.
address2: c/o Buck Skaggstein
city: American Fork
province_code: UT
province: Utah
country_code: US
country: United States
postal_code: '84003'
extended_postal_code: '52'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/WarehouseConfig'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Invalid Zone ID:
value:
errors:
- code: 02-37
type: zone.zone_not_found
message: No zone found with id 282.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Invalid Address:
value:
errors:
- code: 02-50
type: warehouse.invalid_warehouse_data
message: The `address` field must be of type String.
delete:
summary: Delete Warehouse
operationId: DeleteWarehouse
tags:
- Warehouses
description: Deletes a warehouse.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Invalid Zone ID:
value:
errors:
- code: 02-37
type: zone.zone_not_found
message: No zone found with id 282.
/checkout/shop/{shop_identifier}/zones/warehouses:
parameters:
- $ref: '#/components/parameters/shop_identifier'
get:
summary: List Warehouses
operationId: GetWarehouses
tags:
- Warehouses
description: Lists all warehouses for a given shop.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
warehouses:
type: array
items:
$ref: '#/components/schemas/WarehouseConfig'
/checkout/shop/{shop_identifier}/webhooks:
parameters:
- $ref: '#/components/parameters/shop_identifier'
post:
summary: Create Webhook
operationId: CreateWebhook
tags:
- Webhooks
description: |-
Create a webhook registration by specifying the destination URL and topic.
For more information on Checkout webhooks, refer to [Register for Webhooks](/guides/checkout/webhooks#register-for-the-webhook).
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/WebhookConfig'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorV2'
examples:
TopicIDDoesNotExist:
value:
code: 10-10
type: webhook_subscriptions.webhook_topic_id does not exist
message: webhook_topic_id does not exist.
details: {}
MissingRequiredField:
value:
message: The callback_url field is required.
type: webhook_subscriptions
severity: validation
field: callback_url
sub_type: ''
requestBody:
content:
application/json:
schema:
type: object
properties:
webhook_topic_id:
$ref: '#/components/schemas/WebhookTopicID'
callback_url:
$ref: '#/components/schemas/CallbackURL'
required:
- webhook_topic_id
- callback_url
callbacks:
ProcessedOrder:
'{$request.body#/callback_url/order/processed}':
post:
summary: Processed Order
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessedOrderWebhook'
example:
value:
domain: store-vwd2342klmsdf.mybigcommerce.com
platform_domain: example.mybigcommerce.com
application_state:
customer:
accepts_marketing: true
email_address: john.doe@example.com
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
image_url: http://shop.images/oakcheesegrater
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
code: EXPID
available_shipping_lines:
- id: string
line:
id: '0'
description: 'Custom weight-based rate: tier 2'
amount: 450
code: EXPID
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: []
responses:
'200':
description: Successful operation
CreatedOrder:
'{$request.body#/callback_url/order/created}':
post:
summary: Created Order
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedOrderWebhook'
example:
value:
domain: store-vwd2342klmsdf.mybigcommerce.com
platform_domain: example.mybigcommerce.com
application_state:
customer:
accepts_marketing: true
email_address: john.doe@example.com
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
image_url: http://shop.images/oakcheesegrater
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
code: EXPID
available_shipping_lines:
- id: string
line:
id: '0'
description: 'Custom weight-based rate: tier 2'
amount: 450
code: EXPID
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: '179'
platform_friendly_identifier: '179'
order_source: e3b37c97-8544-4fee-b8f3-cf33deb45be5
order_source_name: api_v2
fulfillment_status: unfulfilled
fulfillment_data: []
responses:
'200':
description: Successful operation
FulfilledOrder:
'{$request.body#/callback_url/order/fulfilled}':
post:
summary: Fulfilled Order
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FulfilledOrderWebhook'
example:
value:
domain: store-vwd2342klmsdf.mybigcommerce.com
platform_domain: example.mybigcommerce.com
application_state:
customer:
accepts_marketing: true
email_address: john.doe@example.com
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
image_url: http://shop.images/oakcheesegrater
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
code: EXPID
available_shipping_lines:
- id: string
line:
id: '0'
description: 'Custom weight-based rate: tier 2'
amount: 450
code: EXPID
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: '179'
platform_friendly_identifier: '179'
order_source: e3b37c97-8544-4fee-b8f3-cf33deb45be5
order_source_name: api_v2
fulfillment_status: fulfilled
fulfillment_data:
total_value: 17
total_shipping_value: 10
shipping_details: []
tracking_company: ups
tracking_number: sJKfh72hKD7djh
tracking_url: https://www.ups.com/example-tracking-links
location_id: -3
fulfilled_at: '2022-01-04 19:52:16'
fulfilled_items: []
total_discount: 12
total_fees: 4
order_fees: []
total_order_fees: 13
total_tax: 5
responses:
'200':
description: Successful operation
FailedOrder:
'{$request.body#/callback_url/order/failed}':
post:
summary: Failed Order
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FailedOrderWebhook'
example:
value:
domain: store-vwd2342klmsdf.mybigcommerce.com
platform_domain: example.mybigcommerce.com
application_state:
customer:
accepts_marketing: true
email_address: john.doe@example.com
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
image_url: http://shop.images/oakcheesegrater
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
code: EXPID
available_shipping_lines:
- id: string
line:
id: '0'
description: 'Custom weight-based rate: tier 2'
amount: 450
code: EXPID
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: '179'
platform_friendly_identifier: '179'
order_source: e3b37c97-8544-4fee-b8f3-cf33deb45be5
order_source_name: api_v2
fulfillment_status: unfulfilled
fulfillment_data: []
responses:
'200':
description: Successful operation
AbandonedOrder:
'{$request.body#/callback_url/order/abandoned}':
post:
summary: Abandoned Order
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AbandonedOrderWebhook'
example:
value:
public_order_id: nPTPIlIahDoEgZFabZNNvg7uxahLkGb1x4UINz3eqYV3eHewsjq7kubZc5BLAUqC
line_items:
discounts: []
fees: []
product_data:
barcode: 1234ABC
compare_at_price: 4000
description: A handmade oak cheese grater to elevate your cheese-eating experience.
id: 724bca
image_url: http://shop.images/oakcheesegrater
line_item_key: ABC123
price: 2350
product_id: oak-cheese-grater
properties: []
quantity: 2
requires_shipping: true
sku: OAK_GRATER_SM
tags: Kitchen, Cheese Board, Oak
taxable: true
title: Small
total_price: 4700
variant_id: oak-cheese-grater-small
vendor: Cheese Boards Unlimited
visible: 1
weight: 1000
weight_unit: g
taxes: []
customer:
accepts_marketing: true
email_address: john.doe@example.com
first_name: John
last_name: Doe
platform_id: null
public_id: sTaGXlJuMIz1fzdnE8HSXkK1m2ym9FRbrwxqiS2t7XylVEMBT7YX1Xeep6V7cT53
saved_addresses: []
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
resumable_link: https://checkout.example.com/resume
shop:
domain: store-vwd2342klmsdf.mybigcommerce.com
platform_domain: example.mybigcommerce.com
responses:
'200':
description: Successful operation
GiftCardCreated:
'{$request.body#/callback_url/gift_card/created}':
post:
summary: Gift Card Created
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GiftCardCreatedWebhook'
example:
value:
domain: store-vwd2342klmsdf.mybigcommerce.com
platform_domain: example.mybigcommerce.com
public_order_id: 4U2bwe9SAQY039WGUKM5b2KoxKUKcgyLNvuEKB03Z2HzWbjYB1n4MoC7HuhLT45M
platform_order_id: 179
platform_customer_id: null
customer:
email: john.doe@example.com
first_name: John
last_name: Doe
gift_card_email: john.doe@example.com
gift_card_token: TYIDFASDFOCXOMT
gift_card_key: '107'
gift_card_amount: 2500
responses:
'200':
description: Successful operation
get:
summary: List Webhooks
operationId: ListWebhooks
tags:
- Webhooks
description: Retrieves a list of registered webhooks.
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- type: object
title: Results
properties:
data:
type: array
items:
$ref: '#/components/schemas/WebhookConfig'
minItems: 1
uniqueItems: true
- type: array
title: No Results
minItems: 0
maxItems: 0
items: {}
examples:
example-1:
value:
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'
/checkout/shop/{shop_identifier}/webhooks/{webhook_topic_id}:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- schema:
type: string
name: webhook_topic_id
in: path
required: true
description: The webhook topic id.
put:
summary: Update Webhook
operationId: UpdateWebhook
tags:
- Webhooks
description: |-
Updates the webhook callback URL. Webhook topics cannot be updated.
Learn more about updating webhooks in the [Webhooks guide](/guides/checkout/webhooks#update-or-delete-webhooks).
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/WebhookConfig'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
example-1:
value:
message: The callback url field is required.
type: webhook_subscriptions
field: callback_url
severity: validation
sub_type: ''
requestBody:
content:
application/json:
schema:
type: object
properties:
callback_url:
$ref: '#/components/schemas/CallbackURL'
required:
- callback_url
examples:
example-1:
value:
callback_url: https://my-app.com/webhooks/different_callback_url
delete:
summary: Delete Webhook
operationId: DeleteWebhook
tags:
- Webhooks
description: |-
Removes an existing webhook.
Learn more about removing webhooks in the [Webhooks guide](/guides/checkout/webhooks#update-or-delete-webhooks).
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
minItems: 0
maxItems: 0
items: {}
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
example-1:
value:
message: The webhook topic id field is required.
type: webhook_subscriptions
field: webhook_topic_id
severity: validation
sub_type: ''
/checkout/shop/{shop_identifier}/webhooks/topics:
parameters:
- $ref: '#/components/parameters/shop_identifier'
get:
summary: List Webhook Topics
operationId: ListWebhookTopics
tags:
- Webhooks
description: |-
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](/guides/checkout/webhooks#get-a-list-of-webhook-topics).
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: A list of available webhook topics.
items:
$ref: '#/components/schemas/WebhookTopic'
minItems: 0
uniqueItems: true
example:
- 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
/checkout/shop/{shop_identifier}/zones:
parameters:
- $ref: '#/components/parameters/shop_identifier'
post:
summary: Create Zone
operationId: CreateZone
tags:
- Zones
description: Adds a warehouse, shipping, or tax zone.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ZoneRequest'
example:
name: Western Region
type: warehouse
regions:
- country_code: CA
province_code: MB
- country_code: CA
province_CODE: SK
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ZoneConfig'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Missing Request Data:
value:
errors:
- code: 02-50
type: zone.invalid_zone_data
message: The name field is required.
Invalid Zone Type:
value:
errors:
- code: 02-50
type: zone.invalid_zone_data
message: 'The type field must be one the following values: shipping, tax, warehouse'
Invalid Region Data:
value:
errors:
- code: 02-37
type: zone.country_not_found_by_code
message: 'Zone not created: invalid country code(s) [ZZ,YQ]'
- code: 02-37
type: zone.province_not_found_by_code
message: 'Zone not created: invalid province code(s) [H3,PL]'
Default Zone Exists:
value:
errors:
- code: 02-37
type: zone.default_zone_already_exists
message: 'Unable to create default zone: Default zone already exists'
Region Already Exists:
value:
errors:
- code: 02-37
type: zone.region_already_exists
message: 'The zone CountryId: 4, ProvinceId: 7, ZoneTypeId: 1 already exists in another zone for this shop'
details:
zone_id: 279,
country_code: CA
province_code: MB
get:
summary: List Zones
operationId: GetZone
tags:
- Zones
description: Lists all zones for a shop.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
zones:
type: array
items:
$ref: '#/components/schemas/ZoneConfig'
/checkout/shop/{shop_identifier}/zones/{zone_id}:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- $ref: '#/components/parameters/zone_id'
patch:
summary: Update Zone
operationId: UpdateZone
tags:
- Zones
description: Updates an existing zone. Note that it is not possible to update an existing zone's `type`.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ZoneUpdateRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ZoneConfig'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Zone Not Found:
value:
errors:
- code: 02-37
type: zone.zone_not_found
message: Zone not found.
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Missing Request Data:
value:
errors:
- code: 02-50
type: zone.invalid_zone_data
message: The zone_id field is required.
Prohibited Request Data:
value:
errors:
- code: 02-50
type: zone.invalid_zone_data
message: The type field is not allowed.
Invalid Region Data:
value:
errors:
- code: 02-37
type: zone.country_not_found_by_code
message: 'Zone not created: invalid country code(s) [ZZ,YQ]'
- code: 02-37
type: zone.province_not_found_by_code
message: 'Zone not created: invalid province code(s) [H3,PL]'
Default Zone Exists:
value:
errors:
- code: 02-37
type: zone.default_zone_already_exists
message: 'Unable to create default zone: Default zone already exists'
Region Already Exists:
value:
errors:
- code: 02-37
type: zone.region_already_exists
message: 'The zone CountryId: 4, ProvinceId: 7, ZoneTypeId: 1 already exists in another zone for this shop'
details:
zone_id: 279,
country_code: CA
province_code: MB
delete:
summary: Delete Zone
operationId: DeleteZone
tags:
- Zones
description: Deletes an existing zone. Any regions, tax zone settings, and warehouses associated with the zone will also be deleted.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Missing Request Data:
value:
errors:
- code: 02-50
type: zone.invalid_zone_data
message: The zone_id field is required.
/checkout/shop/{shop_identifier}/general_settings:
parameters:
- $ref: '#/components/parameters/shop_identifier'
get:
summary: Get Shop General Settings
operationId: GetShopGeneralSettings
tags:
- Shops
description: Retrieves basic settings from the shop's General Settings section in the [Bold Checkout admin](https://apps.boldapps.net/accounts/app/4).
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/GeneralSettings'
put:
summary: Update Shop General Settings
operationId: UpdateShopGeneralSettings
tags:
- Shops
description: Updates basic settings from the shop's General Settings section in the [Bold Checkout admin](https://apps.boldapps.net/accounts/app/4).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GeneralSettingsUpdateRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/GeneralSettings'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Prohibited Request Data:
value:
errors:
- code: 02-95
type: general_settings.invalid_settings_data
message: The `public order id.enabled` field must be of type Boolean.
/checkout/shop/{shop_identifier}/general_settings/phone_number_required:
parameters:
- $ref: '#/components/parameters/shop_identifier'
put:
summary: Update Phone Number Requirement
operationId: UpdatePhoneNumberRequirement
tags:
- Shops
description: Updates the phone number requirement setting for a store. This setting can also be edited from the store's **General Settings** section in the [Bold Checkout admin](https://apps.boldapps.net/accounts/app/4).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberRequiredUpdateRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/GeneralSettings'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Prohibited Request Data:
value:
errors:
- code: 02-95
type: general_settings.invalid_settings_data
message: The `phone number required` field must be of type Boolean.
/checkout/shop/{shop_identifier}/general_settings/require_inventory_check:
parameters:
- $ref: '#/components/parameters/shop_identifier'
put:
summary: Update Inventory Check Requirement
operationId: UpdateInventoryCheckRequirement
tags:
- Shops
description: |-
Updates the inventory check requirement setting for a store. If required, an inventory check is performed in response to the [Process Order](/api/checkout#tag/Orders/operation/ProcessOrder) endpoint, and the endpoint returns a 422 error if there is not enough inventory to complete the order.
The inventory check is required by default. You can use this endpoint to disable the inventory check requirement during order processing.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RequireInventoryCheckUpdateRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/GeneralSettings'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Prohibited Request Data:
value:
errors:
- code: 02-95
type: general_settings.invalid_settings_data
message: The `require inventory check` field is required.
/checkout/shop/{shop_identifier}/general_settings/create_platform_customer:
parameters:
- $ref: '#/components/parameters/shop_identifier'
put:
summary: Update Platform Customer Creation Setting
operationId: UpdateCreatePlatformCustomer
tags:
- Shops
description: |-
Updates the platform customer creation setting for a store. On many platforms, whenever Bold creates a new order, it also creates a new customer if it does not already exist on the platform. Some platforms, such as Adobe Commerce, do not behave this way natively, and attempting to create a customer during order creation can cause unexpected errors. Updating this setting to `false` prevents Bold from attempting to create a customer on the platform when a new order is created.
This setting defaults to `true`.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePlatformCustomerUpdateRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/GeneralSettings'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
Prohibited Request Data:
value:
errors:
- code: 02-95
type: general_settings.invalid_settings_data
message: The `create platform customer` field is required.
/checkout/shop/{shop_identifier}/pmmc_session:
parameters:
- $ref: '#/components/parameters/shop_identifier'
- $ref: '#/components/parameters/platform_customer_id'
- $ref: '#/components/parameters/bold_customer_id'
get:
summary: Get PMMC Session
operationId: GetPmmcSession
tags:
- Shops
description: |-
Retrieves a Payment Method Management for Checkout (PMMC) session. Use this endpoint to retrieve the information necessary to load the `