BigCommerce Tax Rates & Zones is a feature within the BigCommerce platform that allows merchants to easily set up and manage tax rates for their online store. With this tool, merchants can create and customize tax rates based on their specific business needs and the locations of their customers.
openapi: 3.0.0
info:
title: BigCommerce Tax Rates & Zones
version: 1.0.0
description: Manage manual tax rates and zones.
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
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
tags:
- name: Tax Rates
- 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
/tax/rates:
parameters:
- $ref: '#/components/parameters/Accept'
get:
tags:
- Tax Rates
summary: BigCommerce Get Tax Rates
description: Retrieve a list of tax rates.
operationId: getTaxRates
parameters:
- $ref: '#/components/parameters/rateIdIn'
- $ref: '#/components/parameters/taxZoneIdIn'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Tax_Rate'
meta:
$ref: '#/components/schemas/Meta'
examples: {}
put:
parameters:
- $ref: '#/components/parameters/Content-Type'
tags:
- Tax Rates
summary: BigCommerce Update Tax Rates
description: >-
Update one or more tax rates. Only the tax rate `id` field is required.
Fields unspecified by the request will retain their current state.
operationId: updateTaxRates
requestBody:
$ref: '#/components/requestBodies/Tax_RateArray'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Tax_Rate'
meta:
$ref: '#/components/schemas/MetaOpen'
examples:
Example 1:
value:
data:
- id: 3
tax_zone_id: 2
name: Sales Tax
enabled: true
priority: 1
class_rates:
- rate: 10
tax_class_id: 0
meta: {}
post:
parameters:
- $ref: '#/components/parameters/Content-Type'
tags:
- Tax Rates
summary: BigCommerce Create Tax Rates
description: >-
Create one or more tax rates. Tax rates must be associated with a
`tax_zone_id`.
operationId: createTaxRates
requestBody:
$ref: '#/components/requestBodies/Tax_RateArrayPOST'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Tax_Rate'
meta:
$ref: '#/components/schemas/MetaOpen'
examples:
Example 1:
value:
data:
- id: 3
tax_zone_id: 2
name: Sales Tax
enabled: true
priority: 1
class_rates:
- rate: 5
tax_class_id: 0
meta: {}
delete:
parameters:
- $ref: '#/components/parameters/rateIdIn'
tags:
- Tax Rates
summary: BigCommerce Delete Tax Rates
description: >-
Delete one or more tax rates.
> You must specify which rate(s) to delete using the `id:in` query
parameter.
operationId: deleteTaxRates
responses:
'204':
description: No Content
components:
requestBodies:
Tax_RateArray:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Tax_RatePUT'
examples:
Example 1:
value:
- id: 3
tax_zone_id: 2
name: Sales Tax
enabled: true
priority: 1
class_rates:
- rate: 10
tax_class_id: 0
required: true
Tax_RateArrayPOST:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Tax_RatePOST'
examples:
Example 1:
value:
- tax_zone_id: 2
name: Sales Tax
enabled: true
priority: 1
class_rates:
- rate: 5
tax_class_id: 0
required: true
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
type: apiKey
in: header
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).
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_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
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
Tax_Rate:
type: object
properties:
class_rates:
type: array
description: >-
Tax rates for tax classes. You must assign at least one tax rate for
each tax class defined on a store.
items:
type: object
properties:
rate:
type: number
description: The tax rate that you apply to the items in a tax class.
example: 5
tax_class_id:
type: integer
description: >-
ID of a tax class. You must associate a tax rate with a tax
class. The rate will apply to all the items in this tax class.
example: 1
enabled:
type: boolean
description: >-
Indicates whether a tax rate is enabled. Tax operations are only for
enabled zones.
default: true
id:
type: integer
description: >-
Tax Rate ID. Internal identifier to update and delete a specific tax
rate.
example: 3
name:
type: string
description: >-
The human-readable name for this tax zone. The name appears in the
store control panel and may be visible to shoppers, depending on
store tax settings.
example: Sales Tax
priority:
type: integer
description: Allows for compounding tax rates, common in certain jurisdictions.
default: 1
tax_zone_id:
type: integer
description: >-
ID of an associated tax zone. You must associate a tax rate with a
tax zone.
example: 2
x-examples: {}
Tax_RatePUT:
type: object
properties:
class_rates:
type: array
description: >-
Tax rates for tax classes. You must assign at least one tax rate for
each tax class defined on a store.
items:
type: object
properties:
rate:
type: number
description: The tax rate that you apply to the items in a tax class.
example: 5
tax_class_id:
type: integer
description: >-
ID of a tax class. You must associate a tax rate with a tax
class. The rate will apply to all the items in this tax class.
example: 1
enabled:
type: boolean
description: >-
Indicates whether a tax rate is enabled. Tax operations are only for
enabled zones.
default: true
id:
type: integer
description: >-
Tax Rate ID. Internal identifier to update and delete a specific tax
rate.
example: 3
name:
type: string
description: >-
The human-readable name for this tax zone. The name appears in the
store control panel and may be visible to shoppers, depending on
store tax settings.
example: Sales Tax
priority:
type: integer
description: Allows for compounding tax rates, common in certain jurisdictions.
default: 1
tax_zone_id:
type: integer
description: >-
ID of an associated tax zone. You must associate a tax rate with a
tax zone.
example: 2
required:
- id
Tax_RatePOST:
type: object
properties:
class_rates:
type: array
description: >-
Tax rates for tax classes. You must assign at least one tax rate for
each tax class defined on a store.
items:
type: object
properties:
rate:
type: number
description: The tax rate that you apply to the items in a tax class.
example: 5
tax_class_id:
type: integer
description: >-
ID of a tax class. You must associate a tax rate with a tax
class. The rate will apply to all items in this tax class.
example: 1
required:
- rate
- tax_class_id
enabled:
type: boolean
description: >-
Indicates whether a tax rate is enabled. Tax operations are only for
enabled zones.
default: true
name:
type: string
description: >-
The human-readable name for this tax zone. The name appears in the
store control panel and may be visible to shoppers, depending on
store tax settings.
example: Sales Tax
priority:
type: integer
description: Allows for compounding tax rates, common in certain jurisdictions.
default: 1
tax_zone_id:
type: integer
description: >-
ID of an associated tax zone. You must associate a tax rate with a
tax zone.
example: 2
required:
- class_rates
- name
- tax_zone_id
Meta:
type: object
properties:
pagination:
type: object
properties:
total:
type: integer
count:
type: integer
per_page:
type: integer
current_page:
type: integer
total_pages:
type: integer
links:
type: object
properties:
current:
type: string
x-examples:
Example 1:
pagination:
total: 1
count: 1
per_page: 50
current_page: 1
total_pages: 1
links:
current: '?tax_zone_id%3Ain=1&page=1&limit=50'
title: Meta
MetaOpen:
title: Response meta
type: object
properties: {}
additionalProperties: true
description: Response metadata.
parameters:
storeHash:
name: store_hash
in: path
required: true
description: Permanent ID of the BigCommerce store.
schema:
type: string
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
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
idIn:
name: id:in
in: query
schema:
type: array
items:
type: integer
minItems: 1
style: form
explode: false
description: >-
Filter by `id`. Use a comma-separated CSV string of IDs for multiple
selections. For example, `5` or `12,34,56`.
required: false
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
rateIdIn:
name: id:in
in: query
schema:
type: array
items:
type: integer
minItems: 1
style: form
explode: false
description: >-
Filter by tax rate `id`. Use a comma-separated CSV string of IDs for
multiple tax rates. For example, `5` or `12,34,56`.
required: false
taxZoneIdIn:
name: tax_zone_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
security:
- X-Auth-Token: []