BigCommerce Orders is a feature within the BigCommerce platform that allows users to manage and track their sales orders efficiently. With BigCommerce Orders, users can easily view and process incoming orders, update order statuses, print packing slips and shipping labels, and manage customer communication throughout the order fulfillment process.
openapi: 3.0.3
info:
title: BigCommerce Orders V3
version: ''
description: Manage order settings of BigCommerce stores.
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
license:
name: ''
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Batch Metafields
- name: Metafields
- name: Order Settings
- name: Payment Actions
- name: Transactions
paths:
/orders/{order_id}/payment_actions/capture:
post:
summary: BigCommerce Capture order payment
description: >-
Capture the payment for an order. When there are no payment method
validation issues, the capture process is successful, the
`payment_status` updates to `capture pending`, and the payment request
is scheduled. The payment request itself occurs asynchronously.
Requires at least one of the following scopes:
* `store_v2_orders`
* `store_v2_transactions`
operationId: captureOrderPayment
parameters:
- $ref: '#/components/parameters/ContentType'
responses:
'201':
$ref: '#/components/responses/201_Created'
'400':
$ref: '#/components/responses/400_BadRequest'
'404':
$ref: '#/components/responses/404_NotFound'
'422':
$ref: '#/components/responses/422_UnprocessableEntity'
'502':
$ref: '#/components/responses/502_GatewayError'
'503':
$ref: '#/components/responses/503_ServiceUnavailable'
'504':
$ref: '#/components/responses/504_GatewayTimeout'
tags:
- Payment Actions
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/OrderIdParam'
/orders/{order_id}/payment_actions/void:
post:
summary: BigCommerce Void
description: >-
Void the payment for an order. When there are no payment method
validation issues, the void process is successful, the `payment_status`
updates to `void pending`, and the void payment request is scheduled.
The payment request itself occurs asynchronously.
Requires at least one of the following scopes:
* `store_v2_orders`
* `store_v2_transactions`
operationId: voidOrderPayment
parameters:
- $ref: '#/components/parameters/ContentType'
responses:
'201':
$ref: '#/components/responses/201_Created'
'400':
$ref: '#/components/responses/400_BadRequest'
'404':
$ref: '#/components/responses/404_NotFound'
'422':
$ref: '#/components/responses/422_UnprocessableEntity'
'502':
$ref: '#/components/responses/502_GatewayError'
'503':
$ref: '#/components/responses/503_ServiceUnavailable'
'504':
$ref: '#/components/responses/504_GatewayTimeout'
tags:
- Payment Actions
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/OrderIdParam'
/orders/{order_id}/transactions:
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/OrderIdParam'
get:
tags:
- Transactions
description: >-
Returns an **orderʼs** transactions.
**Usage Notes**
* Depending on the payment method, different information will be
available (not all payment gateways return full card or fraud detail).
Requires at least one of the following scopes:
* `store_v2_transactions_read_only`
* `store_v2_transactions`
operationId: getOrderTransactions
responses:
'200':
$ref: '#/components/responses/TransactionCollection_Resp'
'204':
description: |
No content found to fulfill request.
content:
application/json:
schema:
description: No-content response for the BigCommerce API.
type: object
properties:
status:
description: |
204 HTTP status code.
type: integer
title:
description: The error title describing the situation.
type: string
type:
type: string
instance:
type: string
title: No Content
'404':
description: |
The resource was not found.
content:
application/json:
schema:
description: Error payload for the BigCommerce API.
type: object
properties:
status:
description: |
404 HTTP status code.
type: integer
title:
description: The error title describing the particular error.
type: string
type:
type: string
instance:
type: string
title: Not Found
summary: BigCommerce Get Transactions
/orders/{order_id}/payment_actions/refund_quotes:
post:
summary: BigCommerce Create a Refund Quote
description: >-
Calculate the tax amount, total refund amount and get available payment
options for an order refund by providing items and costs or quantities
to refund.
Requires at least one of the following scopes:
* `store_v2_orders`
* `store_v2_transactions`
**Note:**
Order refunds are processed consecutively. Processing synchronous
refunds on an order are not yet supported.
operationId: createOrderRefundQuotes
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RefundQuote_Post'
application/xml:
schema:
type: object
properties: {}
multipart/form-data:
schema:
type: object
properties: {}
required: true
x-examples:
Quantity:
items:
- item_id: 75
item_type: PRODUCT
quantity: 1
Amount:
items:
- item_id: 79
item_type: SHIPPING
amount: 10
Tax Exempt (Order Level):
items:
- item_type: ORDER
item_id: 1234
amount: 1
reason: Overcharged $1.00
Multiple Items:
items:
- item_id: 75
item_type: PRODUCT
quantity: 1
- item_id: 79
item_type: SHIPPING
amount: 10
description: ''
responses:
'201':
$ref: '#/components/responses/RefundQuote_Resp'
'422':
$ref: '#/components/responses/422_UnprocessableEntity'
tags:
- Payment Actions
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/OrderIdParam'
/orders/{order_id}/payment_actions/refunds:
post:
summary: BigCommerce Create a Refund
description: >-
Creates a refund. When there are no payment method validation issues,
the refund process is successful and the refund payment request is
scheduled. The payment request itself occurs asynchronously.
Requires at least one of the following scopes:
* `store_v2_orders`
* `store_v2_transactions`
**Note:**
Order refunds are processed consecutively. Processing synchronous
refunds on an order are not yet supported.
operationId: createOrderRefund
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RefundRequest_Post'
required: true
x-examples:
Quantity:
items:
- item_type: PRODUCT
item_id: 31
amount: 35
quantity: 1
reason: Not the right product.
payments:
- provider_id: storecredit
amount: 37.89
offline: false
merchant_calculated_override:
- total_amount: 45
total_tax:
Tax Exempt (Order Level):
order_id: 1234
items:
- item_type: ORDER
item_id: 1234
amount: 1
reason: overcharged
payments:
- provider_id: authorizenet
provider_description: Authorize.net
amount: 1
offline: false
Multiple Items:
items:
- item_id: 75
item_type: PRODUCT
quantity: 1
- item_id: 79
item_type: SHIPPING
amount: 10
tax_adjustment_amount: 0
payments:
- provider_id: storecredit
amount: 232.75
offline: false
Merchant Calculated Override:
order_id: 1234
items:
- item_type: ORDER
item_id: 1234
amount: 10
reason: overcharged
merchant_calculated_override:
total_amount: 10
tax_amount: 0
payments:
- provider_id: authorizenet
provider_description: Authorize.net
amount: 10
offline: false
responses:
'201':
$ref: '#/components/responses/Refund_Resp'
'422':
description: |
Unable to process a guest refund with store credit.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
data:
- status: 422
title: Unable to provide store credit for a guest customer.
type: >-
https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
'503':
description: Service Unavailable
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/FailedQuoteError'
meta:
$ref: '#/components/schemas/Meta'
examples:
response:
value:
data:
- order_id: 1
status: 503
error: Tax service gone away
meta: {}
tags:
- Payment Actions
get:
summary: BigCommerce Get Refunds for Order
description: >-
Returns a list of refunds ordered by refund ID in ascending order for
the given order.
Requires at least one of the following scopes:
* `store_v2_transactions_read_only`
* `store_v2_transactions`
* `store_v2_orders_read_only`
* `store_v2_orders`
operationId: getOrderRefunds
responses:
'200':
$ref: '#/components/responses/RefundCollection_Resp'
tags:
- Payment Actions
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/OrderIdParam'
/orders/payment_actions/refunds/{refund_id}:
parameters:
- $ref: '#/components/parameters/Accept'
- name: refund_id
in: path
description: Refund ID.
required: true
schema:
type: integer
get:
summary: BigCommerce Get a Refund
description: Returns a refund by refund ID.
operationId: getOrderRefund
responses:
'200':
$ref: '#/components/responses/RefundID_Response'
tags:
- Payment Actions
/orders/payment_actions/refunds:
parameters:
- $ref: '#/components/parameters/Accept'
get:
summary: BigCommerce Get All Refunds
description: |-
Returns a list of refunds ordered by refund ID in ascending order.
Requires at least one of the following scopes:
* `store_v2_transactions_read_only`
* `store_v2_transactions`
* `store_v2_orders_read_only`
* `store_v2_orders`
operationId: getOrdersRefunds
tags:
- Payment Actions
parameters:
- name: order_id:in
in: query
description: Filter by `order_id`. Accepts multiple as comma-separated values.
style: form
explode: false
schema:
type: array
items:
type: integer
- name: id:in
in: query
description: Filter by refund `id`. Accepts multiple as comma-separated values.
style: form
explode: false
schema:
type: array
items:
type: integer
- in: query
name: created:min
description: |-
Filter results so they are later than or equal to provided date.
Must be in url-encoded RFC 3339 format.
e.g. `2020-01-15T01:02:34-01:00` is RFC 3339 format.
Url-encoded this will be `2020-01-15T01%3A02%3A34%2B01%3A00`
schema:
type: string
format: date-time
- in: query
name: created:max
description: |-
Filter results so they are earlier than or equal to provided date.
Must be in url-encoded RFC 3339 format.
e.g. `2020-01-15T01:02:34-01:00` is RFC 3339 format.
Url-encoded this will be `2020-01-15T01%3A02%3A34%2B01%3A00`
schema:
type: string
format: date-time
- in: query
name: page
description: Specifies the page number in a limited (paginated) list of items.
schema:
type: integer
- in: query
name: limit
description: >-
Controls the number of items per page in a limited (paginated) list
of items.
schema:
type: integer
responses:
'200':
$ref: '#/components/responses/RefundCollection_Resp'
/orders/payment_actions/refund_quotes:
post:
summary: BigCommerce Create Refund Quotes - BATCH
description: >-
Calculate the tax amount, total refund amount and get available payment
options for an order refund by providing items and costs or quantities
to refund.
This endpoint will accept a batch of one or more.
Requires at least one of the following scopes:
* `store_v2_orders`
* `store_v2_transactions`
operationId: createOrdersRefundQuotes
parameters:
- $ref: '#/components/parameters/Accept'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PostRefundQuotesRequest'
required: true
x-examples:
application/json:
- items:
- item_id: 76
item_type: PRODUCT
quantity: 1
tax_adjustment_amount: 0
responses:
'201':
$ref: '#/components/responses/RefundQuotesBATCH_Resp'
'422':
description: >-
Partial success/failure response. Status to roll up to the most
severe individual failure to the whole request.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/RefundQuote_Full'
errors:
type: array
items:
$ref: '#/components/schemas/FailedQuoteError'
meta:
$ref: '#/components/schemas/Meta'
Example 1:
examples:
response:
value:
data:
- order_id: 1
total_refund_amount: 1.99
total_refund_tax_amount: 1.95
rounding: 1
adjustment: 0.05
tax_inclusive: true
refund_methods:
- ''
errors:
- order_id: 1
status: 422
error: Refund amount is greater than remaining amount
meta:
failure: 1
success: 1
total: 2
'503':
description: >-
Every request in the batch failed. The error object describes the
failure for each component request.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/RefundQuote_Full'
errors:
type: array
items:
$ref: '#/components/schemas/FailedQuoteError'
meta:
$ref: '#/components/schemas/Meta'
examples:
response:
value:
data: []
errors:
- order_id: 1
status: 503
error: Tax service could not be contacted
- order_id: 100
status: 422
error: Refund amount exceeds remaining amount
meta:
failure: 2
success: 0
total: 2
tags:
- Payment Actions
x-private: true
/orders/{order_id}/metafields:
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/OrderIdParam'
get:
summary: BigCommerce Get Order Metafields
tags:
- Metafields
description: >
Gets a `Metafield` object list, by `order_id`.
The maximum number of metafields allowed on each order, product,
category, variant, or brand is 250 per client ID.
operationId: getOrderMetafields
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
- $ref: '#/components/parameters/MetafieldKeyParam'
- $ref: '#/components/parameters/MetafieldNamespaceParam'
- $ref: '#/components/parameters/DirectionParam'
responses:
'200':
description: |
An array of metafields and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/MetaFieldCollectionResponse'
examples: {}
'404':
description: |
The resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
example-1:
value:
status: 404
title: There was no order found with ID 1010
type: >-
https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
post:
summary: BigCommerce Create Metafields
tags:
- Metafields
description: >-
Creates an order `Metafield`.
The maximum number of metafields allowed on each order, product,
category, variant, or brand is 250 per client ID.
operationId: createOrderMetafield
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MetafieldBase_Post'
examples: {}
description: |
A `Metafield` object.
required: true
responses:
'200':
description: |
A `Metafield` object.
content:
application/json:
schema:
$ref: '#/components/schemas/MetafieldResponse'
'409':
description: >
The `Metafield` conflicts with another `Metafield`. This can result
from duplicate unique key combinations of the appʼs client id,
namespace, key, resource_type, and resource_id.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: >
The `Metafield` is not valid. This is the result of missing required
fields or of invalid data. See the response for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/orders/{order_id}/metafields/{metafield_id}:
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/OrderIdParam'
- name: metafield_id
in: path
description: |
The ID of the `Metafield`.
required: true
schema:
type: integer
get:
summary: BigCommerce Get a Metafield
tags:
- Metafields
description: |
Gets a `Metafield`, by `order_id`.
operationId: getOrderMetafield
responses:
'200':
description: |
A `Metafield` object.
content:
application/json:
schema:
$ref: '#/components/schemas/MetafieldResponse'
'404':
description: |
The resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
put:
summary: BigCommerce Update a Metafield
tags:
- Metafields
description: >-
Updates a `Metafield` object.
The maxiumum number of metafields allowed on each order, product,
category, variant, or brand is 250 per client ID.
operationId: updateOrderMetafield
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MetafieldPut'
description: |
A `Metafield` object.
required: true
responses:
'200':
description: |
A metafield and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/MetafieldResponse'
'404':
description: |
The resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
delete:
summary: BigCommerce Delete a Metafield
tags:
- Metafields
description: |
Deletes a `Metafield`.
operationId: deleteOrderMetafield
responses:
'204':
description: |
An empty response.
/orders/settings:
get:
summary: BigCommerce Get Global Order Settings
description: Returns global order settings.
operationId: getGlobalOrderSettings
tags:
- Order Settings
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/GlobalOrderSettings'
- type: object
properties:
meta:
$ref: '#/components/schemas/metaEmpty_Full'
examples: {}
'400':
description: Bad request. Authentication Required.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse400'
put:
summary: BigCommerce Update Global Order Settings
description: Updates global order settings.
operationId: updateGlobalOrderSettings
parameters:
- $ref: '#/components/parameters/ContentType'
tags:
- Order Settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalOrderSettings'
examples:
EnableMultipleOrderNotifications:
$ref: '#/components/examples/EnableMultipleOrderNotifications'
DisableOrderPlacedNotificatons:
$ref: >-
#/components/examples/GlobalOrderSettingsDisableOrderPlacedNotificatons
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- type: object
- $ref: '#/components/schemas/GlobalOrderSettings'
- properties:
meta:
$ref: '#/components/schemas/metaEmpty_Full'
'400':
description: Bad request. Authentication Required.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse400'
'422':
description: >-
Order settings data is not valid. This is the result of missing
required fields, or of invalid data. See the response for more
details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse422'
parameters:
- $ref: '#/components/parameters/Accept'
/orders/settings/channels/{channel_id}:
get:
summary: BigCommerce Get Channel Order Settings
description: Returns order settings for a specific channel.
operationId: getChannelOrderSettings
tags:
- Order Settings
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ChannelOrderSettings'
- type: object
properties:
meta:
$ref: '#/components/schemas/metaEmpty_Full'
examples: {}
'400':
description: Bad request. Authentication Required.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse400'
put:
summary: BigCommerce Update Channel Order Settings
description: |-
Updates order settings for a specific channel.
**Note:** You must override both notifications `email_addresses` or neither, i.e. either both notification `email_addresses` are an array of valid email addresses, or both `email_addresses` must be null. You may not have one set to an array of addresses and the other set to `null`.
operationId: updateChannelOrderSettings
parameters:
- $ref: '#/components/parameters/ContentType'
tags:
- Order Settings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChannelOrderSettings'
examples:
OverrideOrderPlacedEmailAddressesAndDisableForwardEmailAddresses:
$ref: >-
#/components/examples/ChannelOrderSettingsOverrideOrderPlacedEmailAddressesAndDisableForwardEmail
ResetChannelSettings:
$ref: '#/components/examples/ChannelOrderSettingsReset'
DisableMultipleNotificatonsForChannels:
$ref: >-
#/components/examples/ChannelOrderSettingsDisableBothNotifications
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ChannelOrderSettings'
- type: object
properties:
meta:
$ref: '#/components/schemas/metaEmpty_Full'
'400':
description: Bad request. Authentication Required.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse400'
'422':
description: >-
Order settings data is not valid. This is the result of missing
required fields, or of invalid data. See the response for more
details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse422'
parameters:
- $ref: '#/components/parameters/Accept'
- name: channel_id
in: path
schema:
type: string
description: Channel ID
required: true
/orders/metafields:
get:
summary: BigCommerce Get All Order Metafields
tags:
- Batch Metafields
description: Get all order metafields.
operationId: getOrdersMetafields
responses:
'200':
description: |
List of `Metafield` objects.
content:
application/json:
schema:
$ref: '#/components/schemas/MetaFieldCollectionResponse'
'500':
description: Internal Server Error
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
- $ref: '#/components/parameters/MetafieldKeyParam'
- $ref: '#/components/parameters/MetafieldKeyInParam'
- $ref: '#/components/parameters/MetafieldNamespaceParam'
- $ref: '#/components/parameters/MetafieldNamespaceInParam'
- $ref: '#/components/parameters/DirectionParam'
post:
summary: BigCommerce Create multiple Metafields
tags:
- Batch Metafields
description: Create multiple metafields.
operationId: createOrdersMetafields
requestBody:
content:
application/json:
schema:
type: array
items:
allOf:
- $ref: '#/components/schemas/MetafieldBase_Post'
- type: object
properties:
resource_id:
type: integer
example: 42
description: >
The ID for the order with which the metafield is
associated.
required:
- resource_id
description: ''
responses:
'200':
description: |
List of created `Metafield` objects.
content:
application/json:
schema:
$ref: '#/components/schemas/MetaFieldCollectionResponse_POST_PUT'
'422':
description: |
Response object for metafields creation with partial success.
content:
application/json:
schema:
$ref: >-
#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT
'500':
description: Internal Server Error
put
# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/orders-openapi-original.yml