BigCommerce Tax Zones API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Tax Zones 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 Zones
paths:
  /tax/zones:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      parameters:
      - $ref: '#/components/parameters/zoneIdIn'
      tags:
      - Tax Zones
      summary: BigCommerce Get Tax Zones
      description: Retrieve a selection of tax zones when you provide a list of tax zone IDs. Otherwise, retrieve all tax zones defined on the store.
      operationId: getTaxZones
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tax_Zone'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
              examples:
                Example 1:
                  value:
                    data:
                    - id: 2
                      name: example zone
                      enabled: false
                      price_display_settings:
                        show_inclusive: false
                        show_both_on_detail_view: false
                        show_both_on_list_view: false
                      shopper_target_settings:
                        locations:
                        - country_code: AR
                          subdivision_codes:
                          - T
                          - V
                          postal_codes: []
                        - country_code: AU
                          subdivision_codes:
                          - WA
                          - VIC
                          postal_codes: []
                        customer_groups:
                        - 2
                    meta: {}
    put:
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      tags:
      - Tax Zones
      summary: BigCommerce Update Tax Zones
      description: Update one or more tax zones. Only the tax zone `id` field is required. Fields unspecified by the request will retain their current state.
      operationId: updateTaxZones
      requestBody:
        $ref: '#/components/requestBodies/Tax_ZoneArray'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tax_Zone'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
              examples:
                Example 1:
                  value:
                    data:
                    - id: 23
                      name: Australia
                      enabled: false
                      price_display_settings:
                        show_inclusive: false
                        show_both_on_detail_view: false
                        show_both_on_list_view: false
                      shopper_target_settings:
                        locations:
                        - country_code: AU
                          subdivision_codes: []
                          postal_codes:
                          - '2238'
                          - '2173'
                        customer_groups:
                        - 2
                    meta: {}
    post:
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      tags:
      - Tax Zones
      summary: BigCommerce Create Tax Zones
      description: 'Create one or more tax zones.


        > #### Note

        > You cannot create a default tax zone.'
      operationId: createTaxZones
      requestBody:
        $ref: '#/components/requestBodies/Tax_ZoneArrayPOST'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tax_Zone'
                  meta:
                    $ref: '#/components/schemas/MetaOpen'
              examples:
                Example 1:
                  value:
                    data:
                    - id: 2
                      name: example zone
                      enabled: true
                      price_display_settings:
                        show_inclusive: true
                        show_both_on_detail_view: true
                        show_both_on_list_view: true
                      shopper_target_settings:
                        locations:
                        - country_code: AR
                          subdivision_codes:
                          - T
                          - V
                          postal_codes: []
                        - country_code: AU
                          subdivision_codes:
                          - WA
                          - VIC
                          postal_codes: []
                        customer_groups:
                        - 0
                    meta: {}
    delete:
      parameters:
      - $ref: '#/components/parameters/zoneIdIn'
      tags:
      - Tax Zones
      summary: BigCommerce Delete Tax Zones
      description: 'Delete one or more tax zones. Deleting a tax zone removes all associated tax rates.


        > You must specify which zone(s) to delete using the `id:in` query parameter.'
      operationId: deleteTaxZones
      responses:
        '204':
          description: No Content
components:
  schemas:
    Tax_Zone:
      type: object
      x-examples: {}
      properties:
        id:
          type: integer
          description: Tax Zone ID. Internal identifier used to get, update, or delete a specific tax zone.
        name:
          type: string
          description: The human-readable name for this tax zone. The name appears in the store control panel.
          example: Australia
        enabled:
          type: boolean
          description: Indicates whether a tax zone is enabled. Tax operations are only for enabled zones.
          default: true
        price_display_settings:
          type: object
          description: Settings that describe how a store displays prices to shoppers matched with this tax zone.
          properties:
            show_inclusive:
              type: boolean
              description: Indicates whether to show prices as tax inclusive or tax exclusive to shoppers matched with this tax zone.
            show_both_on_detail_view:
              type: boolean
              description: Indicates whether to show both tax inclusive and tax exclusive prices when viewing product detail; for example, on product pages. This view applies to shoppers matched with this tax zone.
            show_both_on_list_view:
              type: boolean
              description: Indicates whether to show both tax inclusive and tax exclusive prices when viewing a list of products; for example, on category and brand pages. This view applies to shoppers matched with this tax zone.
        shopper_target_settings:
          type: object
          description: Settings that describe which shoppers match this tax zone and help determine the most appropriate target for a shopper. You cannot define shopper target settings for the default tax zone because it must accommodate all shoppers who donʼt qualify for any other zone.
          properties:
            locations:
              type: array
              description: A tax zone may target shoppers in one or more locations.
              items:
                type: object
                properties:
                  country_code:
                    type: string
                    example: AU
                    description: Two-letter ISO 3166-1 country code
                  subdivision_codes:
                    type: array
                    example:
                    - NSW
                    - QLD
                    description: Three-letter ISO 3166-2 subdivision code
                    items:
                      type: string
                  postal_codes:
                    type: array
                    example:
                    - '2234'
                    - '2170'
                    items:
                      type: string
            customer_groups:
              type: array
              description: One or more customer groups that a tax zone targets. Empty array if zone applies to all customers.
              items:
                type: integer
    Tax_ZonePOST:
      type: object
      properties:
        name:
          type: string
          description: The human-readable name for this tax zone. The name appears in the store control panel.
          example: Australia
        enabled:
          type: boolean
          description: Indicates whether a tax zone is enabled. Tax operations are only for enabled zones.
          default: true
        price_display_settings:
          type: object
          description: Settings that describe how a store displays prices to shoppers matched with this tax zone.
          properties:
            show_inclusive:
              type: boolean
              description: Indicates whether to show prices as tax inclusive or tax exclusive to shoppers matched with this tax zone.
            show_both_on_detail_view:
              type: boolean
              description: Indicates whether to show both tax inclusive and tax exclusive prices when viewing product detail; for example, on product pages. This view applies to shoppers matched with this tax zone.
              default: false
            show_both_on_list_view:
              type: boolean
              description: Indicates whether to show both tax inclusive and tax exclusive prices when viewing a list of products; for example, on category and brand pages. This view applies to shoppers matched with this tax zone.
              default: false
          required:
          - show_inclusive
        shopper_target_settings:
          type: object
          description: Settings that describe which shoppers match this tax zone and help determine the most appropriate target for a shopper.
          properties:
            locations:
              type: array
              description: A tax zone may target shoppers in one or more locations.
              items:
                type: object
                properties:
                  country_code:
                    type: string
                    example: AU
                    description: Two-letter ISO 3166-1 country code
                  subdivision_codes:
                    type: array
                    example:
                    - NSW
                    - QLD
                    description: Three-letter ISO 3166-2 subdivision code
                    items:
                      type: string
                  postal_codes:
                    type: array
                    example:
                    - '2234'
                    - '2170'
                    items:
                      type: string
            customer_groups:
              type: array
              description: One or more customer groups that a tax zone targets. Empty array if zone applies to all customers.
              items:
                type: integer
          required:
          - locations
      required:
      - name
    MetaOpen:
      title: Response meta
      type: object
      properties: {}
      additionalProperties: true
      description: Response metadata.
    Tax_ZonePUT:
      type: object
      properties:
        id:
          type: integer
          description: Tax Zone ID. Internal identifier used to get, update, or delete a specific tax zone.
        name:
          type: string
          description: The human-readable name for this tax zone. The name appears in the store control panel.
          example: Australia
        enabled:
          type: boolean
          description: Indicates whether a tax zone is enabled. Tax operations are only for enabled zones.
          default: true
        price_display_settings:
          type: object
          description: Settings that describe how a store displays prices to shoppers matched with this tax zone.
          properties:
            show_inclusive:
              type: boolean
              description: Indicates whether to show prices as tax inclusive or tax exclusive to shoppers matched with this tax zone.
            show_both_on_detail_view:
              type: boolean
              description: Indicates whether to show both tax inclusive and tax exclusive prices when viewing product detail; for example, on product pages. This view applies to shoppers matched with this tax zone.
            show_both_on_list_view:
              type: boolean
              description: Indicates whether to show both tax inclusive and tax exclusive prices when viewing a list of products; for example, on category and brand pages. This view applies to shoppers matched with this tax zone.
        shopper_target_settings:
          type: object
          description: Settings that describe which shoppers match this tax zone and help determine the most appropriate target for a shopper. You cannot define shopper target settings for the default tax zone because it must accommodate all shoppers who donʼt qualify for any other zone.
          properties:
            locations:
              type: array
              description: A tax zone may target shoppers in one or more locations.
              items:
                type: object
                properties:
                  country_code:
                    type: string
                    example: AU
                    description: Two-letter ISO 3166-1 country code
                  subdivision_codes:
                    type: array
                    example:
                    - NSW
                    - QLD
                    description: Three-letter ISO 3166-2 subdivision code
                    items:
                      type: string
                  postal_codes:
                    type: array
                    example:
                    - '2234'
                    - '2170'
                    items:
                      type: string
            customer_groups:
              type: array
              description: One or more customer groups that a tax zone targets. Empty array if zone applies to all customers.
              items:
                type: integer
      required:
      - id
  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
    zoneIdIn:
      name: id:in
      in: query
      schema:
        type: array
        items:
          type: integer
        minItems: 1
      style: form
      explode: false
      description: Filter by tax zone `id`. Use a comma-separated CSV string of IDs for multiple tax zones. For example, `5` or `12,34,56`.
      required: false
    Content-Type:
      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
  requestBodies:
    Tax_ZoneArray:
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Tax_ZonePUT'
          examples:
            Example 1:
              value:
              - id: 3
                name: Australia
                enabled: false
                price_display_settings:
                  show_inclusive: false
                  show_both_on_detail_view: false
                  show_both_on_list_view: false
                shopper_target_settings:
                  locations:
                  - country_code: AU
                    postal_codes:
                    - '2238'
                    - '2173'
                  customer_groups:
                  - 2
      required: true
    Tax_ZoneArrayPOST:
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Tax_ZonePOST'
          examples:
            Example 1:
              value:
              - name: example zone
                enabled: true
                price_display_settings:
                  show_inclusive: true
                  show_both_on_detail_view: true
                  show_both_on_list_view: true
                shopper_target_settings:
                  locations:
                  - country_code: AR
                    subdivision_codes:
                    - T
                    - V
                  - country_code: AU
                    subdivision_codes:
                    - WA
                    - VIC
                  customer_groups:
                  - 0
      required: true
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

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

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

        | Information & Settings  | modify     | `store_v2_information`          |


        ### 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