BigCommerce Tax Provider API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Tax Provider API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
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: Tax Provider
paths:
  /estimate:
    post:
      summary: BigCommerce Estimate Taxes
      tags:
      - Tax Provider
      description: 'Submit the quote request to retrieve an estimate from the enabled third-party tax provider. Estimates are not expected to be persisted by the tax provider.


        > Server URL

        > - For supporting tax providers, the server URL contains the tax provider''s profile field; for example, `your_profile.example.com`.

        > - The Try it feature is not currently supported for this endpoint.


        The following actions can trigger tax estimate requests multiple times during a standard checkout on a BigCommerce storefront, depending on the BigCommerce merchant’s settings.


        - After selecting a Shipping Method during the “Estimate Shipping & Tax” facility on the Cart page.

        - After specifying a Shipping Address during a Checkout.

        - After selecting a Shipping Method during a Checkout.

        - After specifying a Billing Address during a Checkout.


        The following actions are not expected to trigger estimate requests.


        - While anonymously browsing a store’s product catalog.

        - On the Cart page prior to a Shopper selecting a Shipping Method via “Estimate Shipping & Tax”.

        - On the Checkout page prior to specifying a Shipping Address.

        - On the Checkout page, when toggling any option related to using the shopper’s Shipping Address as their Billing Address.


        The following control panel actions can also trigger tax estimate requests.


        - Order refund.

        - Edit order.

        - Test connection feature in Tax Settings.'
      operationId: estimateTaxes
      parameters:
      - $ref: '#/components/parameters/header-storehash'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request-quote'
            examples:
              example:
                value:
                  id: 3f0c857e-2c55-443e-a89b-c3c4d8a29605
                  currency_code: USD
                  customer:
                    customer_id: '0'
                    customer_group_id: '0'
                    taxability_code: ''
                  transaction_date: '2019-08-13T03:17:37+00:00'
                  documents:
                  - id: 5d522b889d3d9
                    billing_address:
                      line1: ''
                      line2: ''
                      city: ''
                      region_name: ''
                      region_code: ''
                      country_name: ''
                      country_code: ''
                      postal_code: ''
                      company_name: ''
                      type: RESIDENTIAL
                    destination_address:
                      line1: ''
                      line2: ''
                      city: Van Wert
                      region_name: Ohio
                      region_code: OH
                      country_name: United States
                      country_code: US
                      postal_code: '45892'
                      company_name: ''
                      type: RESIDENTIAL
                    origin_address:
                      line1: 2139 W ANDERSON LN
                      line2: ''
                      city: AUSTIN
                      region_name: Texas
                      region_code: TX
                      country_name: United States
                      country_code: US
                      postal_code: '78757'
                      company_name: ''
                      type: COMMERCIAL
                    shipping:
                      id: 5d522b889d3d9
                      item_code: Flat Rate
                      name: Shipping to Van Wert, United States 45891
                      price:
                        amount: 10
                        tax_inclusive: false
                      quantity: 1
                      tax_class:
                        code: ''
                        class_id: '6'
                        name: Shipping
                      tax_exempt: false
                      type: shipping
                    handling:
                      id: 5d522b889d3d9
                      item_code: Flat Rate
                      name: Handling for Van Wert, United States 45891
                      price:
                        amount: 0
                        tax_inclusive: false
                      quantity: 1
                      tax_class:
                        code: ''
                        class_id: '6'
                        name: Handling
                      tax_exempt: false
                      type: handling
                    items:
                    - id: 088c7465-e5b8-4624-a220-0d9faa82e7cb
                      item_code: ABS
                      name: '[Sample] Able Brewing System'
                      price:
                        amount: 450
                        tax_inclusive: false
                      quantity: 2
                      tax_class:
                        code: ''
                        class_id: '0'
                        name: Default Tax Class
                      tax_exempt: false
                      type: item
                      wrapping:
                        id: d2675662-6326-4a23-9107-ab71fa6a21a1
                        item_code: ''
                        name: 'Wrapping: [Sample] Canvas Laundry Cart'
                        price:
                          amount: 5
                          tax_inclusive: false
                        quantity: 1
                        tax_class:
                          code: ''
                          class_id: '6'
                          name: Wrapping
                        tax_exempt: false
                        type: wrapping
                    - id: d2675662-6326-4a23-9107-ab71fa6a21a1
                      item_code: CLC
                      name: '[Sample] Canvas Laundry Cart'
                      price:
                        amount: 200
                        tax_inclusive: false
                      quantity: 1
                      tax_class:
                        code: ''
                        class_id: '0'
                        name: Default Tax Class
                      tax_exempt: false
                      type: item
                      wrapping:
                        id: d2675662-6326-4a23-9107-ab71fa6a21a1
                        item_code: ''
                        name: 'Wrapping: [Sample] Canvas Laundry Cart'
                        price:
                          amount: 5
                          tax_inclusive: false
                        quantity: 1
                        tax_class:
                          code: ''
                          class_id: '6'
                          name: Wrapping
                        tax_exempt: false
                        type: wrapping
        description: Estimates may not always contain complete data as these requests will be fired at different stages of the shopper checkout. For example, the **Estimate Shipping & Tax** function on the **Cart** page is not expected to provide any billing address data, but the tax provider will still be expected to return a valid estimate.
        required: true
      responses:
        '200':
          description: Noteworthy is that the estimate response does not contain an **external ID** since there is no expectation that an estimate will result in any persisted tax documents by the tax provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-quote'
              examples:
                response:
                  value:
                    documents:
                    - id: 5d522b889d3d9
                      items:
                      - id: 088c7465-e5b8-4624-a220-0d9faa82e7cb
                        price:
                          amount_inclusive: 675
                          amount_exclusive: 450
                          total_tax: 225
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 225
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: item
                        wrapping:
                          id: d2675662-6326-4a23-9107-ab71fa6a21a1
                          price:
                            amount_exclusive: 5
                            amount_inclusive: 7.5
                            sales_tax_summary:
                            - amount: 2.5
                              id: '1'
                              name: BRUTAL TAX
                              rate: 0.5
                              tax_class:
                                class_id: '6'
                                code: US
                                name: Wrapping
                            tax_rate: 0.5
                            total_tax: 2.5
                          type: wrapping
                      - id: d2675662-6326-4a23-9107-ab71fa6a21a1
                        price:
                          amount_inclusive: 300
                          amount_exclusive: 200
                          total_tax: 100
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 100
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: item
                        wrapping:
                          id: d2675662-6326-4a23-9107-ab71fa6a21a1
                          price:
                            amount_exclusive: 5
                            amount_inclusive: 7.5
                            sales_tax_summary:
                            - amount: 2.5
                              id: '1'
                              name: BRUTAL TAX
                              rate: 0.5
                              tax_class:
                                class_id: '6'
                                code: US
                                name: Wrapping
                            tax_rate: 0.5
                            total_tax: 2.5
                          type: wrapping
                      shipping:
                        id: 5d522b889d3d9
                        price:
                          amount_inclusive: 15
                          amount_exclusive: 10
                          total_tax: 5
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 5
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: shipping
                      handling:
                        id: 5d522b889d3d9
                        price:
                          amount_inclusive: 0
                          amount_exclusive: 0
                          total_tax: 0
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 0
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: handling
                    id: 3f0c857e-2c55-443e-a89b-c3c4d8a29605
        '400':
          description: Fallback Tax will be used for this transaction. General response that points to an issue with the incoming request that means a valid response is unable to be returned.
        '401':
          description: Response to indicate that the merchant’s authentication credentials are invalid. The merchant will receive an update in their Store Logs.
        '500':
          description: Fallback Tax will be used for this transaction. General response that points to an error on the tax provider side. These types of errors should be promptly resolved by the tax provider.
  /void:
    post:
      summary: BigCommerce Void Tax Quote
      description: 'Invalidate the persisted tax quote as identified by the given unique ID. Relevant to order cancellations, full refunds, or moving an order from a paid status to an unpaid status.


        > Server URL

        > - For supporting tax providers, the server URL contains the tax provider''s profile field; for example, `your_profile.example.com`.

        > - The Try it feature is not currently supported for this endpoint.'
      operationId: voidTaxQuote
      parameters:
      - name: id
        in: query
        description: Unique ID identifying the existing, persisted Tax Quote that will be voided.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/header-storehash'
      responses:
        '200':
          description: OK
        '400':
          description: General response that points to an issue with the incoming request that means a valid response is unable to be returned.
        '401':
          description: Response to indicate that the merchant’s authentication credentials are invalid. The merchant will receive an update in their Store Logs.
        '500':
          description: General response that points to an error on the tax provider side. These types of errors should be promptly resolved by the tax provider.
      tags:
      - Tax Provider
  /commit:
    post:
      summary: BigCommerce Commit Tax Quote
      description: 'Submit the quote request to be persisted by the enabled third-party tax provider. A commit operation is intended to be submitted once only, when the Order has been confirmed and paid.


        > Server URL

        > - For supporting tax providers, the server URL contains the tax provider''s profile field; for example, `your_profile.example.com`.

        > - The Try it feature is not currently supported for this endpoint.'
      operationId: commitTaxQuote
      parameters:
      - $ref: '#/components/parameters/header-storehash'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request-quote'
            examples:
              example:
                value:
                  id: '113'
                  currency_code: USD
                  customer:
                    customer_id: '0'
                    customer_group_id: '0'
                    taxability_code: ''
                  transaction_date: '2019-08-13T03:40:15+00:00'
                  documents:
                  - id: shipping_14
                    billing_address:
                      line1: 402 S Vine St
                      line2: ''
                      city: Van Wert
                      region_name: Ohio
                      region_code: OH
                      country_name: United States
                      country_code: US
                      postal_code: '45891'
                      company_name: ''
                      type: RESIDENTIAL
                    destination_address:
                      line1: 402 S Vine St
                      line2: ''
                      city: Van Wert
                      region_name: Ohio
                      region_code: OH
                      country_name: United States
                      country_code: US
                      postal_code: '45891'
                      company_name: ''
                      type: RESIDENTIAL
                    origin_address:
                      line1: 2139 W ANDERSON LN
                      line2: ''
                      city: AUSTIN
                      region_name: Texas
                      region_code: TX
                      country_name: United States
                      country_code: US
                      postal_code: '78757'
                      company_name: ''
                      type: COMMERCIAL
                    shipping:
                      id: shipping_14
                      item_code: Flat Rate
                      name: Shipping to Van Wert, United States 45891
                      price:
                        amount: 10
                        tax_inclusive: false
                      quantity: 1
                      tax_class:
                        code: ''
                        class_id: '6'
                        name: Shipping
                      tax_exempt: false
                      type: shipping
                    handling:
                      id: handling_14
                      item_code: Flat Rate
                      name: Handling for Van Wert, United States 45891
                      price:
                        amount: 0
                        tax_inclusive: false
                      quantity: 1
                      tax_class:
                        code: ''
                        class_id: '6'
                        name: Handling
                      tax_exempt: false
                      type: handling
                    items:
                    - id: product_13
                      item_code: ABS
                      name: '[Sample] Able Brewing System'
                      price:
                        amount: 450
                        tax_inclusive: false
                      quantity: 2
                      tax_class:
                        code: ''
                        class_id: '0'
                        name: Default Tax Class
                      tax_exempt: false
                      type: item
                      wrapping:
                        id: product_14
                        item_code: ''
                        name: 'Wrapping: Holiday'
                        price:
                          amount: 5
                          tax_inclusive: false
                        quantity: 1
                        tax_class:
                          code: ''
                          class_id: '6'
                          name: Wrapping
                        tax_exempt: false
                        type: wrapping
                    - id: product_14
                      item_code: CLC
                      name: '[Sample] Canvas Laundry Cart'
                      price:
                        amount: 200
                        tax_inclusive: false
                      quantity: 1
                      tax_class:
                        code: ''
                        class_id: '0'
                        name: Default Tax Class
                      tax_exempt: false
                      type: item
                      wrapping:
                        id: product_14
                        item_code: ''
                        name: 'Wrapping: Holiday'
                        price:
                          amount: 5
                          tax_inclusive: false
                        quantity: 1
                        tax_class:
                          code: ''
                          class_id: '6'
                          name: Wrapping
                        tax_exempt: false
                        type: wrapping
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-quote'
              examples:
                response:
                  value:
                    documents:
                    - external_id: sample-doc-123456789
                      id: shipping_14
                      items:
                      - id: product_13
                        price:
                          amount_inclusive: 675
                          amount_exclusive: 450
                          total_tax: 225
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 225
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: item
                        wrapping:
                          id: product_14
                          price:
                            amount_exclusive: 5
                            amount_inclusive: 7.5
                            sales_tax_summary:
                            - amount: 2.5
                              id: '1'
                              name: BRUTAL TAX
                              rate: 0.5
                              tax_class:
                                class_id: '6'
                                code: US
                                name: Wrapping
                            tax_rate: 0.5
                            total_tax: 2.5
                          type: wrapping
                      - id: product_14
                        price:
                          amount_inclusive: 300
                          amount_exclusive: 200
                          total_tax: 100
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 100
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: item
                        wrapping:
                          id: product_14
                          price:
                            amount_exclusive: 5
                            amount_inclusive: 7.5
                            sales_tax_summary:
                            - amount: 2.5
                              id: '1'
                              name: BRUTAL TAX
                              rate: 0.5
                              tax_class:
                                class_id: '6'
                                code: US
                                name: Wrapping
                            tax_rate: 0.5
                            total_tax: 2.5
                          type: wrapping
                      shipping:
                        id: shipping_14
                        price:
                          amount_inclusive: 15
                          amount_exclusive: 10
                          total_tax: 5
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 5
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: shipping
                      handling:
                        id: handling_14
                        price:
                          amount_inclusive: 0
                          amount_exclusive: 0
                          total_tax: 0
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 0
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: handling
                    id: '113'
        '400':
          description: General response that points to an issue with the incoming request that means a valid response is unable to be returned.
        '401':
          description: Response to indicate that the merchant’s authentication credentials are invalid. The merchant will receive an update in their Store Logs.
        '500':
          description: General response that points to an error on the tax provider side. These types of errors should be promptly resolved by the tax provider.
      tags:
      - Tax Provider
  /adjust:
    post:
      responses:
        '200':
          description: Returned Tax Quote response matches the updated QuoteRequest provided to the service method.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-quote'
              examples:
                response:
                  value:
                    documents:
                    - id: 5d522b889d3d9
                      items:
                      - id: 088c7465-e5b8-4624-a220-0d9faa82e7cb
                        price:
                          amount_inclusive: 675
                          amount_exclusive: 450
                          total_tax: 225
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 225
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: item
                        wrapping:
                          id: d2675662-6326-4a23-9107-ab71fa6a21a1
                          price:
                            amount_exclusive: 5
                            amount_inclusive: 7.5
                            sales_tax_summary:
                            - amount: 2.5
                              id: '1'
                              name: BRUTAL TAX
                              rate: 0.5
                              tax_class:
                                class_id: '6'
                                code: US
                                name: Wrapping
                            tax_rate: 0.5
                            total_tax: 2.5
                          type: wrapping
                      - id: d2675662-6326-4a23-9107-ab71fa6a21a1
                        price:
                          amount_inclusive: 300
                          amount_exclusive: 200
                          total_tax: 100
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 100
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: item
                        wrapping:
                          id: d2675662-6326-4a23-9107-ab71fa6a21a1
                          price:
                            amount_exclusive: 5
                            amount_inclusive: 7.5
                            sales_tax_summary:
                            - amount: 2.5
                              id: '1'
                              name: BRUTAL TAX
                              rate: 0.5
                              tax_class:
                                class_id: '6'
                                code: US
                                name: Wrapping
                            tax_rate: 0.5
                            total_tax: 2.5
                          type: wrapping
                      shipping:
                        id: 5d522b889d3d9
                        price:
                          amount_inclusive: 15
                          amount_exclusive: 10
                          total_tax: 5
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 5
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: shipping
                      handling:
                        id: 5d522b889d3d9
                        price:
                          amount_inclusive: 0
                          amount_exclusive: 0
                          total_tax: 0
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 0
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: handling
                    id: 3f0c857e-2c55-443e-a89b-c3c4d8a29605
        '400':
          description: General response that points to an issue with the incoming request that means a valid response is unable to be returned.
        '401':
          description: Response to indicate that the merchant’s authentication credentials are invalid. The merchant will receive an update in their Store Logs.
        '500':
          description: General response that points to an error on the tax provider side. These types of errors should be promptly resolved by the tax provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-quote'
              examples:
                response:
                  value:
                    documents:
                    - external_id: sample-doc-123456789
                      id: shipping_14
                      items:
                      - id: product_13
                        price:
                          amount_inclusive: 337.5
                          amount_exclusive: 225
                          total_tax: 112.5
                          tax_rate: 0.5
                          sales_tax_summary:
                          - name: Brutal Tax
                            rate: 0.5
                            amount: 112.5
                            tax_class:
                              class_id: '0'
                              name: Brutal Tax
                              code: US
                            id: Brutal Tax
                        type: item
                        wrapping:
                          id: d2675662-6326-4a23-9107-ab71fa6a21a1
                          price:
                            amount_exclusive: 5
                            amount_inclusive: 7.5
                            sales_tax_summary:
                            - amount: 2.5
                              id: '1'
                              name: BRUTAL TAX
                              rate: 0.5
                              tax_class:
                                class_id: '6'
                                code: US
                                name: Wrapping
                            tax_rate: 0.5
                            total_tax: 2.5
          

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-tax-provider-api-openapi.yml