openapi: 3.1.0
info:
  title: 'Integrations: Tax Provider'
  version: 1.0.0
paths:
  /estimate:
    post:
      operationId: estimateTaxes
      summary: Estimate Taxes
      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.
      tags:
        - taxProvider
      parameters:
        - name: Authorization
          in: header
          description: >-
            The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
            (developer.mozilla.org) credentials used to authenticate each API request to the tax provider from the
            associated store; set and update `username`, `password`, and optionally `profile`, using the [Update a
            Connection](/developer/api-reference/rest/integrations/tax-provider/tax-provider-connection/update-tax-provider-connection)
            request. `profile` is an optional field and will be used with supporting providers only.


            For more, see [developer-configured
            authentication](/developer/docs/overview/api-fundamentals/api-accounts#developer-configured-authentication)
            for Provider APIs.
          required: true
          schema:
            type: string
        - name: X-Bc-Store-Hash
          in: header
          description: >-
            BigCommerce will send through the store hash as part of all tax provider operations. Each BigCommerce store
            on the platform has a unique store hash value for the store’s lifetime. This value can assist in account
            verification or profile matching responsibilities.
          required: true
          schema:
            type: string
      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'
        '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.
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: >-
            Response to indicate that the merchant’s authentication credentials are invalid. The merchant will receive
            an update in their Store Logs.
          content:
            application/json:
              schema:
                description: Any type
        '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.
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        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.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request-quote'
  /void:
    post:
      operationId: voidTaxQuote
      summary: 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.
      tags:
        - taxProvider
      parameters:
        - name: id
          in: query
          description: Unique ID identifying the existing, persisted tax quote that will be voided.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
            (developer.mozilla.org) credentials used to authenticate each API request to the tax provider from the
            associated store; set and update `username`, `password`, and optionally `profile`, using the [Update a
            Connection](/developer/api-reference/rest/integrations/tax-provider/tax-provider-connection/update-tax-provider-connection)
            request. `profile` is an optional field and will be used with supporting providers only.


            For more, see [developer-configured
            authentication](/developer/docs/overview/api-fundamentals/api-accounts#developer-configured-authentication)
            for Provider APIs.
          required: true
          schema:
            type: string
        - name: X-Bc-Store-Hash
          in: header
          description: >-
            BigCommerce will send through the store hash as part of all tax provider operations. Each BigCommerce store
            on the platform has a unique store hash value for the store’s lifetime. This value can assist in account
            verification or profile matching responsibilities.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tax Provider_voidTaxQuote_Response_200'
        '400':
          description: >-
            General response that points to an issue with the incoming request that means a valid response is unable to
            be returned.
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: >-
            Response to indicate that the merchant’s authentication credentials are invalid. The merchant will receive
            an update in their Store Logs.
          content:
            application/json:
              schema:
                description: Any type
        '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:
                description: Any type
  /commit:
    post:
      operationId: commitTaxQuote
      summary: 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.


        Merchants may adjust when commit operations occur by adjusting the document submission strategy in their store
        tax settings. The selected document submission strategy will adjust whether order status or payment status is
        used to determine if the order is paid. For more information, see the [Tax Settings API
        Reference](/developer/api-reference/rest/admin/management/tax/tax-settings).


        > 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.
      tags:
        - taxProvider
      parameters:
        - name: Authorization
          in: header
          description: >-
            The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
            (developer.mozilla.org) credentials used to authenticate each API request to the tax provider from the
            associated store; set and update `username`, `password`, and optionally `profile`, using the [Update a
            Connection](/developer/api-reference/rest/integrations/tax-provider/tax-provider-connection/update-tax-provider-connection)
            request. `profile` is an optional field and will be used with supporting providers only.


            For more, see [developer-configured
            authentication](/developer/docs/overview/api-fundamentals/api-accounts#developer-configured-authentication)
            for Provider APIs.
          required: true
          schema:
            type: string
        - name: X-Bc-Store-Hash
          in: header
          description: >-
            BigCommerce will send through the store hash as part of all tax provider operations. Each BigCommerce store
            on the platform has a unique store hash value for the store’s lifetime. This value can assist in account
            verification or profile matching responsibilities.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response-quote'
        '400':
          description: >-
            General response that points to an issue with the incoming request that means a valid response is unable to
            be returned.
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: >-
            Response to indicate that the merchant’s authentication credentials are invalid. The merchant will receive
            an update in their Store Logs.
          content:
            application/json:
              schema:
                description: Any type
        '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:
                description: Any type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request-quote'
  /adjust:
    post:
      operationId: adjustTaxQuote
      summary: Adjust Tax Quote
      description: >-
        Replace the persisted tax quote (identified by the given unique ID) with the provided quote request (represented
        by the **AdjustRequest**).


        Relevant for returns, partial refunds, and other Order modifications where there have been changes to the tax
        liabilities.


        The returned **Tax Quote** response is expected to be the same to a response returned by an equivalent response
        to **estimate** or **commit** methods.


        > 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.
      tags:
        - taxProvider
      parameters:
        - name: id
          in: query
          description: Unique ID identifying the existing, persisted tax quote that will be adjusted.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
            (developer.mozilla.org) credentials used to authenticate each API request to the tax provider from the
            associated store; set and update `username`, `password`, and optionally `profile`, using the [Update a
            Connection](/developer/api-reference/rest/integrations/tax-provider/tax-provider-connection/update-tax-provider-connection)
            request. `profile` is an optional field and will be used with supporting providers only.


            For more, see [developer-configured
            authentication](/developer/docs/overview/api-fundamentals/api-accounts#developer-configured-authentication)
            for Provider APIs.
          required: true
          schema:
            type: string
        - name: X-Bc-Store-Hash
          in: header
          description: >-
            BigCommerce will send through the store hash as part of all tax provider operations. Each BigCommerce store
            on the platform has a unique store hash value for the store’s lifetime. This value can assist in account
            verification or profile matching responsibilities.
          required: true
          schema:
            type: string
      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'
        '400':
          description: >-
            General response that points to an issue with the incoming request that means a valid response is unable to
            be returned.
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: >-
            Response to indicate that the merchant’s authentication credentials are invalid. The merchant will receive
            an update in their Store Logs.
          content:
            application/json:
              schema:
                description: Any type
        '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'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request-adjust'
servers:
  - url: https://your_app.example.com
    description: https://{app_domain}
components:
  schemas:
    request-item-tax-property:
      type: object
      properties:
        code:
          type: string
          description: Used by tax providers to programmatically identify a specific calculation input.
        value:
          type: string
          description: The value that will be factored into the tax providerʼs tax calculation rules, where supported.
      required:
        - code
        - value
      description: >-
        A simple key value pairing allowing merchants to provide an additional input into a tax providerʼs tax
        calculation.
      title: request-item-tax-property
    RequestQuoteCustomer:
      type: object
      properties:
        customer_id:
          type: string
          description: The ID of the shoppers customer account in BigCommerce. May be provided as a UUID.
        customer_group_id:
          type: string
          default: '0'
          description: >-
            The BigCommerce customer group ID assigned to this customer. The default value will be provided if the
            customer has no group assigned. May be provided as a UUID.
        taxability_code:
          type: string
          description: >-
            If applicable, the tax exemption code of the shopper’s customer account. A taxability code is intended to
            apply to multiple customers. This code should match the exemption codes provided by the third-party
            integration.
        tax_properties:
          type: array
          items:
            $ref: '#/components/schemas/request-item-tax-property'
          description: >-
            Any tax property values that have been associated with this customer. See [Tax Properties
            API](/developer/api-reference/rest/admin/management/tax/tax-properties) for more information on configuring
            tax properties.
      required:
        - customer_id
        - customer_group_id
      description: If the shopper is a registered customer in the merchant’s store, basic details for that customer.
      title: RequestQuoteCustomer
    AddressType:
      type: string
      enum:
        - RESIDENTIAL
        - COMMERCIAL
      title: AddressType
    Address:
      type: object
      properties:
        line1:
          type: string
          description: Primary street address.
        line2:
          type: string
          description: Apartment, unit, suite, building, floor, etc.
        city:
          type: string
          description: City, suburb, township, etc.
        region_name:
          type: string
          description: State, province, territory, etc.
        region_code:
          type: string
          description: >-
            If available, the short code/acronym for the region. For example, "CA" for "California" or "NSW" for "New
            South Wales".
        country_name:
          type: string
          description: The human-readable country name.
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 format country code.
        postal_code:
          type: string
          description: Postcode, ZIP, etc. Optional.
        company_name:
          type: string
          description: If this is a commercial address, the associated company’s name.
        type:
          $ref: '#/components/schemas/AddressType'
      description: >-
        Requests may have partial Address data. For example, the BigCommerce Cart page has the "Estimate Shipping & Tax"
        feature which is only expected to supply Country, Region and Postal Code.
      title: Address
    RequestDocumentShippingPrice:
      type: object
      properties:
        amount:
          type: number
          format: double
          description: 'Note: This amount will be **negative** for order-level refunds and may be **zero** for line item refunds.'
        tax_inclusive:
          type: boolean
          default: false
          description: 'Note: **Tax Inclusive** and **Tax Exclusive** prices cannot be added together.'
      required:
        - amount
        - tax_inclusive
      description: >-
        The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If the
        merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax provider will
        instead calculate the amount of tax that was already included in this price. For multiple quantities, this price
        includes that multiplication.
      title: RequestDocumentShippingPrice
    TaxClass:
      type: object
      properties:
        code:
          type: string
          description: >-
            The provider-specific tax code for this item. Items can be classified with tax codes relevant to each tax
            provider, configured by the merchant, and assigned to their products within BigCommerce. A tax code is
            intended to apply to multiple products. This code should match the tax codes provided by the third-party
            integration.
        class_id:
          type: string
          description: The ID of the tax class defined in the merchant’s BigCommerce store. May have a UUID value.
        name:
          type: string
          description: The human-readable name of this tax class in the merchant’s BigCommerce store.
      required:
        - code
        - class_id
        - name
      title: TaxClass
    shipping_type:
      type: string
      enum:
        - shipping
      description: The type of item for the line item in the document.
      title: shipping_type
    RequestDocumentShipping:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for this item used to map responses back to the corresponding item on the order.
        item_code:
          type: string
          description: >-
            The UPC or SKU of the item. The UPC is used when both UPC and SKU values are available on the item. Empty
            string if both UPC and SKU are not available.
        item_reference:
          type: string
          description: The SKU of the item. Empty string if SKU is not available.
        name:
          type: string
          description: A display name for this item.
        price:
          $ref: '#/components/schemas/RequestDocumentShippingPrice'
          description: >-
            The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If
            the merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax
            provider will instead calculate the amount of tax that was already included in this price. For multiple
            quantities, this price includes that multiplication.
        quantity:
          type: integer
        tax_class:
          $ref: '#/components/schemas/TaxClass'
        tax_exempt:
          type: boolean
          default: false
          description: >-
            Flag whether or not this item is always tax-exempt. For example, gift certificate purchases and order-level
            refunds are tax-exempt. Tax-exempt items are included in the request for auditing purposes. Tax-exempt items
            must have a tax amount of zero within the tax quote response.
        tax_properties:
          type: array
          items:
            $ref: '#/components/schemas/request-item-tax-property'
          description: >-
            Merchants may opt to include additional properties that a tax provider can choose to support, factoring
            these values into tax calculation. See [Tax Properties
            API](/developer/api-reference/rest/admin/management/tax/tax-properties) for more information on configuring
            tax properties.
        type:
          $ref: '#/components/schemas/shipping_type'
      required:
        - id
        - price
        - quantity
        - type
      description: Shipping line item present in each document request.
      title: RequestDocumentShipping
    RequestDocumentHandlingPrice:
      type: object
      properties:
        amount:
          type: number
          format: double
          description: 'Note: This amount will be **negative** for order-level refunds and may be **zero** for line item refunds.'
        tax_inclusive:
          type: boolean
          default: false
          description: 'Note: **Tax Inclusive** and **Tax Exclusive** prices cannot be added together.'
      required:
        - amount
        - tax_inclusive
      description: >-
        The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If the
        merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax provider will
        instead calculate the amount of tax that was already included in this price. For multiple quantities, this price
        includes that multiplication.
      title: RequestDocumentHandlingPrice
    handling_type:
      type: string
      enum:
        - handling
      description: The type of item for the line item in the document.
      title: handling_type
    RequestDocumentHandling:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for this item used to map responses back to the corresponding item on the order.
        item_code:
          type: string
          description: >-
            The UPC or SKU of the item. The UPC is used when both UPC and SKU values are available on the item. Empty
            string if both UPC and SKU are not available.
        item_reference:
          type: string
          description: The SKU of the item. Empty string if SKU is not available.
        name:
          type: string
          description: A display name for this item.
        price:
          $ref: '#/components/schemas/RequestDocumentHandlingPrice'
          description: >-
            The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If
            the merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax
            provider will instead calculate the amount of tax that was already included in this price. For multiple
            quantities, this price includes that multiplication.
        quantity:
          type: integer
        tax_class:
          $ref: '#/components/schemas/TaxClass'
        tax_exempt:
          type: boolean
          default: false
          description: >-
            Flag whether or not this item is always tax-exempt. For example, gift certificate purchases and order-level
            refunds are tax-exempt. Tax-exempt items are included in the request for auditing purposes. Tax-exempt items
            must have a tax amount of zero within the tax quote response.
        tax_properties:
          type: array
          items:
            $ref: '#/components/schemas/request-item-tax-property'
          description: >-
            Merchants may opt to include additional properties that a tax provider can choose to support, factoring
            these values into tax calculation. See [Tax Properties
            API](/developer/api-reference/rest/admin/management/tax/tax-properties) for more information on configuring
            tax properties.
        type:
          $ref: '#/components/schemas/handling_type'
      required:
        - id
        - price
        - quantity
        - type
      description: Handling line item present in each document request.
      title: RequestDocumentHandling
    RequestDocumentItemsItemsPrice:
      type: object
      properties:
        amount:
          type: number
          format: double
          description: 'Note: This amount will be **negative** for order-level refunds and may be **zero** for line item refunds.'
        tax_inclusive:
          type: boolean
          default: false
          description: 'Note: **Tax Inclusive** and **Tax Exclusive** prices cannot be added together.'
      required:
        - amount
        - tax_inclusive
      description: >-
        The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If the
        merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax provider will
        instead calculate the amount of tax that was already included in this price. For multiple quantities, this price
        includes that multiplication.
      title: RequestDocumentItemsItemsPrice
    item_type:
      type: string
      enum:
        - item
        - refund
        - fee
      description: |-
        The type of item for the line item in the document.

        Tax estimate requests for order-level refunds have an additional line item with the type `refund`.
      title: item_type
    RequestDocumentItemsItemsWrappingPrice:
      type: object
      properties:
        amount:
          type: number
          format: double
          description: 'Note: This amount will be **negative** for order-level refunds and may be **zero** for line item refunds.'
        tax_inclusive:
          type: boolean
          default: false
          description: 'Note: **Tax Inclusive** and **Tax Exclusive** prices cannot be added together.'
      required:
        - amount
        - tax_inclusive
      description: >-
        The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If the
        merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax provider will
        instead calculate the amount of tax that was already included in this price. For multiple quantities, this price
        includes that multiplication.
      title: RequestDocumentItemsItemsWrappingPrice
    wrapping_type:
      type: string
      enum:
        - wrapping
      description: The type of item for the line item in the document.
      title: wrapping_type
    RequestDocumentItemsItemsWrapping:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for this item used to map responses back to the corresponding item on the order.
        item_code:
          type: string
          description: >-
            The UPC or SKU of the item. The UPC is used when both UPC and SKU values are available on the item. Empty
            string if both UPC and SKU are not available.
        item_reference:
          type: string
          description: The SKU of the item. Empty string if SKU is not available.
        name:
          type: string
          description: A display name for this item.
        price:
          $ref: '#/components/schemas/RequestDocumentItemsItemsWrappingPrice'
          description: >-
            The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If
            the merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax
            provider will instead calculate the amount of tax that was already included in this price. For multiple
            quantities, this price includes that multiplication.
        quantity:
          type: integer
        tax_class:
          $ref: '#/components/schemas/TaxClass'
        tax_exempt:
          type: boolean
          default: false
          description: >-
            Flag whether or not this item is always tax-exempt. For example, gift certificate purchases and order-level
            refunds are tax-exempt. Tax-exempt items are included in the request for auditing purposes. Tax-exempt items
            must have a tax amount of zero within the tax quote response.
        tax_properties:
          type: array
          items:
            $ref: '#/components/schemas/request-item-tax-property'
          description: >-
            Merchants may opt to include additional properties that a tax provider can choose to support, factoring
            these values into tax calculation. See [Tax Properties
            API](/developer/api-reference/rest/admin/management/tax/tax-properties) for more information on configuring
            tax properties.
        type:
          $ref: '#/components/schemas/wrapping_type'
      required:
        - id
        - price
        - quantity
        - type
      description: Optional gift wrapping for items in the consignment.
      title: RequestDocumentItemsItemsWrapping
    RequestDocumentItemsItems:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for this item used to map responses back to the corresponding item on the order.
        item_code:
          type: string
          description: >-
            The UPC or SKU of the item. The UPC is used when both UPC and SKU values are available on the item. Empty
            string if both UPC and SKU are not available.
        item_reference:
          type: string
          description: The SKU of the item. Empty string if SKU is not available.
        name:
          type: string
          description: A display name for this item.
        price:
          $ref: '#/components/schemas/RequestDocumentItemsItemsPrice'
          description: >-
            The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If
            the merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax
            provider will instead calculate the amount of tax that was already included in this price. For multiple
            quantities, this price includes that multiplication.
        quantity:
          type: integer
        tax_class:
          $ref: '#/components/schemas/TaxClass'
        tax_exempt:
          type: boolean
          default: false
          description: >-
            Flag whether or not this item is always tax-exempt. For example, gift certificate purchases and order-level
            refunds are tax-exempt. Tax-exempt items are included in the request for auditing purposes. Tax-exempt items
            must have a tax amount of zero within the tax quote response.
        tax_properties:
          type: array
          items:
            $ref: '#/components/schemas/request-item-tax-property'
          description: >-
            Merchants may opt to include additional properties that a tax provider can choose to support, factoring
            these values into tax calculation. See [Tax Properties
            API](/developer/api-reference/rest/admin/management/tax/tax-properties) for more information on configuring
            tax properties.
        type:
          $ref: '#/components/schemas/item_type'
        wrapping:
          $ref: '#/components/schemas/RequestDocumentItemsItemsWrapping'
          description: Optional gift wrapping for items in the consignment.
      required:
        - id
        - price
        - quantity
        - type
      description: >-
        An **ItemRequest** represents required information relating to completing tax calculations for a specific line
        item.
      title: RequestDocumentItemsItems
    RequestDocumentDeliveryType:
      type: string
      enum:
        - digital
        - pickup
        - courier
        - postal
      description: >-
        The method by which the items in this consignment are delivered to the shopper. Digital consignments are always
        `digital`; physical consignments use the fulfillment method selected at checkout.
      title: RequestDocumentDeliveryType
    request-document:
      type: object
      properties:
        id:
          type: string
          description: >-
            A unique identifier for this consignment. This value can be expected to be unique within an individual quote
            request but may be duplicated within subsequent quote requests. A digital consignment will see a prefix
            **DigitalDelivery_** followed by the Order ID.
        billing_address:
          $ref: '#/components/schemas/Address'
        destination_address:
          $ref: '#/components/schemas/Address'
        origin_address:
          $ref: '#/components/schemas/Address'
        shipping:
          $ref: '#/components/schemas/RequestDocumentShipping'
          description: Shipping line item present in each document request.
        handling:
          $ref: '#/components/schemas/RequestDocumentHandling'
          description: Handling line item present in each document request.
        items:
          type: array
          items:
            $ref: '#/components/schemas/RequestDocumentItemsItems'
          description: >-
            Collection of one or more items contained within this consignment that need to be assessed for tax
            liabilities. An item may or may not have gift wrapping.
        delivery_type:
          $ref: '#/components/schemas/RequestDocumentDeliveryType'
          description: >-
            The method by which the items in this consignment are delivered to the shopper. Digital consignments are
            always `digital`; physical consignments use the fulfillment method selected at checkout.
      required:
        - id
        - destination_address
        - origin_address
        - shipping
        - handling
        - items
        - delivery_type
      description: >-
        Each **DocumentRequest** represents an order or part of an order of items fulfilled from a single origin address
        to a single destination address. In addition to shipping and billing details, a document request includes the
        collection of items in the shipment, with tax-relevant information for each item. Multi-address orders, in which
        items ship to or from multiple addresses, require at least one **DocumentRequest** per combination of
        sender-recipient addresses. These are similar to "consignments" or "shipments" in other BigCommerce APIs.
      title: request-document
    request-quote:
      type: object
      properties:
        id:
          type: string
          description: >-
            Unique ID of the taxable document (order, cart, quote, etc) this tax quote request is being generated for.
            Will remain consistent for the lifetime of the entity being estimated.
        currency_code:
          type: string
          description: ISO 4217 3 character currency code that all prices on this request are in.
        customer:
          $ref: '#/components/schemas/RequestQuoteCustomer'
          description: If the shopper is a registered customer in the merchant’s store, basic details for that customer.
        transaction_date:
          type: string
          format: date-time
          description: >-
            ISO 8601 formatted date the shopper placed this order. Tax quotes are expected to reflect taxes applicable
            on this date. Dates will be provided in UTC.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/request-document'
          description: >-
            One or more consignments containing items being purchased by the shopper, including shipping and handling
            fees that are charged for each consignment. Most orders will contain a single consignment (to a single
            shipping address), however the BigCommerce platform also supports "Multi-address orders" which allow
            shoppers to place a single order with items shipped to different addresses.
      required:
        - id
        - currency_code
        - customer
        - transaction_date
        - documents
      description: >-
        Each **QuoteRequest** represents an order. In addition to transaction details, it contains a `documents` array
        of one or more **DocumentRequest** objects, which represent distinct combinations of origin and fulfillment
        addresses and the tax-relevant contents of those consignments. This is similar to an "order" in other
        BigCommerce APIs.
      title: request-quote
    SalesTax:
      type: object
      properties:
        name:
          type: string
          description: >-
            The human-readable name of this tax. Used for reporting. Depending on store configuration, may also be
            visible in the itemization of taxes at checkout, on invoices, and in the control panel. May not be empty.
        rate:
          type: number
          format: double
          description: >-
            Decimal tax rate applied by this component tax rate. Tax rates support up to four decimal places. For
            example "0.1" for 10% and "0.0125" for 1.25%.
        amount:
          type: number
          format: double
          description: >-
            The absolute amount of tax applied to the item this SalesTax component is attached to, for this component
            rate. For example, if an item was $10 and this was a 5% component tax rate, the amount would be 0.50 (50
            cents)
        tax_class:
          $ref: '#/components/schemas/TaxClass'
        id:
          type: string
          description: >-
            Optional unique identifier for this sales tax, describing the relevant tax classification rule on the tax
            provider platform.


            Supplying an identifier allows BigCommerce to group related taxes together from all items in the order.


            This identifier is persisted by BigCommerce and may be desirable for auditing purposes between BigCommerce
            and the tax provider. Currently supports persisting integer values only (the string type indicates we may
            support UUID values in the future).
      required:
        - name
        - rate
        - amount
      title: SalesTax
    response-taxprice:
      type: object
      properties:
        amount_inclusive:
          type: number
          format: double
          description: >-
            The price of this line item inclusive of tax. Must be equal to **amount_exclusive** + **total_tax**.
            Although the primary type is `double`, this field also accepts a numeric string (for example, `"675.00"`).
        amount_exclusive:
          type: number
          format: double
          description: >-
            The price of this line item exclusive of tax. Must be equal to **amount_inclusive** - **total_tax**.
            Although the primary type is `double`, this field also accepts a numeric string (for example, `"450.00"`).
        total_tax:
          type: number
          format: double
          description: >-
            The total amount of tax that applied to this line item. Must be equal to **amount_inclusive** -
            **amount_exclusive**. Although the primary type is `double`, this field also accepts a numeric string (for
            example, `"225.00"`).
        tax_rate:
          type: number
          format: double
          description: >-
            The total tax rate that applied to this item. This is the aggregated rate of the individual rates in
            **sales_tax_summary**.
        sales_tax_summary:
          type: array
          items:
            $ref: '#/components/schemas/SalesTax'
          description: Breakdown of the sales taxes that applied to this item.
      required:
        - amount_inclusive
        - amount_exclusive
        - total_tax
        - tax_rate
        - sales_tax_summary
      title: response-taxprice
    ResponseDocumentItemsItemsWrapping:
      type: object
      properties:
        id:
          type: string
          description: >-
            A unique identifier for the line item these tax liabilities are calculated for. Must match the corresponding
            request line item ID.
        price:
          $ref: '#/components/schemas/response-taxprice'
        type:
          $ref: '#/components/schemas/wrapping_type'
      required:
        - id
        - price
        - type
      description: Optional gift wrapping for items in the consignment.
      title: ResponseDocumentItemsItemsWrapping
    ResponseDocumentItemsItems:
      type: object
      properties:
        id:
          type: string
          description: >-
            A unique identifier for the line item these tax liabilities are calculated for. Must match the corresponding
            request line item ID.
        price:
          $ref: '#/components/schemas/response-taxprice'
        type:
          $ref: '#/components/schemas/item_type'
        wrapping:
          $ref: '#/components/schemas/ResponseDocumentItemsItemsWrapping'
          description: Optional gift wrapping for items in the consignment.
      required:
        - id
        - price
        - type
      description: |-
        The tax liabilities calculated for a specific item.

        Note: Tax liabilities should be calculated with **quantity** accounted for.
      title: ResponseDocumentItemsItems
    ResponseDocumentShipping:
      type: object
      properties:
        id:
          type: string
          description: >-
            A unique identifier for the line item these tax liabilities are calculated for. Must match the corresponding
            request line item ID.
        price:
          $ref: '#/components/schemas/response-taxprice'
        type:
          $ref: '#/components/schemas/shipping_type'
      required:
        - id
        - price
        - type
      description: Shipping line item present in each document request.
      title: ResponseDocumentShipping
    ResponseDocumentHandling:
      type: object
      properties:
        id:
          type: string
          description: >-
            A unique identifier for the line item these tax liabilities are calculated for. Must match the corresponding
            request line item ID.
        price:
          $ref: '#/components/schemas/response-taxprice'
        type:
          $ref: '#/components/schemas/handling_type'
      required:
        - id
        - price
        - type
      description: Handling line item present in each document request.
      title: ResponseDocumentHandling
    response-document:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for this consignment. Must match the ID of the corresponding Document Request.
        external_id:
          type: string
          description: >-
            An optional unique identifier for the document stored in the external provider’s system. Currently not used
            in any end-to-end operation, but may be logged by BigCommerce and thus be helpful when resolving issues.
        items:
          type: array
          items:
            $ref: '#/components/schemas/ResponseDocumentItemsItems'
          description: >-
            Collection of items contained within this consignment that have had tax liabilities calculated. An item may
            or may not have gift wrapping.
        shipping:
          $ref: '#/components/schemas/ResponseDocumentShipping'
          description: Shipping line item present in each document request.
        handling:
          $ref: '#/components/schemas/ResponseDocumentHandling'
          description: Handling line item present in each document request.
      required:
        - id
        - items
        - shipping
        - handling
      title: response-document
    response-quote:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the tax quote that was requested. This value must either match the ID of the
            requested quote or be an external ID on the tax provider’s system. This value will be used for future adjust
            and void operations.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/response-document'
          description: >-
            Represents an order quote or part of an order quote of tax-relevant items fulfilled from a single origin
            address to a single destination address, including arrays of shipping and handling fee objects for each
            item. Most order quotes contain a single document; however, BigCommerce supports "multi-address orders",
            which may come from or go to distinct sets of addresses and thus require multiple documents per quote.
      required:
        - id
        - documents
      title: response-quote
    Tax Provider_voidTaxQuote_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: Tax Provider_voidTaxQuote_Response_200
    RequestAdjustCustomer:
      type: object
      properties:
        customer_id:
          type: string
          description: The ID of the shoppers customer account in BigCommerce. May be provided as a UUID.
        customer_group_id:
          type: string
          default: '0'
          description: >-
            The BigCommerce customer group ID assigned to this customer. The default value will be provided if the
            customer has no group assigned. May be provided as a UUID.
        taxability_code:
          type: string
          description: >-
            If applicable, the tax exemption code of the shopper’s customer account. A taxability code is intended to
            apply to multiple customers. This code should match the exemption codes provided by the third-party
            integration.
        tax_properties:
          type: array
          items:
            $ref: '#/components/schemas/request-item-tax-property'
          description: >-
            Any tax property values that have been associated with this customer. See [Tax Properties
            API](/developer/api-reference/rest/admin/management/tax/tax-properties) for more information on configuring
            tax properties.
      required:
        - customer_id
        - customer_group_id
      description: If the shopper is a registered customer in the merchant’s store, basic details for that customer.
      title: RequestAdjustCustomer
    request-adjust:
      type: object
      properties:
        adjust_description:
          type: string
          description: >-
            Specifies the reason for the adjustment operation, for auditing purposes. May be a custom, user-entered
            description.
        id:
          type: string
          description: >-
            Unique ID of the taxable document (order, cart, quote, etc) this tax quote request is being generated for.
            Will remain consistent for the lifetime of the entity being estimated.
        currency_code:
          type: string
          description: ISO 4217 3 character currency code that all prices on this request are in.
        customer:
          $ref: '#/components/schemas/RequestAdjustCustomer'
          description: If the shopper is a registered customer in the merchant’s store, basic details for that customer.
        transaction_date:
          type: string
          format: date-time
          description: >-
            ISO 8601 formatted date the shopper placed this order. Tax quotes are expected to reflect taxes applicable
            on this date. Dates will be provided in UTC.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/request-document'
          description: >-
            One or more consignments containing items being purchased by the shopper, including shipping and handling
            fees that are charged for each consignment. Most orders will contain a single consignment (to a single
            shipping address), however the BigCommerce platform also supports "Multi-address orders" which allow
            shoppers to place a single order with items shipped to different addresses.
      required:
        - id
        - currency_code
        - customer
        - transaction_date
        - documents
      description: >-
        An **AdjustRequest** contains the same data as a standard **QuoteRequest** with added detail of the adjustment
        operation.
      title: request-adjust
  securitySchemes:
    Authorization:
      type: http
      scheme: basic
      description: >-
        The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)
        (developer.mozilla.org) credentials used to authenticate each API request to the tax provider from the
        associated store; set and update `username`, `password`, and optionally `profile`, using the [Update a
        Connection](/developer/api-reference/rest/integrations/tax-provider/tax-provider-connection/update-tax-provider-connection)
        request. `profile` is an optional field and will be used with supporting providers only.


        For more, see [developer-configured
        authentication](/developer/docs/overview/api-fundamentals/api-accounts#developer-configured-authentication) for
        Provider APIs.
