Tax Zone Object

{
  "id": "tz_b621028608fc454b996d903c636dfa0e",
  "country": "CA",
  "region": "QC",
  "rates": [
      {
          "id": "tr_e21196aace0c4453a0f2431ef3cede09",
          "name": "GST",
          "rate": "0.05",
          "tax_number_for_invoice": null,
          "tax_group_overrides": {
	          "tg_123": "0.00",
	          "tg_456": "0.10123"
          }
      },
      {
          "id": "tr_92e2206d667441f6b0b3c0930d050f10",
          "name": "QST",
          "rate": "0.09975",
          "tax_number_for_invoice": "Legal tax number to display on invoices",
          "tax_group_overrides": null
      }
    ]
}

Field

Description

id string

Unique identifier of the tax zone. All ids are prefixed tz_.

country string

ISO 3166-1 alpha-2 country code to which the rates inside the zone will be applied. The country is not editable after the zone’s creation.

region string

Optional precision of the zone with their two letter state or province code. The region is not editable after the zone’s creation.

rates array

Applied rates for a given country + region combo. At least one rate must be in the zone. See Rates table below.

Rates

Field

Description

id string

Unique identifier of a tax rate. All ids are prefixed tr_.

name string

Display name of the tax rate. This will be displayed in the merchant’s orders dashboard.

rate string

Decimal string of the tax applied on a given price e.g., "0.05".

tax_number_for_invoice string

Optional string to display alongside invoices tax line item breakdowns.

tax_group_overrides object

Optional record of tax group ids and their overridden rate e.g., { tg_123: "0.04" }.

🚧

Unique Constraint

The country + region combination MUST be unique per store. Our API will 400 if a new zone duplicates an existing one.