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: support@bigcommerce.com 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: summary: BigCommerce Update multiple Metafields tags: - Batch Metafields description: Create multiple metafields. operationId: updateOrdersMetafields requestBody: content: application/json: schema: type: array items: allOf: - $ref: '#/components/schemas/MetafieldBase_Post' - type: object properties: id: type: integer example: 42 description: | The ID of metafield to update. required: - id description: '' responses: '200': description: | List of updated `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 delete: summary: BigCommerce Delete All Metafields tags: - Batch Metafields description: Delete all order metafields. operationId: deleteOrdersMetafields requestBody: content: application/json: schema: type: array items: type: integer description: List of metafield IDs. responses: '200': description: | Response object for metafields deletion with success. content: application/json: schema: $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess' '422': description: | Response object for metafields deletion with partial success. content: application/json: schema: $ref: >- #/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE components: schemas: GetReturnsSettings: type: object properties: reasons: type: array items: $ref: '#/components/schemas/Reason' preferred_outcomes: type: array items: $ref: '#/components/schemas/PreferredOutcome' x-internal: false Reason: type: object properties: id: type: integer format: int64 label: type: string description: A description of the reason. is_archived: type: boolean description: Indicates whether or not the reason has been archived. x-internal: false PreferredOutcome: type: object properties: id: type: integer format: int64 label: type: string description: A description of the outcome. is_archived: type: boolean description: Indicates whether or not the outcome has been archived. x-internal: false CreateReturnRequest: type: object required: - items properties: items: description: A collection of items to be returned. type: array items: $ref: '#/components/schemas/CreateReturnRequestItem' comment: description: A comment provided to the merchant for review. type: string title: CreateReturnRequest x-internal: false CreateReturnRequestItem: type: object required: - reference_id - quantity - preferred_outcome_id - reason_id properties: reference_id: $ref: '#/components/schemas/ItemReferenceId' quantity: type: integer minimum: 1 preferred_outcome_id: type: integer format: int64 reason_id: type: integer format: int64 x-internal: false CreateReturn: $ref: '#/components/schemas/Return_Full' Return_Full: type: object description: A view of a return. properties: items: type: array items: $ref: '#/components/schemas/ReturnItem' total: type: string format: decimal description: The total price of the items being returned. currency: type: string format: iso-4217 description: The transactional currency of the return and the associated order. customer: type: object properties: id: type: integer format: int64 email: type: string format: email comment: type: string description: A comment provided to the merchant for review. status: $ref: '#/components/schemas/Status_Full' date_modified: type: string format: date-time x-internal: false ReturnItem: type: object description: A view of a returned item. properties: id: type: integer format: int64 description: The unique identifier of this returned item. reference_id: $ref: '#/components/schemas/ItemReferenceId' quantity: type: integer description: The quantity of items for which a return was requested. total: type: string format: decimal description: The total price of the line item. preferred_outcome: type: object properties: id: type: integer format: int64 description: Unique identifier of the preferred outcome. label: type: string description: A displayable label for the preferred outcome. reason: type: object properties: id: type: integer format: int64 description: Unique identifier of the reason. label: type: string description: A displayable label for the reason. received_state: type: object properties: received_quantity: type: integer description: The quantity of items marked as received by the merchant. pending_quantity: type: integer description: The quantity of items pending receipt by the merchant. review_state: type: object properties: approved_quantity: type: integer description: The quantity of items approved for return by the merchant. pending_quantity: type: integer description: The quantity of items pending receipt by the merchant. rejected_quantity: type: integer description: The quantity of items rejected by the merchant. x-internal: false StatusUpdate_Full: type: object properties: return_id: type: integer format: int64 description: The ID of the return for which the status should be updated. new_status: $ref: '#/components/schemas/Status_Full' title: StatusUpdate_Full x-internal: false Status_Full: type: string enum: - CLOSED - OPEN - REMOVED description: The status of the return. title: Status_Full x-internal: false UpdateReturnStatusesRequest: type: array items: $ref: '#/components/schemas/StatusUpdate_Full' title: UpdateReturnStatusesRequest x-internal: false UpdateReturnStatuses: type: array items: type: object properties: id: type: integer format: int64 description: The ID of the return for which the status was updated. status: $ref: '#/components/schemas/Status_Full' x-internal: false Problem: type: object properties: status: type: integer description: Status code of the problem. title: type: string description: A short description of the problem. type: type: string format: url description: A resource describing the problem. x-internal: false BatchOperationMeta: type: object properties: total: type: integer description: The total number of operations in the batch. success: type: integer description: The number of failed operations in the batch. failed: type: integer description: The number of failed operations in the batch. x-internal: false Pagination: type: object description: Data about the response, including pagination and collection totals. title: Pagination properties: total: type: integer description: | Total number of items in the result set. example: 36 count: type: integer description: | Total number of items in the collection response. example: 36 per_page: type: integer description: > The amount of items returned in the collection per page, controlled by the limit parameter. example: 50 current_page: type: integer description: | The page you are currently on within the collection. example: 1 total_pages: type: integer description: | The total number of pages in the collection. example: 1 links: type: object description: > Pagination links for the previous and next parts of the whole collection. properties: previous: type: string description: | Link to the previous page returned in the response. current: type: string description: | Link to the current page returned in the response. example: '?page=1&limit=50' next: type: string description: | Link to the next page returned in the response. x-internal: false ReceivedItems_Put: type: array items: type: object required: - item_id - received_quantity - pending_quantity properties: item_id: type: integer format: int64 description: The item ID for updating the received state. received_quantity: type: integer description: The quantity of items to be marked as received. pending_quantity: type: integer description: The quantity of items to be marked as pending. title: ReceivedItems_Put x-internal: false ReceivedItems_Base: type: array items: type: object properties: item_id: type: integer format: int64 description: The ID of the item for which received item status was updated. received_quantity: type: integer format: int64 description: The quantity of items marked as received. pending_quantity: type: integer format: int64 description: The quantity of items marked as pending. title: ReceivedItems_Base x-internal: false ReviewedItems_Put: type: array items: type: object required: - item_id - authorized_quantity - rejected_quantity - pending_quantity properties: item_id: type: integer format: int64 description: The item ID for updating the reviewed state. authorized_quantity: type: integer description: The quantity of items to be marked as authorized. rejected_quantity: type: integer description: The quantity of items to be marked as rejected. pending_quantity: type: integer description: The quantity of items to be marked as pending. title: ReviewedItems_Put x-internal: false ReviewedItems_Base: type: array items: type: object properties: item_id: type: integer format: int64 description: The ID of the item for which reviewed status was updated. authorized_quantity: type: integer format: int64 description: The quantity of items marked as authorized. rejected_quantity: type: integer format: int64 description: The quantity of items marked as rejected. pending_quantity: type: integer format: int64 description: The quantity of items marked as pending. title: ReviewedItems_Base x-internal: false GetReturnableItems: type: array items: type: object properties: reference_id: $ref: '#/components/schemas/ItemReferenceId' name: type: string description: The name of the order product. returnable_quantity: type: integer description: >- The maximum quantity of this item that can presently be requested for return. total: type: string format: decimal description: The total price of this line item. options: type: array items: type: object properties: display_name: type: string description: A displayable name for the option. display_value: type: string description: A displayable value for the option. description: An item available for return. description: A collection of options configured for the order product. x-internal: false ItemReferenceId: type: object properties: type: type: string description: The reference type. enum: - ORDER_PRODUCT value: type: string description: The value identifying the returned item. required: - type - value x-internal: false CollectionMeta: type: object description: Data about the response, including pagination and collection totals. properties: pagination: type: object description: Data about the response, including pagination and collection totals. title: Pagination properties: total: type: integer description: | Total number of items in the result set. example: 36 count: type: integer description: | Total number of items in the collection response. example: 36 per_page: type: integer description: > The amount of items returned in the collection per page, controlled by the limit parameter. example: 50 current_page: type: integer description: | The page you are currently on within the collection. example: 1 total_pages: type: integer description: | The total number of pages in the collection. example: 1 links: type: object description: > Pagination links for the previous and next parts of the whole collection. properties: previous: type: string description: | Link to the previous page returned in the response. current: type: string description: | Link to the current page returned in the response. example: '?page=1&limit=50' next: type: string description: | Link to the next page returned in the response. title: Collection Meta x-internal: false Meta: type: object title: Meta properties: meta: type: object description: Data about the response, including pagination and collection totals. title: Pagination properties: total: type: integer description: | Total number of items in the result set. example: 36 count: type: integer description: | Total number of items in the collection response. example: 36 per_page: type: integer description: > The amount of items returned in the collection per page, controlled by the limit parameter. example: 50 current_page: type: integer description: | The page you are currently on within the collection. example: 1 total_pages: type: integer description: | The total number of pages in the collection. example: 1 links: type: object description: > Pagination links for the previous and next parts of the whole collection. properties: previous: type: string description: | Link to the previous page returned in the response. current: type: string description: | Link to the current page returned in the response. example: '?page=1&limit=50' next: type: string description: | Link to the next page returned in the response. x-internal: false ErrorResponse: allOf: - $ref: '#/components/schemas/error_Base' - type: object properties: errors: type: object properties: {} additionalProperties: true title: DetailedErrors title: ErrorResponse x-internal: false DetailedErrors: type: object properties: {} additionalProperties: true title: DetailedErrors x-internal: false Transaction_Post: type: object title: Transaction_Post properties: event: type: string description: | Store event that created the transaction. enum: - purchase - authorization - capture - refund - void - pending - settled method: type: string description: > The payment method: `credit_card` - a credit-card transaction; `electronic_wallet` - an online wallet; `store_credit` - a transaction using store credit; `gift_certificate` - a transaction using a gift certificate; `custom` - manual payment methods; `token` - payment token; `nonce` - temporary payment token; `offsite` - online payment off the site (e.g., PayPal); `offline` - payment method that takes place offline. enum: - credit_card - electronic_wallet - gift_certificate - store_credit - apple_pay_card - apple_pay_token - bigpay_token - token - custom - offsite - offline - nonce amount: type: number format: float description: | Amount of money in the transaction. currency: type: string format: ISO-4217 description: | Currency used for the transaction. gateway: type: string description: | The payment gateway, where applicable. enum: - 2checkout - adyen - amazon - authorizenet - bankdeposit - braintree - cheque - cod - custom - firstdatagge4 - giftcertificate - hps - instore - klarna - migs - moneyorder - nmi - paypalexpress - paypalpaymentsprous - paypalpaymentsprouk - plugnpay - qbmsv2 - securenet - square - storecredit - stripe - testgateway - usaepay gateway_transaction_id: description: > The transaction ID returned by the payment gateway for this transaction item. type: string date_created: description: | The date/time of the transaction. type: string format: date-time test: type: boolean description: > True if the transaction performed was a test, or if the gateway is in test mode. status: type: string description: | Status of the transaction. enum: - ok - error fraud_review: type: boolean description: | Result of gateway fraud review, if any. Default is `false`. reference_transaction_id: type: integer description: > Identifier for an existing transaction upon which this transaction acts. offline: $ref: '#/components/schemas/Offline' custom: $ref: '#/components/schemas/Custom' required: - event - method - amount - currency - gateway x-internal: false NotFound: 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 x-internal: false Transaction: allOf: - title: Transaction Base properties: event: type: string description: | Store event that created the transaction. enum: - purchase - authorization - capture - refund - void - pending - settled method: type: string description: > The payment method: `credit_card` - a credit-card transaction; `electronic_wallet` - an online wallet; `store_credit` - a transaction using store credit; `gift_certificate` - a transaction using a gift certificate; `custom` - manual payment methods; `token` - payment token; `nonce` - temporary payment token; `offsite` - online payment off the site; `offline` - payment method that takes place offline. enum: - credit_card - electronic_wallet - gift_certificate - store_credit - apple_pay_card - bigpay_token - apple_pay_token - token - custom - offsite - offline - nonce amount: type: number format: float description: | Amount of money in the transaction. currency: type: string format: ISO-4217 description: | Currency used for the transaction. gateway: type: string description: | The payment gateway, where applicable. enum: - 2checkout - adyen - amazon - authorizenet - bankdeposit - braintree - cheque - cod - custom - firstdatagge4 - giftcertificate - hps - instore - klarna - migs - moneyorder - nmi - paypalexpress - paypalpaymentsprous - paypalpaymentsprouk - plugnpay - qbmsv2 - securenet - square - storecredit - stripe - testgateway - usaepay gateway_transaction_id: description: > The transaction ID returned by the payment gateway for this transaction item. type: string date_created: description: | The date/time of the transaction. type: string format: date-time test: type: boolean description: > True if the transaction performed was a test, or if the gateway is in test mode. status: type: string description: | Status of the transaction. enum: - ok - error fraud_review: type: boolean description: | Result of gateway fraud review, if any. Default is `false`. reference_transaction_id: type: integer description: > Identifier for an existing transaction upon which this transaction acts. offline: type: object description: Offline payment (e.g., check or purchase order). title: Offline properties: display_name: description: | Display name for the offline payment. type: string custom: type: object description: Custom payment from manual order. title: Custom properties: payment_method: description: | Text entered for the payment method in the control panel. type: string payment_method_id: type: string description: | The payment method ID used for this transaction. required: - event - method - amount - currency - gateway - properties: id: type: integer description: | Unique identifier for the transaction. order_id: type: string description: > Identifier for the BigCommerce Order with which this transaction is associated. date_created: description: | The date/time of the transaction. type: string format: date-time payment_instrument_token: type: string description: >- This field contains internal BigPay token for stored card that is then mapped to the actual third-party token. We currently do not offer a way to get third party tokens.These tokens are read-only and do not return any information about the payment. avs_result: description: >- Address Verification Service (AVS) result from the payment gateway. type: object title: AVS Results properties: code: description: AVS code. type: string message: description: AVS message. type: string street_match: description: AVS Code for street matching result. type: string postal_match: description: AVS Code for postal matching result. type: string cvv_result: description: Card Verification Value result from the payment gateway. type: object title: CVV Result properties: code: description: CVV code. type: string message: description: CVV message. type: string credit_card: $ref: '#/components/schemas/CreditCard' gift_certificate: type: object description: A gift-certificate model. title: Gift Certificate properties: code: description: | The gift-certificate code. type: string example: MB345 original_balance: type: number description: | The balance on a gift certificate when it was purchased. format: float example: 100 minimum: 0 maximum: 21474836.47 starting_balance: description: > The balance on a gift certificate at the time of this purchase. type: number format: float example: 100 remaining_balance: description: | The remaining balance on a gift certificate. type: number format: float example: 35.42 status: description: > The status of a gift certificate: `active` - gift certificate is active; `pending` - gift certificate purchase is pending; `disabled` - gift certificate is disabled; `expired` - gift certificate is expired. type: string enum: - active - pending - disabled - expired store_credit: type: object description: | A store credit model. properties: remaining_balance: description: | Remaining balance of shopperʼs store credit. type: number format: float example: 35.42 type: object title: '' x-examples: Example 1: event: purchase method: credit_card amount: 3.4 currency: string gateway: 2checkout gateway_transaction_id: string date_created: '2019-08-24T14:15:22Z' test: true status: ok fraud_review: true reference_transaction_id: 0 offline: display_name: string custom: payment_method: string payment_method_id: string id: 0 order_id: string payment_instrument_token: string avs_result: code: string message: string street_match: string postal_match: string cvv_result: code: string message: string credit_card: card_type: alelo card_iin: string card_last4: string card_expiry_month: 1 card_expiry_year: 0 gift_certificate: code: MB345 original_balance: 100 starting_balance: 100 remaining_balance: 35.42 status: active store_credit: remaining_balance: 35.42 description: '' CreditCard: type: object description: A credit-card model. title: Credit Card properties: card_type: type: string enum: - alelo - alia - american_express - cabal - carnet - dankort - diners_club - discover - elo - forbrugsforeningen - jcb - maestro - master - naranja - sodexo - unionpay - visa - vr description: >- **Allowed values**: alelo, alia, american_express, cabal, carnet, dankort, diners_club, discover, elo, forbrugsforeningen, jcb, maestro, master, naranja, sodexo, unionpay, visa, vr card_iin: description: | The IIN of a credit-card number. type: string card_last4: description: | The last 4 digits of a credit-card number. type: string card_expiry_month: description: | The expiry month of a credit-card. type: integer minimum: 1 maximum: 12 card_expiry_year: description: | The expiry year of a credit-card. type: integer x-internal: false StoreCredit: type: object description: | A store credit model. properties: remaining_balance: description: | Remaining balance of shopperʼs store credit. type: number format: float example: 35.42 x-internal: false Custom: type: object description: Custom payment from manual order. properties: payment_method: description: | Text entered for the payment method in the control panel. type: string title: Custom x-internal: false Offline: type: object description: Offline payment (e.g., check or purchase order). properties: display_name: description: | Display name for the offline payment. type: string title: Offline x-internal: false GiftCertificate: type: object description: A gift-certificate model. title: Gift Certificate x-internal: false properties: code: description: | The gift-certificate code. type: string example: MB345 original_balance: type: number description: | The balance on a gift certificate when it was purchased. format: float example: 100 minimum: 0 maximum: 21474836.47 starting_balance: type: number description: | The balance on a gift certificate at the time of this purchase. format: float example: 100 minimum: 0 remaining_balance: description: | The remaining balance on a gift certificate. type: number format: float example: 35.42 status: description: > The status of a gift certificate: `active` - gift certificate is active; `pending` - gift certificate purchase is pending; `disabled` - gift certificate is disabled; `expired` - gift certificate is expired. type: string enum: - active - pending - disabled - expired AVSResult: description: Address Verification Service (AVS) result from the payment gateway. type: object properties: code: description: AVS code. type: string message: description: AVS message. type: string street_match: description: AVS Code for street matching result. type: string postal_match: description: AVS Code for postal matching result. type: string title: AVS Results x-internal: false CVVResult: description: Card Verification Value result from the payment gateway. type: object properties: code: description: CVV code. type: string message: description: CVV message. type: string title: CVV Result x-internal: false NoContent: 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 x-internal: false metaEmpty_Full: type: object title: Response meta properties: {} additionalProperties: true description: Response metadata. pagination_Full: type: object title: pagination_Full properties: total: description: Total number of items in the result set. type: integer format: int32 count: description: Total number of items in the collection response. type: integer format: int32 per_page: description: >- The amount of items returned in the collection per page, controlled by the limit parameter. type: integer format: int32 current_page: description: The page you are currently on within the collection. type: integer format: int32 total_pages: description: The total number of pages in the collection. type: integer format: int32 links: $ref: '#/components/schemas/links_Full' x-internal: false metaCollection_Full: type: object title: metaCollection_Full properties: pagination: $ref: '#/components/schemas/pagination_Full' x-internal: false x-examples: example-1: pagination: total: 0 count: 0 per_page: 0 current_page: 0 total_pages: 0 links: previous: string current: '?page=1&limit=50' next: string links_Full: type: object properties: previous: type: string description: | Link to the previous page returned in the response. current: type: string description: | Link to the current page returned in the response. example: '?page=1&limit=50' next: type: string description: | Link to the next page returned in the response. title: links_Full x-internal: false error_Base: type: object title: error_Base properties: status: description: | The HTTP status code. type: integer title: description: | The error title describing the particular error. type: string type: type: string description: Error payload for the BigCommerce API. x-internal: false errorDetailed_Full: type: object properties: errors: type: object properties: {} additionalProperties: true title: DetailedErrors title: errorDetailed_Full x-internal: false PostRefundQuotesRequest: type: array description: Request body for batch refund quotes. title: Refund Quotes Request - BATCH items: $ref: '#/components/schemas/RefundQuote_Post' x-internal: false RefundQuote_Post: type: object title: RefundQuote_Post description: Request body for refund quotes. x-internal: false x-examples: {} properties: items: type: array items: $ref: '#/components/schemas/ItemsRefund' required: - items RefundQuote_Full: type: object title: RefundQuote_Full x-internal: false properties: order_id: type: integer description: ID of the order to be refunded. total_refund_amount: $ref: '#/components/schemas/Amount' total_refund_tax_amount: type: number example: 1.95 rounding: type: number description: >- Indicates rounding value to bring `refund_total` to an amount refundable with payment providers (in this case to 2 decimal places). adjustment: $ref: '#/components/schemas/AdjustmentAmount' tax_inclusive: type: boolean description: Indicate if `total_refund_amount` includes tax amount. refund_methods: type: array description: > An array of available refund methods. Note that `refund_methods` is an array of refund methods, with each refund method being an array of payment options. For example, if the order was placed by a combination of store credit and bank deposit the refund methods would be: ```json { "refund_methods": [ [ { "provider_id": "storecredit", "provider_description": "Store Credit", "amount": 119.35, "offline": false, "offline_provider": false, "offline_reason": "" } ], [ { "provider_id": "custom", "provider_description": "Custom", "amount": 119.35, "offline": true, "offline_provider": true, "offline_reason": "This is an offline payment provider." } ], [ { "provider_id": "bankdeposit", "provider_description": "Bank Deposit", "amount": 80.35, "offline": true, "offline_provider": true, "offline_reason": "This is an offline payment provider." }, { "provider_id": "storecredit", "provider_description": "Store Credit", "amount": 39, "offline": false, "offline_provider": false, "offline_reason": "" } ] ] } ``` In this case there are three refund methods available to the merchant: 1. Refund up to the entire order amount to store credit. 2. Mark an amount up to the full order amount as refunded externally, through a provider or means not represented directly in BC ("custom"). 3. Refund the amount paid by store credit to store credit, and the amount paid by bank deposit with a manual refund, which will be recorded as being refunded against the bank deposit. items: $ref: '#/components/schemas/RefundMethod' RefundRequest_Post: type: object description: Request body for refund requests. title: RefundRequest_Post x-internal: false properties: items: type: array items: $ref: '#/components/schemas/ItemsRefund' payments: type: array items: $ref: '#/components/schemas/PaymentRequest' merchant_calculated_override: $ref: '#/components/schemas/MerchantOverride' required: - items - payments x-examples: {} RefundID_Get: type: object x-examples: Example: data: id: 12 order_id: 180 user_id: 0 created: '2022-06-16T16:44:15+00:00' reason: Customer requires a refund. total_amount: 50 total_tax: 5 uses_merchant_override_values: false payments: - id: 13 provider_id: storecredit amount: 50 offline: true is_declined: false declined_message: '' items: - item_type: PRODUCT item_id: 87 quantity: 1 requested_amount: meta: {} properties: data: type: object properties: id: type: integer description: | Refund ID for the returned refund. order_id: type: integer description: Order ID associated with the refund. user_id: type: integer description: > Reference to the user ID who created the refund. This is automatically populated by BigCommerce. created: type: string description: | Timestamp of when the refund was created. format: date-time reason: type: string description: | Reason for refund. total_amount: type: number description: > A non-negative 2 decimal place rounded value that represents the amount that can be refunded with the correct payment provider(s). example: 109.11 total_tax: type: number description: > Total tax amount refunded back to the shopper. This can be a negative amount indicating we have collected tax by refunding less to the customer. uses_merchant_override_values: type: boolean description: > Whether refund amount and tax are provided explicitly by merchant override. payments: type: array items: type: object properties: id: type: integer description: | Reference to refund payment ID. provider_id: type: string description: | Reference to payment provider. example: storecredit amount: type: number description: > A non-negative two decimal place rounded value represents the amount that can be charged/refunded with payment providers. example: 109.11 offline: type: boolean description: | Indicates whether the payment was offline. is_declined: type: boolean description: > Indicates if this payment has been declined by the payment provider. declined_message: type: string description: | Message indicates why the payment was declined. items: type: array items: type: object properties: item_type: type: string description: | Type of item that was refunded. enum: - PRODUCT - GIFT_WRAPPING - SHIPPING - HANDLING - ORDER item_id: type: integer description: > `order_product.id` corresponding to the item_types of PRODUCT, GIFT_WRAPPING. `order_address.id` corresponding to the item_types of SHIPPING, HANDLING. `order.id` corresponding to the item_type of ORDER. quantity: type: integer description: > Quantity of item refunded. Note: this will only be populated for item_type PRODUCT. requested_amount: type: string description: > A non-negative two decimal place rounded value that represents the amount that can be refunded with the payment provider(s). example: '109.11' nullable: true reason: type: string description: | Reason for refunding an item. meta: $ref: '#/components/schemas/metaEmpty_Full' PostRefundsRequest: type: array description: Request body for batch refunds. title: Refunds Request - BATCH items: $ref: '#/components/schemas/RefundRequest_Post' x-internal: false x-examples: {} FailedQuoteError: type: object description: Failed quote response. properties: order_id: type: integer status: type: integer description: HTTP status code. example: 422 error: type: string description: Details why the request failed. title: FailedQuoteError x-internal: false ItemsRefund: title: ItemsRefund x-internal: false oneOf: - $ref: '#/components/schemas/AmountBoundItem' - $ref: '#/components/schemas/QuantityBoundItem' - $ref: '#/components/schemas/TaxExemptItem' x-examples: {} PaymentRequest: type: object properties: provider_id: type: string description: Reference to payment provider. example: checkout_paypalexpress amount: type: number description: Amount refunded with this provider. example: 9.99 offline: type: boolean description: >- Whether the payment was marked as offline or performed through an online payment service. example: true title: Payment Request x-internal: false RefundMethod: type: array minItems: 1 items: $ref: '#/components/schemas/PaymentOption' title: Refund Method x-internal: false QuantityBoundItem: type: object title: Quantity Bound Item description: > Quantity Bound Item Type of refund item that capture refunding of items in the order that are of type quantity. * `ORDER` * `PRODUCT` * `GIFT_WRAPPING` * `SHIPPING` * `HANDLING` * `TAX` properties: item_type: type: string example: PRODUCT enum: - ORDER - PRODUCT - GIFT_WRAPPING - SHIPPING - HANDLING - TAX description: Type of refund. item_id: type: integer example: 1 description: Order Product ID. quantity: type: integer example: 3 reason: type: string example: Wrong size. description: Reason for refund. minLength: 0 maxLength: 1000 x-internal: false TaxExemptItem: type: object title: Tax Exempt (Order Level) description: >- Use this to refund a custom value at the order level. When `item_type` is set to `ORDER`, tax is not re-calculated. x-internal: false properties: item_type: type: string description: >- The type of refund. When `item_type` is set to `ORDER`, tax is not re-calculated. example: ORDER enum: - ORDER item_id: type: number description: Numeric ID of the product in the order. example: 1 amount: $ref: '#/components/schemas/Amount' reason: type: string description: Reason for the refund. minLength: 0 maxLength: 1000 AmountBoundItem: type: object title: Amount Bound Item description: >- Amount Bound Item Type of refund item that capture refunding of items in the order that are of type amount. * `PRODUCT` * `ORDER` * `GIFT_WRAPPING` * `SHIPPING` * `HANDLING` * `TAX` x-internal: false properties: item_type: type: string enum: - PRODUCT - ORDER - GIFT_WRAPPING - SHIPPING - HANDLING - TAX example: SHIPPING description: Type of refund. item_id: type: integer example: 1 description: Order address ID. amount: $ref: '#/components/schemas/Amount' quantity: type: integer example: 3 description: Number of items in refund. reason: type: string description: Explanation of refund. minLength: 0 maxLength: 1000 example: Customer requested refund MerchantOverride: type: object title: Merchant Calculated Override description: >- Merchant explicitly provided override based on their own calculation. This override gives merchants the flexibility to - bypass any tax correction due to tax rate/providers changes between when a customer places an order and a merchant initiates a refund - use explicit values calculated by external systems (e.g., merchants' own Extended Producer Responsibility or Order Management System) Note: when using the override, BC internal tax based refund calculation is skipped and therefore order/taxes records are not updated. properties: total_amount: $ref: '#/components/schemas/Amount' total_tax: type: number description: >- Total tax amount refunded back to the shopper. Use 0 value if there is no tax liability change for the refund or tax does not need to be recorded on the refund and would be handled externally. required: - total_amount - total_tax x-internal: false Refund: type: object title: Refund properties: id: type: integer description: Refund resource ID. readOnly: true order_id: type: integer description: Reference to order ID. user_id: type: integer description: >- Reference to the userʼs ID who create this refund. This is automatically populated by BigCommerce. readOnly: true created: type: string format: date-time description: Timestamp of when this refund was created. readOnly: true reason: type: string description: Reason for refund. total_amount: $ref: '#/components/schemas/Amount' total_tax: type: number description: >- Total tax amount refunded back to the shopper. Note: `order_level_amount` does not affect tax liability. This can be a negative amount indicating we have collected tax by refunding less to the customer. uses_merchant_override_values: type: boolean description: >- Whether refund amount and tax are provided explicitly by merchant override. items: type: array description: Array of items refunded. minItems: 1 items: $ref: '#/components/schemas/RefundItem' payments: type: array description: An array of refund payments made to payment providers. minItems: 1 items: $ref: '#/components/schemas/RefundPayment' x-internal: false RefundItem: type: object properties: item_type: type: string description: Type of item that was refunded. enum: - PRODUCT - GIFT_WRAPPING - SHIPPING - HANDLING - ORDER item_id: type: integer description: >- order_product.id corresponding to the item_types of PRODUCT, GIFT_WRAPPING. order_address.id corresponding to the item_types of SHIPPING, HANDLING. order.id corresponding to the item_type of ORDER. reason: type: string description: Reason for refunding an item. quantity: type: integer description: >- Quantity of item refunded. Note: this will only be populated for item_type PRODUCT requested_amount: $ref: '#/components/schemas/Amount' title: Refund Item x-internal: false RefundPayment: type: object title: Refund Payment properties: id: type: integer description: Reference to refund payment ID. readOnly: true provider_id: type: string description: Reference to payment provider. example: storecredit amount: $ref: '#/components/schemas/Amount' offline: type: boolean description: Indicate whether payment was offline. is_declined: type: boolean description: Indicate if this payment has been declined by payment provider. declined_message: type: string description: Message indicate why payment was declined. x-internal: false PaymentOption: type: object example: provider_id: checkout_paypalexpress provider_description: Paypal Express amount: 9.99 offline: true offline_provider: true offline_reason: Multiple online refunds are not available. title: Payment Option properties: provider_id: type: string description: Name of the payment method. example: checkout_paypalexpress provider_description: type: string description: Description for payment provider. example: Paypal Express amount: type: number description: Amount to be refunded with this payment provider. example: 9.99 offline: type: boolean description: >- Indicates the payment must be done offline due to constraints of the payment provider, such as partial refunds not being supported, or it being offline only such as cash on delivery of bank deposit. example: true offline_provider: type: boolean description: >- Indicates if the payment provider is a strictly offline provider, such as cash on delivery or bank deposit. example: true offline_reason: type: string description: Reason the payment option is offline only, if applicable. example: Multiple online refunds are not available x-internal: false Amount: type: number format: float description: >- A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded with payment providers. example: 1.99 title: Amount x-internal: false AdjustmentAmount: type: number format: float description: >- A negative or positive 2 decimal place rounded value that represents the difference between the refund amount requested in the refund quote and the actual amount that is refundable on the order. This value is negative when the refund amount requested in the refund quote is more than the total refundable amount. This value is positive when the total refundable amount has increased, e.g. as a result of rounding. example: -10.2 title: Adjustment Amount x-internal: false MetaRefund: type: object title: MetaRefund properties: failure: type: integer success: type: integer total: type: integer description: Describes refund failures, success and totals. x-internal: false x-examples: example-1: failure: 0 success: 0 total: 0 MetaFieldCollectionResponse: type: object description: | Response payload for the BigCommerce API. properties: data: type: array items: $ref: '#/components/schemas/Metafield' meta: $ref: '#/components/schemas/CollectionMeta' x-internal: false MetaFieldCollectionResponse_POST_PUT: type: object description: | Response payload for the BigCommerce API. properties: data: type: array items: $ref: '#/components/schemas/Metafield' errors: type: array description: Empty for 200 responses. example: [] meta: $ref: '#/components/schemas/CollectionMeta' x-internal: false MetafieldResponse: description: | Response payload for the BigCommerce API. x-internal: false x-examples: {} allOf: - type: object properties: data: $ref: '#/components/schemas/Metafield' - $ref: '#/components/schemas/Meta' MetafieldBase: type: object description: | Common Metafield properties. x-internal: false properties: permission_set: type: string description: > Determines the visibility and writeability of the field by other API consumers. |Value|Description | |:-|:-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| enum: - app_only - read - write - read_and_sf_access - write_and_sf_access namespace: type: string description: | Namespace for the metafield, for organizational purposes. example: Sales Department minLength: 1 maxLength: 64 key: type: string description: | The name of the field, for example: `location_id`, `color`. minLength: 1 maxLength: 64 example: Staff Name value: type: string description: | The value of the field, for example: `1`, `blue`. minLength: 1 maxLength: 65535 example: Ronaldo description: type: string description: | Description for the metafields. example: order minLength: 0 maxLength: 255 resource_type: type: string description: | The type of resource with which the metafield is associated. enum: - order - brand - product - variant - category example: order resource_id: type: integer description: > The unique identifier for the resource with which the metafield is associated. example: 0 readOnly: true required: - permission_set MetafieldBase_Post: type: object description: | Common Metafield properties. x-internal: false properties: permission_set: type: string description: > Determines the visibility and writeability of the field by other API consumers. |Value|Description | |:-|:-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| |`read_and_sf_access`|Visible to other API consumers, including on storefront| |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| enum: - app_only - read - write - read_and_sf_access - write_and_sf_access namespace: type: string description: | Namespace for the metafield, for organizational purposes. example: Sales Department minLength: 1 maxLength: 64 key: type: string description: | The name of the field, for example: `location_id`, `color`. minLength: 1 maxLength: 64 example: Staff Name value: type: string description: | The value of the field, for example: `1`, `blue`. minLength: 1 maxLength: 65535 example: Ronaldo description: type: string description: | Description for the metafields. minLength: 0 maxLength: 255 example: Name of Staff Member required: - permission_set - namespace - key - value Metafield: description: > Allows app partners to write custom data to various resources in the API. allOf: - $ref: '#/components/schemas/MetafieldBase' - type: object properties: id: type: integer description: | The unique identifier for the metafields. date_created: type: string format: date-time description: | Date and time of the metafieldʼs creation. example: '2022-06-16T18:39:00+00:00' date_modified: type: string format: date-time description: | Date and time when the metafield was last updated. example: '2022-06-16T18:39:00+00:00' owner_client_id: type: string description: Client ID for the metafieldʼs creator. example: asdfasdfasdfasdfasdfasdfasdf readOnly: true x-internal: false x-examples: {} MetafieldPut: description: | The model for a PUT to update metafield. allOf: - $ref: '#/components/schemas/MetafieldBase_Post' x-internal: false GlobalOrderSettings: type: object properties: notifications: type: object description: Global notification settings. properties: order_placed: description: Global order notification settings. type: object properties: email_addresses: description: >- Email addresses order notifications will be sent to. Empty array disables order notifications. Not nullable. type: array items: type: string forward_invoice: description: Global order invoice forward settings. type: object properties: email_addresses: description: >- Email addresses order invoices will be forwarded to. Empty array disables forwarding order invoices. Not nullable. type: array items: type: string example: $ref: '#/components/examples/EnableMultipleOrderNotifications/value' x-tags: - Models title: GlobalOrderSettings x-examples: example-1: $ref: '#/components/examples/EnableMultipleOrderNotifications/value' MetaFieldCollectionResponsePartialSuccess_POST_PUT: type: object description: | Response payload for the BigCommerce API. properties: data: type: array items: $ref: '#/components/schemas/Metafield' errors: type: array items: $ref: '#/components/schemas/Error' meta: $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' MetaFieldCollectionResponsePartialSuccess_DELETE: type: object description: | Response payload for the BigCommerce API. properties: data: type: array items: type: integer description: | The unique identifier for the metafield. example: - 123 errors: type: array items: $ref: '#/components/schemas/Error' meta: $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta' x-internal: false MetaFieldCollectionDeleteResponseSuccess: type: object description: | Response payload for the BigCommerce API. properties: data: type: array items: type: integer description: | The unique identifier for the metafield. example: - 123 - 124 - 125 errors: type: array description: Empty for 200 responses. example: [] meta: $ref: '#/components/schemas/WriteCollectionSuccessMeta' x-internal: false WriteCollectionPartialSuccessMeta: type: object description: Additional data about the response. properties: total: type: integer description: | Total number of items in the result set. example: 3 success: type: integer description: | Total number of items that were successfully deleted. example: 1 failed: type: integer description: | Total number of items that failed to be deleted. example: 2 title: Collection Meta x-internal: false WriteCollectionSuccessMeta: type: object description: Additional data about the response. properties: total: type: integer description: | Total number of items in the result set. example: 3 success: type: integer description: | Total number of items that were successfully deleted. example: 3 failed: type: integer description: | Total number of items that failed to be deleted. example: 0 title: Collection Meta x-internal: false Total: type: integer description: | Total number of items in the result set. example: 3 Success: type: integer description: | Total number of items that were successfully deleted. example: 1 Failed: type: integer description: | Total number of items that failed to be deleted. example: 2 Error: type: object description: | Error response payload for the BigCommerce API. properties: status: type: integer description: | The HTTP status code for the error. example: 422 title: type: string description: | The error title. example: Bulk operation has failed type: type: string description: | The error type. example: >- https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes errors: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: type: object description: | Error detail response payload for the BigCommerce API. example: '1': Unauthorized to delete '2': Metafield does not exist MetafieldPost_Batch: description: | The model for a POST to create metafield. allOf: - $ref: '#/components/schemas/MetafieldBase_Post' - type: object properties: resource_id: type: integer example: 42 description: | The ID for the resource with which the metafield is associated. required: - resource_id x-internal: false MetafieldPut_Batch: description: | The model for a PUT to create metafield. allOf: - $ref: '#/components/schemas/MetafieldBase_Post' - type: object properties: id: type: integer example: 42 description: | The ID of metafield to update. resource_id: type: integer example: 42 description: | The ID for the resource with which the metafield is associated. required: - id x-internal: false ChannelOrderSettings: type: object properties: notifications: type: object description: Channel notification settings. properties: order_placed: description: Channel order notification settings. type: object properties: email_addresses: description: >- Email addresses channel order notifications will be sent to. If null will fall back to global value. Empty array disables order notifications for channel. type: array nullable: true items: type: string forward_invoice: description: Channel order invoice forward settings. type: object properties: email_addresses: description: >- Email addresses channel order invoices will be forwarded to. If null will fall back to global value. Empty array disables forwarding order invoices for channel. type: array nullable: true items: type: string x-tags: - Models title: ChannelOrderSettings ErrorResponse400: type: object properties: schema: $ref: '#/components/schemas/betaErrorResponse' x-tags: - Models ErrorResponse404: type: object properties: schema: $ref: '#/components/schemas/betaErrorResponse' x-tags: - Models ErrorResponse422: type: object properties: schema: $ref: '#/components/schemas/betaErrorResponse' x-tags: - Models betaErrorResponse: allOf: - $ref: '#/components/schemas/BaseError' - type: object properties: errors: type: object x-tags: - Models BaseError: type: object description: | Error payload for the BigCommerce API. properties: status: description: | The HTTP status code. type: integer title: description: | The error title describing the particular error. type: string type: type: string x-tags: - Models betaDetailedErrors: type: object x-tags: - Models responses: Return_Resp: description: '' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Return_Full' meta: type: object properties: pagination: $ref: '#/components/schemas/Pagination' ReturnStatus_Resp: description: '' content: application/json: schema: properties: data: $ref: '#/components/schemas/UpdateReturnStatuses' errors: type: array items: $ref: '#/components/schemas/Problem' meta: $ref: '#/components/schemas/BatchOperationMeta' OrderReturnableItems_Resp: description: '' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/GetReturnableItems' CreateReturn_Resp: description: '' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateReturn' ReceivedItems_Resp: description: '' content: application/json: schema: properties: data: $ref: '#/components/schemas/ReceivedItems_Base' errors: type: array items: $ref: '#/components/schemas/Problem' meta: $ref: '#/components/schemas/BatchOperationMeta' ReviewedItems_Resp: description: '' content: application/json: schema: properties: data: $ref: '#/components/schemas/ReviewedItems_Base' errors: type: array items: $ref: '#/components/schemas/Problem' meta: $ref: '#/components/schemas/BatchOperationMeta' StoreReturnSettings_Resp: description: '' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/GetReturnsSettings' 502_GatewayError: description: >- If something happens during the request that causes it to fail, a 502 response will be returned. A new request should be made; however, it could fail. content: application/json: schema: $ref: '#/components/schemas/error_Base' examples: response: value: status: 502 title: >- A login URL could not be generated. Please try another request. type: /api-docs/getting-started/api-status-codes 504_GatewayTimeout: description: >- If this occurs, you should retry the request. Typically retrying the request several times will result in a successful request; however, if you cannot successfully make a request, please check the BigCommerce system status [here](https://status.bigcommerce.com/). A service is likely down, and you will need to complete the request again when it is back up (in several hours, usually). content: application/json: schema: $ref: '#/components/schemas/errorDetailed_Full' examples: response: value: status: 504 title: Gateway Timeout type: /api-docs/getting-started/api-status-codes errors: {} 403_Unauthorized: description: '' content: application/json: schema: $ref: '#/components/schemas/error_Base' examples: response: value: status: 403 title: >- Unauthorized Access. You do not have permission to make this request. type: /api-docs/getting-started/api-status-codes 400_BadRequest: description: |- Malformed request syntax. Typically need to fix the JSON. Body to resend successfully. content: application/json: schema: $ref: '#/components/schemas/error_Base' examples: response: value: status: 400 title: Input is invalid. type: /api-docs/getting-started/api-status-codes 404_NotFound: description: The resource was not found. content: application/json: schema: $ref: '#/components/schemas/error_Base' examples: response: value: status: 404 title: Account with {id} not found type: /api-docs/getting-started/api-status-codes 422_UnprocessableEntity: description: >- This occurs when missing or unacceptable data is passed for one or more fields. Please correct the values for the fields listed in the errors object. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: response: value: status: 422 title: JSON data is missing or invalid type: /api-docs/getting-started/api-status-codes errors: name: error.expected.jsstring primary_contact.district: error.expected.jsstring. 503_ServiceUnavailable: description: >- If this occurs, you should retry the request. If you cannot successfully make a request, please check the BigCommerce system status [here](https://status.bigcommerce.com/). A service is likely down, and you will need to make the request again when it is back up (in several hours, usually). content: application/json: schema: $ref: '#/components/schemas/error_Base' examples: response: value: status: 503 title: Service Unavailable type: /api-docs/getting-started/api-status-codes paymentActionsCapture_Resp: description: '' content: application/json: schema: type: object properties: {} paymentActionsVoid_Resp: description: '' content: application/json: schema: type: object properties: {} 201_Acknowledged: description: Request acknowledged. content: application/json: schema: type: object properties: {} 201_Created: description: Resource Created. content: application/json: schema: type: object RefundCollection_Resp: description: '' content: application/json: schema: type: object description: Response payload for Refund resource. properties: data: type: array description: Collection of Refunds items: $ref: '#/components/schemas/Refund' meta: $ref: '#/components/schemas/metaEmpty_Full' refundsBATCH_Resp: description: '' content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Refund' errors: type: array items: $ref: '#/components/schemas/FailedQuoteError' meta: $ref: '#/components/schemas/MetaRefund' RefundQuote_Resp: description: '' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/RefundQuote_Full' meta: $ref: '#/components/schemas/metaEmpty_Full' Refund_Resp: description: '' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Refund' meta: $ref: '#/components/schemas/metaEmpty_Full' TransactionCollection_Resp: description: Response payload for the BigCommerce Order Transactions API. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Transaction' meta: $ref: '#/components/schemas/metaCollection_Full' Transaction_Resp: description: >- Response payload for the BigCommerce Order Transactions API single transaction. content: application/json: schema: allOf: - properties: data: $ref: '#/components/schemas/Transaction_Post' - properties: id: type: integer description: | Unique identifier for the transaction. order_id: type: string description: >- Identifier for the BigCommerce Order with which this transaction is associated. date_created: type: string format: date-time description: | The datetime of the transaction. payment_instrument_token: type: string description: >- This field contains internal BigPay token for stored card that is then mapped to the actual third-party token. We currently do not offer a way to get third party tokens.These tokens are read-only and do not return any information about the payment. avs_result: $ref: '#/components/schemas/AVSResult' cvv_result: $ref: '#/components/schemas/CVVResult' credit_card: $ref: '#/components/schemas/CreditCard' gift_certificate: $ref: '#/components/schemas/GiftCertificate' store_credit: $ref: '#/components/schemas/StoreCredit' - properties: meta: $ref: '#/components/schemas/metaEmpty_Full' type: object RefundQuotesBATCH_Resp: description: '' 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' RefundID_Response: description: '' content: application/json: schema: $ref: '#/components/schemas/RefundID_Get' examples: Example: value: data: id: 12 order_id: 180 user_id: 0 created: '2022-06-16T16:44:15+00:00' reason: Customer requires a refund. total_amount: 50 total_tax: 5 uses_merchant_override_values: false payments: - id: 13 provider_id: storecredit amount: 50 offline: true is_declined: false declined_message: '' items: - item_type: PRODUCT item_id: 87 quantity: 1 requested_amount: meta: {} parameters: OrderIdParam: name: order_id in: path description: | The ID of the `Order` to which the transactions belong. required: true schema: type: integer Accept: name: Accept in: header required: true description: >- The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. schema: type: string default: application/json ContentType: name: Content-Type in: header required: true description: >- The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body. schema: type: string default: application/json PageParam: name: page description: | Specifies the page number in a limited (paginated) list of products. required: false in: query schema: type: integer MetafieldIdParam: name: metafield_id in: path description: | The ID of the `Metafield`. required: true schema: type: integer MetafieldKeyParam: name: key in: query description: | Filter based on a metafieldʼs key. required: false schema: type: string MetafieldKeyInParam: name: key:in in: query description: >- Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter. required: false style: form explode: false schema: type: array items: type: string MetafieldNamespaceParam: name: namespace in: query description: | Filter based on a metafieldʼs key. required: false schema: type: string MetafieldNamespaceInParam: name: namespace:in in: query description: >- Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter. required: false style: form explode: false schema: type: array items: type: string LimitParam: name: limit description: > Controls the number of items per page in a limited (paginated) list of products. required: false in: query schema: type: integer DirectionParam: name: direction description: | Sort direction. Acceptable values are: `asc`, `desc`. required: false in: query schema: type: string enum: - asc - desc securitySchemes: X-Auth-Token: name: X-Auth-Token description: >- ### OAuth scopes | UI Name | Permission | Parameter | |:--|:--|:-| | Order Transactions | read and modify `transactions` and `payment_methods` | `store_v2_transactions` | | Order Transactions | read `transactions` and `payment_methods` | `store_v2_transactions_read_only` | | Orders | read and modify `payment_methods` |`store_v2_orders`| | Orders | read `payment_methods` |`store_v2_orders_read_only`| ### Authentication header | Header | Argument | Description | |:-|:|:| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header examples: EnableMultipleOrderNotifications: summary: Enable order placed and forward invoice notifications value: notifications: order_placed: email_addresses: - admin@example.com - another-email@example.com forward_invoice: email_addresses: - admin@example.com - another-email@example.com GlobalOrderSettingsDisableOrderPlacedNotificatons: summary: Disable order placed notifications at global level value: notifications: order_placed: email_addresses: [] ChannelOrderSettingsOverrideOrderPlacedEmailAddressesAndDisableForwardEmail: summary: >- Override order placed email addresses and forward email addresses global value for channel value: notifications: order_placed: email_addresses: - admin@example.com - another-email@example.com forward_invoice: email_addresses: [] ChannelOrderSettingsReset: summary: Reset order placed email addresses to global value for channel value: notifications: order_placed: email_addresses: forward_invoice: email_addresses: ChannelOrderSettingsDisableBothNotifications: summary: Disable order placed notifications for channel value: notifications: order_placed: email_addresses: [] forward_invoice: email_addresses: []