diff --git a/reference/orders.v3.yml b/reference/orders.v3.yml index 68ffa744a..70c49512e 100644 --- a/reference/orders.v3.yml +++ b/reference/orders.v3.yml @@ -1,13 +1,22 @@ -openapi: 3.0.3 +openapi: '3.0.3' info: title: Orders V3 version: '' description: Manage order settings of BigCommerce stores. - termsOfService: '' + 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' + - 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: @@ -16,25 +25,17 @@ tags: - name: Transactions - name: Order Settings paths: - '/stores/{store_hash}/v3/orders/{order_id}/payment_actions/capture': + '/orders/{order_id}/payment_actions/capture': post: - summary: Capture + summary: Capture order payment description: |- - Capture the payment for an order updating the `payment_status` to `capture pending`. - + 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: paymentactioncapture parameters: - - name: order_id - in: path - description: ID of the order - required: true - schema: - type: integer - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/Content-Type' + - $ref: '#/components/parameters/ContentType' responses: '201': $ref: '#/components/responses/201_Created' @@ -53,35 +54,20 @@ paths: tags: - Payment Actions parameters: - - name: store_hash - in: path - required: true - schema: - type: string - - name: order_id - in: path - required: true - schema: - type: string - '/stores/{store_hash}/v3/orders/{order_id}/payment_actions/void': + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/OrderIdParam' + '/orders/{order_id}/payment_actions/void': post: summary: Void description: |- - Void the payment for an order updating the `payment_status` to `void pending`. + 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: paymentactionvoid parameters: - - name: order_id - in: path - description: ID of the order - required: true - schema: - type: integer - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/Content-Type' + - $ref: '#/components/parameters/ContentType' responses: '201': $ref: '#/components/responses/201_Created' @@ -100,30 +86,12 @@ paths: tags: - Payment Actions parameters: - - name: store_hash - in: path - required: true - schema: - type: string - - name: order_id - in: path - required: true - schema: - type: string - '/stores/{store_hash}/v3/orders/{order_id}/transactions': + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/OrderIdParam' + '/orders/{order_id}/transactions': parameters: - - name: order_id - in: path - description: | - The ID of the `Order` to which the transactions belong. - required: true - schema: - type: integer - - name: store_hash - in: path - required: true - schema: - type: string + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/OrderIdParam' get: tags: - Transactions @@ -184,25 +152,7 @@ paths: type: string title: Not Found summary: Get Transactions - parameters: - - name: order_id - in: path - description: | - The ID of the `Order` to which the transactions belong. - required: true - schema: - type: integer - - in: header - name: Accept - schema: - type: string - default: application/json - - name: Content-Type - in: header - schema: - type: string - default: application/json - '/stores/{store_hash}/v3/orders/{order_id}/payment_actions/refund_quotes': + '/orders/{order_id}/payment_actions/refund_quotes': post: summary: Create a Refund Quote description: |- @@ -211,21 +161,26 @@ paths: 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: postrefundquote parameters: - - name: order_id - in: path - description: Order id - required: true - schema: - type: integer - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/Content-Type' + - $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: @@ -243,7 +198,7 @@ paths: - item_type: ORDER item_id: 1234 amount: 1 - reason: Overchaged $1.00 + reason: Overcharged $1.00 Multiple Items: items: - item_id: 75 @@ -252,6 +207,7 @@ paths: - item_id: 79 item_type: SHIPPING amount: 10 + description: '' responses: '201': $ref: '#/components/responses/RefundQuote_Resp' @@ -260,35 +216,24 @@ paths: tags: - Payment Actions parameters: - - name: order_id - in: path - required: true - schema: - type: string - - name: store_hash - in: path - required: true - schema: - type: string - '/stores/{store_hash}/v3/orders/{order_id}/payment_actions/refunds': + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/OrderIdParam' + '/orders/{order_id}/payment_actions/refunds': post: summary: Create a Refund description: |- - Creates a refund. + 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: postrefund parameters: - - name: order_id - in: path - description: order id - required: true - schema: - type: integer - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/Content-Type' + - $ref: '#/components/parameters/ContentType' requestBody: content: application/json: @@ -298,28 +243,18 @@ paths: x-examples: Quantity: items: - - item_id: 75 - item_type: PRODUCT + - item_type: PRODUCT + item_id: 31 + amount: 35.00 quantity: 1 + reason: Not the right product. payments: - provider_id: storecredit - amount: 232.75 + amount: 37.89 offline: false - Amount: - order_id: 1 - items: - - item_type: SHIPPING - item_id: 1 - amount: 1.99 - reason: string - reason: Wrong t-shirt size - payments: - - |- - { - "provider_id": "checkout_paypalexpress", - "amount": 9.99, - "offline": true - } + merchant_calculated_override: + - total_amount: 45.00 + total_tax: Tax Exempt (Order Level): order_id: 1234 items: @@ -363,6 +298,25 @@ paths: 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: @@ -397,26 +351,23 @@ paths: * `store_v2_orders_read_only` * `store_v2_orders` operationId: getorderrefunds - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/Content-Type' responses: '200': $ref: '#/components/responses/RefundCollection_Resp' tags: - Payment Actions parameters: - - name: order_id - in: path - required: true - schema: - type: string - - name: store_hash + - $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: string - '/stores/{store_hash}/v3/orders/payment_actions/refunds/{refund_id}': + type: integer get: summary: Get a Refund description: Returns a refund by refund ID. @@ -426,141 +377,9 @@ paths: $ref: '#/components/responses/RefundID_Response' tags: - Payment Actions + '/orders/payment_actions/refunds': parameters: - - name: refund_id - in: path - description: Refund ID. - required: true - schema: - type: integer - - name: store_hash - in: path - required: true - schema: - type: string - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/Content-Type' - '/stores/{store_hash}/v3/orders/payment_actions/refund_quotes': - post: - summary: Create Refund Quotes - BATCH - description: |- - Calculate the tax amount, total refund amount and get availble 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: postrefundquotes - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/Content-Type' - 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 - parameters: - - name: store_hash - in: path - required: true - schema: - type: string - '/stores/{store_hash}/v3/orders/payment_actions/refunds': get: summary: Get All Refunds description: |- @@ -572,6 +391,8 @@ paths: * `store_v2_orders_read_only` * `store_v2_orders` operationId: getrefunds + tags: + - Payment Actions parameters: - name: 'order_id:in' in: query @@ -591,8 +412,6 @@ paths: type: array items: type: integer - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/Content-Type' - in: query name: 'created:min' description: |- @@ -610,7 +429,6 @@ paths: 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` @@ -630,28 +448,25 @@ paths: responses: '200': $ref: '#/components/responses/RefundCollection_Resp' - tags: - - Payment Actions + '/orders/payment_actions/refund_quotes': post: - summary: Create Refunds - BATCH + summary: Create Refund Quotes - BATCH description: |- - Creates a refund. + 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: postrefunds + operationId: postrefundquotes parameters: - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/Content-Type' requestBody: content: application/json: schema: - $ref: '#/components/schemas/PostRefundsRequest' - examples: {} + $ref: '#/components/schemas/PostRefundQuotesRequest' required: true x-examples: application/json: @@ -660,18 +475,11 @@ paths: item_type: PRODUCT quantity: 1 tax_adjustment_amount: 0 - payments: - - provider_id: testgateway - amount: 220.5 - offline: false - - provider_id: storecredit - amount: 2.25 - offline: true responses: '201': - $ref: '#/components/responses/refundsBATCH_Resp' + $ref: '#/components/responses/RefundQuotesBATCH_Resp' '422': - description: Partial success/failure response. HTTP status for the entire response to roll up to the most severe individual failure to the whole request. + description: Partial success/failure response. Status to roll up to the most severe individual failure to the whole request. content: application/json: schema: @@ -680,13 +488,13 @@ paths: data: type: array items: - $ref: '#/components/schemas/Refund' + $ref: '#/components/schemas/RefundQuote_Full' errors: type: array items: $ref: '#/components/schemas/FailedQuoteError' meta: - type: object + $ref: '#/components/schemas/Meta' Example 1: examples: response: @@ -694,39 +502,22 @@ paths: { "data": [ { - "id": 1, - "order_id": 100, - "user_id": 1, - "created": "", - "reason": "", - "total_amount": 0.05, - "total_tax": 1, - "items": [ - { - "item_type": "ORDER", - "item_id": 1, - "reason": "", - "quantity": 1, - "requested_amount": 0.05 - } - ], - "payments": [ - { - "id": 1, - "provider_id": "checkout_paypalexpress", - "amount": 0.05, - "offline": true, - "is_declined": true, - "declined_message": "" - } + "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: [ + "errors": [ { "order_id": 1, "status": 422, - "error": "Refund amount was negative" + "error": "Refund amount is greater than remaining amount" } ], "meta": { @@ -745,61 +536,35 @@ paths: data: type: array items: - $ref: '#/components/schemas/Refund' + $ref: '#/components/schemas/RefundQuote_Full' errors: type: array items: $ref: '#/components/schemas/FailedQuoteError' meta: - type: object - Example 1: + $ref: '#/components/schemas/Meta' examples: response: - value: |- - { - "data": [ - ], - "errors": [ - { - "order_id": 1, - "status": 422, - "error": "Refund amount was negative" - }, - { - "order_id": 100, - "status": 503, - "error": "Tax service could not be contacted" - } - ], - "meta": { - "failure": 2, - "success": 0, - "total": 2 - } - } + 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: - - name: store_hash - in: path - required: true - schema: - type: string - '/stores/{store_hash}/v3/orders/{order_id}/metafields': - parameters: - - name: order_id - in: path - description: | - The ID of the `Order` to which the transactions belong. - required: true - schema: - type: integer - - name: store_hash - in: path - required: true - schema: - type: string + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/OrderIdParam' get: summary: Get Metafields tags: @@ -807,7 +572,7 @@ paths: description: | Gets a `Metafield` object list, by `order_id`. - The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. + The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. operationId: getOrderMetafieldsByOrderId parameters: - $ref: '#/components/parameters/PageParam' @@ -844,8 +609,10 @@ paths: description: |- Creates an order `Metafield`. - The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. + 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: @@ -865,7 +632,7 @@ paths: $ref: '#/components/schemas/MetafieldResponse' '409': description: | - The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. + The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client ID, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -877,15 +644,10 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorResponse' - '/stores/{store_hash}/v3/orders/{order_id}/metafields/{metafield_id}': + '/orders/{order_id}/metafields/{metafield_id}': parameters: - - name: order_id - in: path - description: | - The ID of the `Order` to which the transactions belong. - required: true - schema: - type: integer + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/OrderIdParam' - name: metafield_id in: path description: | @@ -893,11 +655,6 @@ paths: required: true schema: type: integer - - name: store_hash - in: path - required: true - schema: - type: string get: summary: Get a Metafield tags: @@ -929,6 +686,8 @@ paths: 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: @@ -963,7 +722,7 @@ paths: '204': description: | An empty response. - '/stores/{store_hash}/v3/orders/settings': + '/orders/settings': get: summary: Get Global Order Settings description: Returns global order settings. @@ -978,7 +737,10 @@ paths: schema: allOf: - $ref: '#/components/schemas/GlobalOrderSettings' - - $ref: '#/components/schemas/metaEmpty_Full' + - type: object + properties: + meta: + $ref: '#/components/schemas/metaEmpty_Full' examples: {} '400': description: Bad request. Authentication Required. @@ -990,6 +752,8 @@ paths: summary: Update Global Order Settings description: Updates global order settings. operationId: UpdateGlobalOrderSettings + parameters: + - $ref: '#/components/parameters/ContentType' tags: - Order Settings requestBody: @@ -1009,8 +773,11 @@ paths: application/json: schema: allOf: + - type: object - $ref: '#/components/schemas/GlobalOrderSettings' - - $ref: '#/components/schemas/metaEmpty_Full' + - properties: + meta: + $ref: '#/components/schemas/metaEmpty_Full' '400': description: Bad request. Authentication Required. content: @@ -1024,26 +791,14 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse422' parameters: - - schema: - type: string - name: store_hash - in: path - required: true - '/stores/{store_hash}/v3/orders/settings/channels/{channel_id}': + - $ref: '#/components/parameters/Accept' + '/orders/settings/channels/{channel_id}': get: summary: Get Channel Order Settings description: Returns order settings for a specific channel. operationId: GetChannelOrderSettings tags: - Order Settings - parameters: - - schema: - type: integer - minimum: 1 - in: path - name: channel_id - required: true - description: Channel Id responses: '200': description: OK @@ -1052,7 +807,10 @@ paths: schema: allOf: - $ref: '#/components/schemas/ChannelOrderSettings' - - $ref: '#/components/schemas/metaEmpty_Full' + - type: object + properties: + meta: + $ref: '#/components/schemas/metaEmpty_Full' examples: {} '400': description: Bad request. Authentication Required. @@ -1063,20 +821,14 @@ paths: put: summary: Update Channel Order Settings description: |- - Updates order settings for a specific channel. + 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 addesses and the other set to `null`. + **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 - parameters: - - schema: - type: integer - minimum: 1 - in: path - name: channel_id - required: true - description: Channel Id requestBody: content: application/json: @@ -1097,7 +849,10 @@ paths: schema: allOf: - $ref: '#/components/schemas/ChannelOrderSettings' - - $ref: '#/components/schemas/metaEmpty_Full' + - type: object + properties: + meta: + $ref: '#/components/schemas/metaEmpty_Full' '400': description: Bad request. Authentication Required. content: @@ -1111,15 +866,12 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse422' parameters: - - schema: - type: string - name: store_hash + - $ref: '#/components/parameters/Accept' + - name: channel_id in: path - required: true - - schema: + schema: type: string - name: channel_id - in: path + description: Channel ID required: true components: schemas: @@ -1143,10 +895,10 @@ components: format: int64 label: type: string - description: A description of the reason + description: A description of the reason. is_archived: type: boolean - description: Indicates whether or not the reason has been archived + description: Indicates whether or not the reason has been archived. x-internal: false PreferredOutcome: type: object @@ -1156,10 +908,10 @@ components: format: int64 label: type: string - description: A description of the outcome + description: A description of the outcome. is_archived: type: boolean - description: Indicates whether or not the outcome has been archived + description: Indicates whether or not the outcome has been archived. x-internal: false CreateReturnRequest: type: object @@ -1167,12 +919,12 @@ components: - items properties: items: - description: A collection of items to be returned + 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 + description: A comment provided to the merchant for review. type: string title: CreateReturnRequest x-internal: false @@ -1200,7 +952,7 @@ components: $ref: '#/components/schemas/Return_Full' Return_Full: type: object - description: A view of a return + description: A view of a return. properties: items: type: array @@ -1209,11 +961,11 @@ components: total: type: string format: decimal - description: The total price of the items being returned + 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 + description: The transactional currency of the return and the associated order. customer: type: object properties: @@ -1225,7 +977,7 @@ components: format: email comment: type: string - description: A comment provided to the merchant for review + description: A comment provided to the merchant for review. status: $ref: '#/components/schemas/Status_Full' date_modified: @@ -1234,62 +986,62 @@ components: x-internal: false ReturnItem: type: object - description: A view of a return item + description: A view of a returned item. properties: id: type: integer format: int64 - description: The unique identifier of this return item + 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 + description: The quantity of items for which a return was requested. total: type: string format: decimal - description: The total price of the line item + 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 + description: Unique identifier of the preferred outcome. label: type: string - description: A displayable label for the preferred outcome + description: A displayable label for the preferred outcome. reason: type: object properties: id: type: integer format: int64 - description: Unique identifier of the reason + description: Unique identifier of the reason. label: type: string - description: A displayable label for the reason + 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 + 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 + 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 + 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 + description: The quantity of items pending receipt by the merchant. rejected_quantity: type: integer - description: The quantity of items rejected by the merchant + description: The quantity of items rejected by the merchant. x-internal: false StatusUpdate_Full: type: object @@ -1297,7 +1049,7 @@ components: return_id: type: integer format: int64 - description: The ID of the return for which the status should be updated + description: The ID of the return for which the status should be updated. new_status: $ref: '#/components/schemas/Status_Full' title: StatusUpdate_Full @@ -1325,7 +1077,7 @@ components: id: type: integer format: int64 - description: The ID of the return for which the status was updated + description: The ID of the return for which the status was updated. status: $ref: '#/components/schemas/Status_Full' x-internal: false @@ -1334,27 +1086,27 @@ components: properties: status: type: integer - description: Status code of the problem + description: Status code of the problem. title: type: string - description: A short description of the problem + description: A short description of the problem. type: type: string format: url - description: A resource describing the problem + 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 + description: The total number of operations in the batch. success: type: integer - description: The number of failed operations in the batch + description: The number of failed operations in the batch. failed: type: integer - description: The number of failed operations in the batch + description: The number of failed operations in the batch. x-internal: false Pagination: type: object @@ -1417,13 +1169,13 @@ components: item_id: type: integer format: int64 - description: The ID of the item for which to update the received state + description: The item ID for updating the received state. received_quantity: type: integer - description: The quantity of items to be marked as received + description: The quantity of items to be marked as received. pending_quantity: type: integer - description: The quantity of items to be marked as pending + description: The quantity of items to be marked as pending. title: ReceivedItems_Put x-internal: false ReceivedItems_Base: @@ -1434,15 +1186,15 @@ components: item_id: type: integer format: int64 - description: The ID of the item for which received item status was updated + 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 + description: The quantity of items marked as received. pending_quantity: type: integer format: int64 - description: The quantity of items marked as pending + description: The quantity of items marked as pending. title: ReceivedItems_Base x-internal: false ReviewedItems_Put: @@ -1458,16 +1210,16 @@ components: item_id: type: integer format: int64 - description: The ID of the item for which to update the reviewed state + description: The item ID for updating the reviewed state. authorized_quantity: type: integer - description: The quantity of items to be marked as authorized + description: The quantity of items to be marked as authorized. rejected_quantity: type: integer - description: The quantity of items to be marked as rejected + description: The quantity of items to be marked as rejected. pending_quantity: type: integer - description: The quantity of items to be marked as pending + description: The quantity of items to be marked as pending. title: ReviewedItems_Put x-internal: false ReviewedItems_Base: @@ -1478,19 +1230,19 @@ components: item_id: type: integer format: int64 - description: The ID of the item for which reviewed status was updated + 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 + description: The quantity of items marked as authorized. rejected_quantity: type: integer format: int64 - description: The quantity of items marked as rejected + description: The quantity of items marked as rejected. pending_quantity: type: integer format: int64 - description: The quantity of items marked as pending + description: The quantity of items marked as pending. title: ReviewedItems_Base x-internal: false GetReturnableItems: @@ -1502,14 +1254,14 @@ components: $ref: '#/components/schemas/ItemReferenceId' name: type: string - description: The name of the order product + 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 + 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 + description: The total price of this line item. options: type: array items: @@ -1517,24 +1269,24 @@ components: properties: display_name: type: string - description: A displayable name for the option + 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 + 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 + description: The reference type. enum: - ORDER_PRODUCT value: type: string - description: The value identifying the returned item + description: The value identifying the returned item. required: - type - value @@ -1653,15 +1405,15 @@ components: properties: errors: type: object - additionalProperties: - type: string + properties: {} + additionalProperties: true title: DetailedErrors title: ErrorResponse x-internal: false DetailedErrors: type: object - additionalProperties: - type: string + properties: {} + additionalProperties: true title: DetailedErrors x-internal: false Transaction_Post: @@ -1691,6 +1443,7 @@ components: - store_credit - apple_pay_card - apple_pay_token + - bigpay_token - token - custom - offsite @@ -1716,12 +1469,12 @@ components: - amazon - authorizenet - bankdeposit + - bigcommerce - braintree - cheque - cod - custom - firstdatagge4 - - giftcertificate - hps - instore - klarna @@ -1735,7 +1488,6 @@ components: - qbmsv2 - securenet - square - - storecredit - stripe - testgateway - usaepay @@ -1745,7 +1497,7 @@ components: type: string date_created: description: | - The datetime of the transaction. + The date/time of the transaction. type: string format: date-time test: @@ -1796,7 +1548,6 @@ components: title: Not Found x-internal: false Transaction: - description: A BigCommerce Transaction object describes a single transaction. allOf: - title: Transaction Base properties: @@ -1822,6 +1573,7 @@ components: - gift_certificate - store_credit - apple_pay_card + - bigpay_token - apple_pay_token - token - custom @@ -1854,7 +1606,6 @@ components: - cod - custom - firstdatagge4 - - giftcertificate - hps - instore - klarna @@ -1868,7 +1619,6 @@ components: - qbmsv2 - securenet - square - - storecredit - stripe - testgateway - usaepay @@ -1878,7 +1628,7 @@ components: type: string date_created: description: | - The datetime of the transaction. + The date/time of the transaction. type: string format: date-time test: @@ -1921,7 +1671,7 @@ components: payment_method_id: type: string description: | - The payment method ID used for this transaction + The payment method ID used for this transaction. required: - event - method @@ -1939,7 +1689,7 @@ components: Identifier for the BigCommerce Order with which this transaction is associated. date_created: description: | - The datetime of the transaction. + The date/time of the transaction. type: string format: date-time payment_instrument_token: @@ -2016,9 +1766,52 @@ components: type: number format: float example: 35.42 - title: Transaction - x-internal: false 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. @@ -2187,11 +1980,10 @@ components: x-internal: false metaEmpty_Full: type: object - title: metaEmpty_Full - x-internal: false - properties: - meta: - type: object + title: Response meta + properties: {} + additionalProperties: true + description: Response metadata. pagination_Full: type: object title: pagination_Full @@ -2277,8 +2069,8 @@ components: properties: errors: type: object - additionalProperties: - type: string + properties: {} + additionalProperties: true title: DetailedErrors title: errorDetailed_Full x-internal: false @@ -2296,24 +2088,20 @@ components: x-internal: false x-examples: {} properties: - order_id: - type: integer - description: Order ID against which this refund will be created. This is optional for creating a single refund request. The order ID is included in the request path. - example: 1 items: type: array items: $ref: '#/components/schemas/ItemsRefund' required: - - order_id - items RefundQuote_Full: type: object title: RefundQuote_Full + x-internal: false properties: order_id: type: integer - description: ID of the order to be refunded + description: ID of the order to be refunded. total_refund_amount: $ref: '#/components/schemas/Amount' total_refund_tax_amount: @@ -2321,12 +2109,12 @@ components: example: 1.95 rounding: type: number - description: Indicates rounding value to bring refund_total to an amount refundable via payment providers (in this case to 2 decimal places) + 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 + description: Indicate if `total_refund_amount` includes tax amount. refund_methods: type: array description: | @@ -2383,12 +2171,9 @@ components: 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 via a manual refund, which will be recorded as being refunded against the bank deposit. - - > + 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' - x-internal: false RefundRequest_Post: type: object description: Request body for refund requests. @@ -2399,10 +2184,6 @@ components: type: array items: $ref: '#/components/schemas/ItemsRefund' - reason: - type: string - description: Reason for refund - example: Wrong t-shirt size payments: type: array items: @@ -2438,7 +2219,7 @@ components: item_id: 87 quantity: 1 requested_amount: null - reason: incididunt exercitation enim + reason: Wrong color meta: {} properties: data: @@ -2447,10 +2228,10 @@ components: id: type: integer description: | - Refund ID for the returned refund + Refund ID for the returned refund. order_id: type: integer - description: Order ID associated with the refund + description: Order ID associated with the refund. user_id: type: integer description: | @@ -2458,12 +2239,12 @@ components: created: type: string description: | - Timestamp of when the refund was created + Timestamp of when the refund was created. format: date-time reason: type: string description: | - Reason for refund + Reason for refund. total_amount: type: number description: | @@ -2485,29 +2266,29 @@ components: id: type: integer description: | - Reference to refund payment ID + Reference to refund payment ID. provider_id: type: string description: | - Reference to payment provider + 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 via payment providers. + 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 + Indicates whether the payment was offline. is_declined: type: boolean description: | - Indicates if this payment has been declined by the payment provider + Indicates if this payment has been declined by the payment provider. declined_message: type: string description: | - Message indicates why the payment was declined + Message indicates why the payment was declined. items: type: array items: @@ -2516,7 +2297,7 @@ components: item_type: type: string description: | - Type of item that was refunded + Type of item that was refunded. enum: - PRODUCT - GIFT_WRAPPING @@ -2530,7 +2311,7 @@ components: quantity: type: integer description: | - Quantity of item refunded. Note: this will only be populated for item_type PRODUCT + Quantity of item refunded. Note: this will only be populated for item_type PRODUCT. requested_amount: type: string description: | @@ -2540,12 +2321,12 @@ components: reason: type: string description: | - Reason for refunding an item + Reason for refunding an item. meta: - type: object + $ref: '#/components/schemas/metaEmpty_Full' PostRefundsRequest: type: array - description: Request body for batch refunds + description: Request body for batch refunds. title: Refunds Request - BATCH items: $ref: '#/components/schemas/RefundRequest_Post' @@ -2559,17 +2340,17 @@ components: type: integer status: type: integer - description: HTTP status code + description: HTTP status code. example: 422 error: type: string - description: details why the request failed + description: Details why the request failed. title: FailedQuoteError x-internal: false ItemsRefund: title: ItemsRefund x-internal: false - anyOf: + oneOf: - $ref: '#/components/schemas/AmountBoundItem' - $ref: '#/components/schemas/QuantityBoundItem' - $ref: '#/components/schemas/TaxExemptItem' @@ -2579,11 +2360,11 @@ components: properties: provider_id: type: string - description: Reference to payment provider + description: Reference to payment provider. example: checkout_paypalexpress amount: type: number - description: Amount refunded via this provider + description: Amount refunded with this provider. example: 9.99 offline: type: boolean @@ -2605,25 +2386,35 @@ components: 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. ' + description: Order Product ID. quantity: type: integer example: 3 reason: type: string - description: Reason for refund + example: Wrong size. + description: Reason for refund. minLength: 0 maxLength: 1000 x-internal: false @@ -2631,6 +2422,7 @@ components: 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 @@ -2638,6 +2430,10 @@ components: 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: @@ -2645,22 +2441,30 @@ components: description: Reason for the refund. minLength: 0 maxLength: 1000 - x-internal: false AmountBoundItem: type: object title: Amount Bound Item - description: | + 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: @@ -2669,15 +2473,20 @@ components: 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 - x-internal: false + example: Customer requested refund MerchantOverride: type: object title: Merchant Calculated Override - description: | + description: |- Merchant explicitly provided override based on their own calculation. This override gives merchants the flexibility to @@ -2701,23 +2510,23 @@ components: properties: id: type: integer - description: Refund resource ID + description: Refund resource ID. readOnly: true order_id: type: integer - description: Reference to order id + 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. + 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 + description: Timestamp of when this refund was created. readOnly: true reason: type: string - description: Reason for refund + description: Reason for refund. total_amount: $ref: '#/components/schemas/Amount' total_tax: @@ -2725,16 +2534,16 @@ components: 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 + description: Whether refund amount and tax are provided explicitly by merchant override. items: type: array - description: Array of items refunded + 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 + description: An array of refund payments made to payment providers. minItems: 1 items: $ref: '#/components/schemas/RefundPayment' @@ -2744,7 +2553,7 @@ components: properties: item_type: type: string - description: Type of item that was refunded + description: Type of item that was refunded. enum: - PRODUCT - GIFT_WRAPPING @@ -2756,7 +2565,7 @@ components: 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 + description: Reason for refunding an item. quantity: type: integer description: 'Quantity of item refunded. Note: this will only be populated for item_type PRODUCT' @@ -2770,23 +2579,23 @@ components: properties: id: type: integer - description: Reference to refund payment id + description: Reference to refund payment ID. readOnly: true provider_id: type: string - description: Reference to payment provider + description: Reference to payment provider. example: storecredit amount: $ref: '#/components/schemas/Amount' offline: type: boolean - description: Indicate whether payment was offline + description: Indicate whether payment was offline. is_declined: type: boolean - description: Indicate if this payment has been declined by payment provider + description: Indicate if this payment has been declined by payment provider. declined_message: type: string - description: Message indicate why payment was declined + description: Message indicate why payment was declined. x-internal: false PaymentOption: type: object @@ -2796,20 +2605,20 @@ components: amount: 9.99 offline: true offline_provider: true - offline_reason: Multiple online refunds are not available + offline_reason: Multiple online refunds are not available. title: Payment Option properties: provider_id: type: string - description: Name of the payment method + description: Name of the payment method. example: checkout_paypalexpress provider_description: type: string - description: Description for payment provider + description: Description for payment provider. example: Paypal Express amount: type: number - description: amount to be refunded via this payment provider + description: Amount to be refunded with this payment provider. example: 9.99 offline: type: boolean @@ -2827,7 +2636,7 @@ components: Amount: type: number format: float - description: A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded via payment providers. + 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 @@ -2889,8 +2698,8 @@ components: description: | Determines the visibility and writeability of the field by other API consumers. - |Value|Description - |-|-| + |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| @@ -2960,8 +2769,8 @@ components: description: | Determines the visibility and writeability of the field by other API consumers. - |Value|Description - |-|-| + |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| @@ -3255,7 +3064,7 @@ components: 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 are unable to successfully make a request, please check the BigCommerce system status [here](https://status.bigcommerce.com/). A service is likely down and the request will need to be made again when it is back up (in several hours usually)' + 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: @@ -3281,7 +3090,7 @@ components: type: /api-docs/getting-started/api-status-codes 400_BadRequest: description: |- - Malformed request syntax. Typically need to fix the JSON + Malformed request syntax. Typically need to fix the JSON. Body to resend successfully. content: application/json: @@ -3321,7 +3130,7 @@ components: name: error.expected.jsstring primary_contact.district: error.expected.jsstring. 503_ServiceUnavailable: - description: 'If this occurs, you should retry the request. If you are unable to successfully make a request, please check the BigCommerce system status [here](https://status.bigcommerce.com/). A service is likely down and the request will need to be made again when it is back up (in several hours usually)' + 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: @@ -3359,14 +3168,13 @@ components: application/json: schema: type: object - properties: {} RefundCollection_Resp: description: '' content: application/json: schema: type: object - description: Response payload for Refund resource + description: Response payload for Refund resource. properties: data: type: array @@ -3374,8 +3182,7 @@ components: items: $ref: '#/components/schemas/Refund' meta: - type: object - description: Meta data collection + $ref: '#/components/schemas/metaEmpty_Full' refundsBATCH_Resp: description: '' content: @@ -3403,7 +3210,7 @@ components: data: $ref: '#/components/schemas/RefundQuote_Full' meta: - type: object + $ref: '#/components/schemas/metaEmpty_Full' Refund_Resp: description: '' content: @@ -3414,7 +3221,7 @@ components: data: $ref: '#/components/schemas/Refund' meta: - type: object + $ref: '#/components/schemas/metaEmpty_Full' TransactionCollection_Resp: description: Response payload for the BigCommerce Order Transactions API. content: @@ -3514,7 +3321,7 @@ components: item_id: 87 quantity: 1 requested_amount: null - reason: incididunt exercitation enim + reason: Wrong item sent. meta: {} parameters: OrderIdParam: @@ -3526,17 +3333,21 @@ components: schema: type: integer Accept: - in: header 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 - Content-Type: + 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 + default: 'application/json' PageParam: name: page description: | @@ -3590,34 +3401,32 @@ components: - desc securitySchemes: X-Auth-Token: - type: apiKey - in: header name: X-Auth-Token description: |- - ### OAuth Scopes - | **UI Name** | **Permission** | **Parameter** | - | --- | --- | --- | + ### 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`| - ### Headers - - |Header|Parameter|Description| - |-|-|-| - |`X-Auth-Token`|`access_token `|Obtained by creating an API account or installing an app in a BigCommerce control panel.| - - ### Example - - ```http - GET /stores/{store_hash}/v3/catalog/summary - host: api.bigcommerce.com - Content-Type: application/json - X-Auth-Token: {access_token} - ``` - - * For more information on Authenticating BigCommerce APIs, see: [Authentication](/api-docs/getting-started/authentication). + ### 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 @@ -3663,7 +3472,3 @@ components: email_addresses: [] forward_invoice: email_addresses: [] -x-stoplight: - docs: - includeDownloadLink: true - showModels: false