Thanks for being patient while we implement your feedback to improve the developer experience.

Get Tax Zones

GET /tax/zones

Request

Retrieve a selection of tax zones when you provide a list of tax zone IDs. Otherwise, retrieve all tax zones defined on the store.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • in

    Filter by tax zone id. Use a comma-separated CSV string of IDs for multiple tax zones. For example, 5 or 12,34,56.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/tax/zones' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

OK

Body

object | application/json

  • data    array[object]

  • meta    object

Example 1

{
  "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": {}
}

Update Tax Zones

PUT /tax/zones

Request

Update one or more tax zones. Only the tax zone id field is required. Fields unspecified by the request will retain their current state.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

array | application/json

  • id    integer

    Tax Zone ID. Internal identifier used to get, update, or delete a specific tax zone.

  • name    string

    The human-readable name for this tax zone. The name displays on the merchant's control panel.

    Example: Australia

  • enabled    boolean

    Indicates whether a tax zone is enabled. Tax operations are only for enabled zones.

    Default: true

  • price_display_settings    object

    Settings that describe how a store displays prices to shoppers matched with this tax zone.

  • shopper_target_settings    object

    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.

Response

OK

Body

object | application/json

  • data    array[object]

  • meta    object

Example 1

{
  "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": {}
}

Create Tax Zones

POST /tax/zones

Request

Create one or more tax zones.

<!-- theme: info -->

Note

You cannot create a default tax zone.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

array | application/json

  • name    string

    The human-readable name for this tax zone. The name displays on the merchant's control panel.

    Example: Australia

  • enabled    boolean

    Indicates whether a tax zone is enabled. Tax operations are only for enabled zones.

    Default: true

  • price_display_settings    object

    Settings that describe how a store displays prices to shoppers matched with this tax zone.

  • shopper_target_settings    object

    Settings that describe which shoppers match this tax zone and help determine the most appropriate target for a shopper.

Response

OK

Body

object | application/json

  • data    array[object]

  • meta    object

Example 1

{
  "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 Tax Zones

DELETE /tax/zones

Request

Delete one or more tax zones. Deleting a tax zone removes all associated tax rates.

<!-- theme:info -->

You must specify which zone(s) to delete using the id:in query parameter.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • in

    Filter by tax zone id. Use a comma-separated CSV string of IDs for multiple tax zones. For example, 5 or 12,34,56.

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/tax/zones' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

No Content