openapi: 3.0.0
info:
  title: BigCommerce Tax Properties
  description: Include tax properties and product tax properties in tax calculations.
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  version: ''
security:
  - X-Auth-Token: []
tags:
  - name: Product Tax Properties
  - name: Tax Properties
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
paths:
  /tax/properties:
    parameters:
      - $ref: '#/components/parameters/Accept'
    get:
      tags:
        - Tax Properties
      summary: BigCommerce Get Tax Properties
      description: Retrieve all tax properties defined in this store.
      operationId: getTaxProperties
      parameters:
        - $ref: '#/components/parameters/idin'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Property'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
        '400':
          description: Request parameters invalid
    put:
      tags:
        - Tax Properties
      summary: BigCommerce Update Tax Properties
      description: >-
        Update one or more tax properties. Only fields specified will be
        adjusted.
      operationId: updateTaxProperties
      parameters:
        - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PropertyPUT'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Property'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
        '422':
          description: The request body does not meet specifications.
    post:
      tags:
        - Tax Properties
      summary: BigCommerce Create Tax Properties
      description: >-
        Create one or more tax properties. A **code** and a **display name**
        must be included when creating tax properties.
      operationId: createTaxProperties
      parameters:
        - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PropertyPOST'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Property'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
        '422':
          description: The request body does not meet specifications.
    delete:
      tags:
        - Tax Properties
      summary: BigCommerce Delete Tax Properties
      description: >-
        Delete one or multiple tax properties. A tax property must have zero
        usages within product tax properties before you can delete it.
      operationId: deleteTaxProperties
      parameters:
        - $ref: '#/components/parameters/idin_required'
      responses:
        '204':
          description: No Content
        '400':
          description: Request parameters invalid
        '409':
          description: Tax Property is in use and cannot be deleted.
  /tax/products/properties:
    parameters:
      - $ref: '#/components/parameters/Accept'
    get:
      tags:
        - Product Tax Properties
      summary: BigCommerce Get Product Tax Properties
      description: >-
        Retrieve the tax properties that are associated with one or more
        products.
      operationId: getProductsTaxProperties
      parameters:
        - $ref: '#/components/parameters/product_idin'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProductTaxProperty'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
        '400':
          description: Request parameters invalid
    put:
      tags:
        - Product Tax Properties
      summary: BigCommerce Update Product Tax Properties
      description: >-
        Update the tax properties associated with one or more products. This
        operation will be additive to any tax property values already associated
        with the product, overwriting any existing tax property values.
      operationId: updateProductTaxProperties
      parameters:
        - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ProductTaxProperty'
            examples:
              Example:
                value:
                  - product_id: 157
                    tax_properties:
                      A-123456789: '26'
                      B-6731789: '200'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProductTaxProperty'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
        '422':
          description: The request body does not meet specifications.
    delete:
      tags:
        - Product Tax Properties
      summary: BigCommerce Delete Product Tax Properties
      description: Delete tax properties that are associated with one or more products.
      operationId: deleteProductTaxProperties
      parameters:
        - $ref: '#/components/parameters/product_idin'
      responses:
        '204':
          description: No Content
        '400':
          description: Request parameters invalid
components:
  parameters:
    Accept:
      name: Accept
      in: header
      required: true
      description: >-
        The [MIME
        type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)
        of the response body.
      schema:
        type: string
        default: application/json
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: >-
        The [MIME
        type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)
        of the request body.
      schema:
        type: string
        default: application/json
    product_idin:
      name: product_id:in
      in: query
      required: true
      description: >-
        ID of product. To target multiple products, provide a comma-separated
        list of IDs such as `12,34,56`
      schema:
        type: string
    idin:
      name: id:in
      in: query
      required: false
      description: >-
        ID of tax property. To target multiple tax properties, provide a
        comma-separated list of IDs such as `12,34,56`
      schema:
        type: string
    idin_required:
      name: id:in
      in: query
      required: true
      description: >-
        ID of tax property. To target multiple tax properties, provide a
        comma-separated list of IDs such as `12,34,56`
      schema:
        type: string
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--|:--|:-|

        |  Information & Settings | modify | `store_v2_information` |

        |  Information & Settings | read-only | `store_v2_information_read_only`
        |


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

        | `X-Auth-Token` | `access_token` | For more about API accounts that
        generate `access_token`s, see our [Guide to API
        Accounts](/docs/start/authentication/api-accounts). |


        ### Further reading


        For example requests and more information about authenticating
        BigCommerce APIs, see [Authentication and Example
        Requests](/docs/start/authentication#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API
        Accounts](/docs/start/authentication/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status
        Codes](/docs/start/about/status-codes).
      type: apiKey
      in: header
  schemas:
    Property:
      type: object
      properties:
        id:
          type: integer
          description: An internal identifier used by other operations.
          example: 1
          readOnly: true
        code:
          type: string
          description: >-
            The unique string programmatically references this unique tax
            property by the tax provider. Merchants should liaise with their tax
            provider to explore supported values and functions.
          example: A-123456789
        display_name:
          type: string
          description: >-
            The human-readable name for this property. This string will be
            displayed on the Products screen as a field label.
          example: Example Tax Property 1
        description:
          type: string
          description: >-
            Optional. Additional detail about this tax property may help guide
            merchants. This string will be displayed on the Products screen as a
            tooltip associated with the relevant field.
          example: Food Industry
        created_at:
          type: string
          description: Datetime.
          format: date-time
          example: 2022-07-21T19:33:57Z
          readOnly: true
        updated_at:
          type: string
          description: Datetime.
          format: date-time
          example: 2022-07-21T19:33:57Z
          readOnly: true
    PropertyPOST:
      type: object
      properties:
        code:
          type: string
          description: >-
            The unique string programmatically references this unique tax
            property by the tax provider. Merchants should liaise with their tax
            provider to explore supported values and functions.
          example: A-123456789
        display_name:
          type: string
          description: >-
            The human-readable name for this property. This string will be
            displayed on the Products screen as a field label.
          example: Example Tax Property 1
        description:
          type: string
          description: >-
            Additional detail about this tax property may help guide merchants.
            This string will be displayed on the Products screen as a tooltip
            associated with the relevant field.
          example: Food Industry
      required:
        - code
        - display_name
    PropertyPUT:
      type: object
      properties:
        id:
          type: integer
          description: An internal identifier used by other operations.
          example: 1
        code:
          type: string
          description: >-
            The unique string programmatically references this unique tax
            property by the tax provider. Merchants should liaise with their tax
            provider to explore supported values and functions.
          example: A-123456789
        display_name:
          type: string
          description: >-
            The human-readable name for this property. This string will be
            displayed on the Products screen as a field label.
          example: Example Tax Property 1
        description:
          type: string
          description: >-
            Optional. Additional detail about this tax property may help guide
            merchants. This string will be displayed on the Products screen as a
            tooltip associated with the relevant field.
          example: Food Industry
      required:
        - id
    ProductTaxProperty:
      type: object
      description: A collection of tax property values associated with a product.
      properties:
        product_id:
          type: integer
          description: >-
            A reference to the product that the product tax properties are
            associated with.
          example: 157
        tax_properties:
          type: object
          description: >-
            A simple key-value pairing. The tax property must be defined to
            associate a value. These values will be sent to the active tax
            provider during Tax Provider API operations whenever the associated
            product is included in the operation.
          example:
            A-123456789: '26'
            B-6731789: '200'
      required:
        - product_id
        - tax_properties
    MetaOpen:
      title: Response meta
      type: object
      properties: {}
      additionalProperties: true
      description: Response metadata.