Tax zones

Define the countries and subdivisions where market tax rates apply.

Tax zones belong to a market and use read_markets / write_markets. A zone may cover only countries assigned to that market. Geography is validated and overlap is rejected, so an address resolves to one specific zone or the optional default zone. Rates owned by a deleted zone are removed only after the confirmation handshake reports the impact.

Match an order to a jurisdiction#

A tax zone describes where a set of rates applies. Its countries must belong to the market, and subdivisions use the platform's canonical country-subdivision codes. Specific zones are matched before the optional default zone. If no zone matches and no default exists, Tringify returns zero zone tax and marks the calculation as unmatched.

Tringify checks tax ID formats and check digits only. It does not verify registrations or exemptions with tax authorities. You are responsible for your tax settings and for approving exempt customers. A tax ID never grants an exemption. An online customer must sign in to the customer account you marked tax_exempt, and the matched tax zone must have an enabled exemption with effect exempt. Otherwise an entered tax ID is recorded with invoice_only and tax is charged, even in an exempt zone. With effect invoice_only, tax is always charged. Staff can explicitly approve an exemption for an individual order. Orders record the applied source as customer_flag, staff_order or none. Saved IDs must pass the zone type, format and optional pattern rules; invalid saved IDs are ignored without blocking checkout. Shopper-entered IDs are sent with quotes and receive field errors. EU VAT uses national published checksum rules; Czech nine-digit birth numbers and Latvian personal numbers receive structural checks only. Canadian BN uses MOD10. Order edits recalculate the identity type, applied exemption source and GSTIN state mismatch with the tax totals.

Create a zone#

json

// POST /api/2025-01/markets/{marketId}/tax-zones
{
  "name": "California",
  "description": "California shipping addresses",
  "countries": ["US"],
  "subdivisions": ["US-CA"],
  "is_default": false
}

Use the available-countries endpoint when building geography controls. It returns market countries together with their subdivision choices and existing zone claims. Business-tax exemption settings belong to the zone because the applicable treatment depends on the jurisdiction that matched the order. Tringify assigns priority itself, in creation order; zones never overlap, so it does not change which zone an address matches.

Endpoints#

Get tax zone limits

GET read_markets

Fetch tax-zone validation limits.

Returns the live tax-zone limits — the per-market cap and the name, description, and search length caps (all counted in characters), plus list pagination bounds. Read this instead of hardcoding numbers.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Response

200

Sample response

{
  "success": true,
  "data": {
    "limits": {
      "max_per_market": 50,
      "name_max_length": 100,
      "description_max_length": 500,
      "list_page_size": 20,
      "list_max_limit": 100,
      "search_max_length": 200,
      "page_size_options": [10, 20, 50]
    }
  }
}

Get available countries

GET read_markets

Fetch the market's countries with their zone-claim status.

Returns every country in the market stamped with its claim status across the market's zones: fully_claimed (a country fallback already exists, named in claimed_by_zone) and claimed_subdivisions (subdivisions other zones already took). Both can be present for one country. A country fallback does not prevent creating a zone for its unclaimed subdivisions; it only prevents another zone from covering that country whole, that is, listing it with none of its subdivisions. Build zone pickers from this — the server's verdict is the only source of what is still claimable. Pass exclude_zone_id when editing a zone so its own claims don't count against it.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`

Query parameters

Name	Type	Description
`exclude_zone_id`	`uuid`	Zone id whose own claims to ignore — pass the zone being edited. Example: `7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
404 MARKET_NOT_FOUND
Market does not exist in this store.

Response

200

Sample response

{
  "success": true,
  "data": {
    "countries": [
      {
        "code": "DE",
        "name": "Germany",
        "fully_claimed": true,
        "claimed_by_zone": "European Union"
      },
      {
        "code": "IN",
        "name": "India",
        "fully_claimed": false,
        "claimed_subdivisions": ["IN-KA"]
      }
    ]
  }
}

List tax zones

GET read_markets

List a market's tax zones.

Returns paginated tax zones, searchable by name. Each zone carries rate_count — how many rate lines it holds — and is_default marks the market's catch-all zone if one exists. A market is not required to have a default zone: addresses no zone covers are sold with zero tax, and the tax calculation reports tax_zone_unmatched. Pagination and search bounds come from the limits endpoint.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`

Query parameters

Name	Type	Description
`page`	`integer`	Page number. Example: `1`
`per_page`	`integer`	Page size (service-capped). Example: `20`
`search`	`string`	Search by tax zone name. Example: `europe`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
404 MARKET_NOT_FOUND
Market does not exist in this store.

Response

200

Sample response

{
  "success": true,
  "data": {
    "tax_zones": [{
    "id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
    "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "European Union",
    "description": "EU member states",
    "countries": ["DE", "FR"],
    "subdivisions": [],
    "is_default": false,
    "priority": 0,
    "tax_exemption": {
      "enabled": true,
      "type": "eu_vat",
      "effect": "invoice_only",
      "type_mismatch": false,
      "checkout_text": "Enter your EU VAT number."
    },
    "rate_count": 2,
    "created_at": "2026-07-01T10:15:00Z",
    "updated_at": "2026-07-09T18:40:00Z"
  }],
    "total": 1
  }
}

Create a tax zone

POST write_markets

Create a tax zone in a market.

Creates a tax zone. name is required and unique within the market. A regular zone needs at least one country or subdivision; every country must belong to the market, every subdivision must be a known ISO subdivision belonging to a selected country, and duplicate subdivision claims or duplicate whole-country claims are rejected. A whole-country zone with an empty subdivisions array can coexist with state-specific zones: state matches win, then the country zone covers the rest. For example, a zone with countries: ["IN"] and subdivisions: ["IN-UP"] handles Uttar Pradesh; a second zone with countries: ["IN"] and subdivisions: [] handles the rest of India. Only the matching zone’s rates apply. One zone can list whole countries and subdivisions of other countries together: each listed country with at least one listed subdivision is claimed only for those subdivisions, and a listed country with none of its subdivisions listed is claimed whole, except subdivisions other zones claim. So countries: ["IN", "US"] with subdivisions: ["IN-UP"] covers Uttar Pradesh and all of the US. Addresses are matched with country and state trimmed and case-insensitive, and a state matches a subdivision zone whether the address gives its ISO code with or without the country (UP, up, IN-UP) or its full name (Uttar Pradesh). When a country has subdivision zones and the address has no state, or one that isn't recognised, tax is not taken from the country zone: the tax calculation reports tax_zone_unmatched: true with tax_zone_needs_state: true and reports unresolved tax until a recognised state is given. Operational order creation is refused with ORDER_TAX_ZONE_NEEDS_STATE and details.tax_zone_needs_state: true; it cannot create a payable zero-tax order. A recognised state that no subdivision zone covers uses the whole-country zone. Setting is_default instead creates the market's catch-all zone for unmatched addresses. The optional tax_exemption object sets the business treatment: exempt removes tax only for a buyer marked tax_exempt by the merchant, and invoice_only keeps tax and marks the order for a business invoice when such a buyer, or any buyer who enters a tax ID, checks out. Fires tax_zones/create.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Tax zone name — unique within the market. Example: `European Union`
`description`	`string`	Internal description. Example: `EU member states`
`countries`	`array`	ISO country codes belonging to the market. A listed country with none of its subdivisions listed is covered whole, except subdivisions assigned to other zones; a listed country with listed subdivisions is covered only for those subdivisions. Only one zone may cover a country whole, but it can coexist with subdivision zones. Empty countries and subdivisions are only valid for the default zone. Example: `["DE", "FR"]`
`subdivisions`	`array`	ISO subdivision codes (e.g. IN-KA). Each must belong to a selected country and not be claimed by another zone. Listing a subdivision limits the zone to the listed subdivisions of that country only; other listed countries are still covered whole. Example: `["IN-KA", "IN-MH"]`
`is_default`	`boolean`	Make this the market's catch-all zone for addresses no other zone covers. The default zone must have no countries or subdivisions; promoting one demotes the previous default in the same write. Example: `false`
`tax_exemption`	`object`	Business tax exemption for this zone: `{enabled, type, effect, checkout_text, custom_label, custom_placeholder, custom_pattern, custom_example, translations}`. Supported `type` values are `eu_vat`, `uk_vat`, `gstin`, `abn`, `gst_hst`, `ein`, and `custom`. `effect` is `exempt` (charge no tax, only for a buyer marked tax_exempt by the merchant; with inclusive prices, discounts, fees and thresholds settle once on the commercial amounts, then included tax is removed from items, shipping, COD and checkout fees. For example, 120 including 20% less a fixed 12 discount becomes 90. The order keeps `is_tax_included: true` with `tax_exempt: true` and zero `tax_total`) or `invoice_only` (keep tax and mark the order for a business invoice, for a merchant-approved exempt customer or any buyer who enters a tax ID at checkout). A tax ID never removes tax by itself, including in an exempt zone: tax is charged and invoice_only is recorded. Tringify performs offline format and check-digit checks only, with no live registration or exemption verification; merchants are responsible for tax settings and exemption approvals. Types must fit at least one zone country (market country for a default zone): eu_vat in EU countries, uk_vat in GB, gstin in IN, abn in AU, gst_hst in CA, ein in US, custom anywhere. Existing mismatches are returned as tax_exemption.type_mismatch=true without modifying stored settings; saving such a zone is refused. To turn the treatment off, send `{"enabled": false}`; leaving `tax_exemption` out keeps the saved treatment. `checkout_text` is limited to 100 characters. For `custom`, `custom_label` is required and limited to 50 characters; `custom_placeholder` is optional and limited to 50 characters. custom_pattern is optional RE2, at most 256 UTF-8 bytes, matched against the entire normalized ID; no pattern permits free text. custom_example is optional, at most 100 characters, and must pass the pattern. translations maps en/de/es/fr/it to custom_label, custom_placeholder and checkout_text with the same limits. Built-in labels use checkout copy translations. Values are uppercased and spaces, dots and dashes removed before storing. EU VAT requires an EU country prefix (EL for Greece), national format and published check-digit rules (structural checks only for Czech nine-digit birth numbers and Latvian personal numbers); UK VAT uses GB with 9 or 12 digits and mod-97/9755 checks; GSTIN checks 15 characters, state 01-38/97/99, PAN shape and base-36 checksum; ABN checks 11 digits with weighted modulus 89; GST/HST requires a 9-digit BN with MOD10 checksum plus RT and a nonzero four-digit account number; EIN accepts NN-NNNNNNN. A valid GSTIN with a different Indian tax-address state is accepted and records tax_id_state_mismatch=true on the order. Example: `{"enabled": true, "type": "eu_vat", "effect": "invoice_only", "checkout_text": "Enter your EU VAT number."}`

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
400 TAX_ID_ZONE_TYPE_MISMATCH
The type fits no zone country (no market country for a default zone). Existing mismatches are returned on reads without modifying stored settings.
400 TAX_ID_PATTERN_INVALID
Custom RE2 pattern is invalid or exceeds 256 UTF-8 bytes.
400 TAX_ID_INVALID
Custom example does not match the normalized full-value pattern.
400 TAX_ZONE_NAME_REQUIRED
Name is empty after normalization.
400 TAX_ZONE_NAME_TOO_LONG
Name exceeds the limit.
400 TAX_ZONE_DESCRIPTION_TOO_LONG
Description exceeds the limit.
400 TAX_ZONE_LIMIT_REACHED
The market's tax zone cap has been reached.
400 ZONE_NEEDS_REGION
A regular zone must include at least one country or subdivision.
400 ZONE_DEFAULT_NO_REGIONS
The default zone must have no countries or subdivisions — it covers all remaining regions.
400 ZONE_COUNTRY_INVALID
A country is not valid for this zone (unknown code or not in the market).
400 ZONE_SUBDIVISION_INVALID
A subdivision code is unknown.
400 ZONE_SUBDIVISION_NEEDS_COUNTRY
Subdivisions require their country to be selected in the zone.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision belongs to a country not selected in this zone.
400 ZONE_COUNTRY_TAKEN
A country this zone covers whole (none of its subdivisions listed) is already covered whole by another zone.
400 ZONE_SUBDIVISION_TAKEN
A subdivision is already assigned to another zone.
400 MARKET_TAX_EXEMPTION_TYPE_INVALID
Tax_exemption.type is not a supported tax ID kind.
400 MARKET_TAX_EXEMPTION_EFFECT_INVALID
Tax_exemption.effect must be exempt or invoice_only.
400 MARKET_CHECKOUT_TEXT_TOO_LONG
Tax_exemption.checkout_text exceeds the limit.
400 MARKET_CUSTOM_LABEL_REQUIRED
Tax_exemption.custom_label is required when type is custom.
400 MARKET_CUSTOM_LABEL_TOO_LONG
Tax_exemption.custom_label exceeds the limit.
400 MARKET_CUSTOM_PLACEHOLDER_TOO_LONG
Tax_exemption.custom_placeholder exceeds the limit.
404 MARKET_NOT_FOUND
Market does not exist in this store.
409 TAX_ZONE_NAME_DUPLICATE
A tax zone with this name already exists in the market.

Response

201

Sample response

{
  "success": true,
  "data": {
    "tax_zone": {
    "id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
    "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "European Union",
    "description": "EU member states",
    "countries": ["DE", "FR"],
    "subdivisions": [],
    "is_default": false,
    "priority": 0,
    "tax_exemption": {
      "enabled": true,
      "type": "eu_vat",
      "effect": "invoice_only",
      "type_mismatch": false,
      "checkout_text": "Enter your EU VAT number."
    },
    "rate_count": 2,
    "created_at": "2026-07-01T10:15:00Z",
    "updated_at": "2026-07-09T18:40:00Z"
  }
  }
}

Get a tax zone

GET read_markets

Fetch one tax zone.

Returns the tax zone.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`taxZoneId` required	`uuid`	Tax zone id. Example: `7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
404 MARKET_NOT_FOUND
Market does not exist in this store.
404 NOT_FOUND
Tax zone does not exist in this market.

Response

200

Sample response

{
  "success": true,
  "data": {
    "tax_zone": {
    "id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
    "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "European Union",
    "description": "EU member states",
    "countries": ["DE", "FR"],
    "subdivisions": [],
    "is_default": false,
    "priority": 0,
    "tax_exemption": {
      "enabled": true,
      "type": "eu_vat",
      "effect": "invoice_only",
      "type_mismatch": false,
      "checkout_text": "Enter your EU VAT number."
    },
    "rate_count": 2,
    "created_at": "2026-07-01T10:15:00Z",
    "updated_at": "2026-07-09T18:40:00Z"
  }
  }
}

Update a tax zone

PUT write_markets

Update a tax zone.

Updates the zone's name, description, regions, default flag, and business tax exemption. Region rules match create: regular zones need at least one country or subdivision, all regions must be claimable, and the default zone must have none. Promoting a zone to default demotes the previous default in the same write. Fires tax_zones/update.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`taxZoneId` required	`uuid`	Tax zone id. Example: `7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Tax zone name — unique within the market. Example: `European Union`
`description`	`string`	Internal description. Example: `EU member states`
`countries`	`array`	ISO country codes belonging to the market. A listed country with none of its subdivisions listed is covered whole, except subdivisions assigned to other zones; a listed country with listed subdivisions is covered only for those subdivisions. Only one zone may cover a country whole, but it can coexist with subdivision zones. Empty countries and subdivisions are only valid for the default zone. Example: `["DE", "FR"]`
`subdivisions`	`array`	ISO subdivision codes (e.g. IN-KA). Each must belong to a selected country and not be claimed by another zone. Listing a subdivision limits the zone to the listed subdivisions of that country only; other listed countries are still covered whole. Example: `["IN-KA", "IN-MH"]`
`is_default`	`boolean`	Make this the market's catch-all zone for addresses no other zone covers. The default zone must have no countries or subdivisions; promoting one demotes the previous default in the same write. Example: `false`
`tax_exemption`	`object`	Business tax exemption for this zone: `{enabled, type, effect, checkout_text, custom_label, custom_placeholder, custom_pattern, custom_example, translations}`. Supported `type` values are `eu_vat`, `uk_vat`, `gstin`, `abn`, `gst_hst`, `ein`, and `custom`. `effect` is `exempt` (charge no tax, only for a buyer marked tax_exempt by the merchant; with inclusive prices, discounts, fees and thresholds settle once on the commercial amounts, then included tax is removed from items, shipping, COD and checkout fees. For example, 120 including 20% less a fixed 12 discount becomes 90. The order keeps `is_tax_included: true` with `tax_exempt: true` and zero `tax_total`) or `invoice_only` (keep tax and mark the order for a business invoice, for a merchant-approved exempt customer or any buyer who enters a tax ID at checkout). A tax ID never removes tax by itself, including in an exempt zone: tax is charged and invoice_only is recorded. Tringify performs offline format and check-digit checks only, with no live registration or exemption verification; merchants are responsible for tax settings and exemption approvals. Types must fit at least one zone country (market country for a default zone): eu_vat in EU countries, uk_vat in GB, gstin in IN, abn in AU, gst_hst in CA, ein in US, custom anywhere. Existing mismatches are returned as tax_exemption.type_mismatch=true without modifying stored settings; saving such a zone is refused. To turn the treatment off, send `{"enabled": false}`; leaving `tax_exemption` out keeps the saved treatment. `checkout_text` is limited to 100 characters. For `custom`, `custom_label` is required and limited to 50 characters; `custom_placeholder` is optional and limited to 50 characters. custom_pattern is optional RE2, at most 256 UTF-8 bytes, matched against the entire normalized ID; no pattern permits free text. custom_example is optional, at most 100 characters, and must pass the pattern. translations maps en/de/es/fr/it to custom_label, custom_placeholder and checkout_text with the same limits. Built-in labels use checkout copy translations. Values are uppercased and spaces, dots and dashes removed before storing. EU VAT requires an EU country prefix (EL for Greece), national format and published check-digit rules (structural checks only for Czech nine-digit birth numbers and Latvian personal numbers); UK VAT uses GB with 9 or 12 digits and mod-97/9755 checks; GSTIN checks 15 characters, state 01-38/97/99, PAN shape and base-36 checksum; ABN checks 11 digits with weighted modulus 89; GST/HST requires a 9-digit BN with MOD10 checksum plus RT and a nonzero four-digit account number; EIN accepts NN-NNNNNNN. A valid GSTIN with a different Indian tax-address state is accepted and records tax_id_state_mismatch=true on the order. Example: `{"enabled": true, "type": "eu_vat", "effect": "invoice_only", "checkout_text": "Enter your EU VAT number."}`

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
400 TAX_ID_ZONE_TYPE_MISMATCH
The type fits no zone country (no market country for a default zone). Existing mismatches are returned on reads without modifying stored settings.
400 TAX_ID_PATTERN_INVALID
Custom RE2 pattern is invalid or exceeds 256 UTF-8 bytes.
400 TAX_ID_INVALID
Custom example does not match the normalized full-value pattern.
400 TAX_ZONE_NAME_REQUIRED
Name is empty after normalization.
400 TAX_ZONE_NAME_TOO_LONG
Name exceeds the limit.
400 TAX_ZONE_DESCRIPTION_TOO_LONG
Description exceeds the limit.
400 TAX_ZONE_LIMIT_REACHED
The market's tax zone cap has been reached.
400 ZONE_NEEDS_REGION
A regular zone must include at least one country or subdivision.
400 ZONE_DEFAULT_NO_REGIONS
The default zone must have no countries or subdivisions — it covers all remaining regions.
400 ZONE_COUNTRY_INVALID
A country is not valid for this zone (unknown code or not in the market).
400 ZONE_SUBDIVISION_INVALID
A subdivision code is unknown.
400 ZONE_SUBDIVISION_NEEDS_COUNTRY
Subdivisions require their country to be selected in the zone.
400 ZONE_SUBDIVISION_NOT_IN_COUNTRY
A subdivision belongs to a country not selected in this zone.
400 ZONE_COUNTRY_TAKEN
A country this zone covers whole (none of its subdivisions listed) is already covered whole by another zone.
400 ZONE_SUBDIVISION_TAKEN
A subdivision is already assigned to another zone.
400 MARKET_TAX_EXEMPTION_TYPE_INVALID
Tax_exemption.type is not a supported tax ID kind.
400 MARKET_TAX_EXEMPTION_EFFECT_INVALID
Tax_exemption.effect must be exempt or invoice_only.
400 MARKET_CHECKOUT_TEXT_TOO_LONG
Tax_exemption.checkout_text exceeds the limit.
400 MARKET_CUSTOM_LABEL_REQUIRED
Tax_exemption.custom_label is required when type is custom.
400 MARKET_CUSTOM_LABEL_TOO_LONG
Tax_exemption.custom_label exceeds the limit.
400 MARKET_CUSTOM_PLACEHOLDER_TOO_LONG
Tax_exemption.custom_placeholder exceeds the limit.
404 MARKET_NOT_FOUND
Market does not exist in this store.
409 TAX_ZONE_NAME_DUPLICATE
A tax zone with this name already exists in the market.
404 NOT_FOUND
Tax zone does not exist in this market.

Response

200

Sample response

{
  "success": true,
  "data": {
    "tax_zone": {
    "id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
    "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "European Union",
    "description": "EU member states",
    "countries": ["DE", "FR"],
    "subdivisions": [],
    "is_default": false,
    "priority": 0,
    "tax_exemption": {
      "enabled": true,
      "type": "eu_vat",
      "effect": "invoice_only",
      "type_mismatch": false,
      "checkout_text": "Enter your EU VAT number."
    },
    "rate_count": 2,
    "created_at": "2026-07-01T10:15:00Z",
    "updated_at": "2026-07-09T18:40:00Z"
  }
  }
}

Delete a tax zone

DELETE write_markets

Delete a tax zone.

Deletes the tax zone. If it still has rate lines, the first call returns CONFIRMATION_REQUIRED; retry with confirmed and the returned confirmation_token. The token is for that number of rate lines: if lines are added before the retry, the zone asks for confirmation again. Cascaded rate lines do not fire individual tax_rates/delete events, so re-sync rates after the tax_zones/delete event. The default zone can't be deleted while it is the default. After deletion, addresses are matched again: any remaining state-specific zone wins, then a whole-country zone, then the default zone. If none matches, no tax is applied.

Path parameters

Name	Type	Description
`marketId` required	`uuid`	Market id. Example: `9a1f2c3d-4e5f-6789-abcd-ef0123456789`
`taxZoneId` required	`uuid`	Tax zone id. Example: `7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`confirmed`	`boolean`	On a confirmation retry, set this to true and send the returned confirmation_token. Omit it on the first request.
`confirmation_token`	`string`	Token from the CONFIRMATION_REQUIRED response. Omit it on the first request and resend the exact same id selection when using it.

Errors

400 STORE_API_INVALID_REQUEST_BODY
marketId must be a valid UUID.
409 CONFIRMATION_REQUIRED
The zone still has rate lines. Retry with confirmed and the returned confirmation_token.
400 TAX_ZONE_DEFAULT_DELETE_LOCKED
The default zone can't be deleted while it is the default.
404 MARKET_NOT_FOUND
Market does not exist in this store.
404 NOT_FOUND
Tax zone does not exist in this market.

Response

200

Sample response

{
  "success": true,
  "data": { "success": true }
}

Webhook events#

Tax-zone events are published for every write, and the saved change and its event become visible together. Making a zone the default also publishes an update for the zone that stops being the default. Update payloads contain the complete saved geography and exemption configuration; delete payloads retain the removed zone's identity.

Tax zone created

EVENT tax_zones/create App scope: read_markets Staff permission: markets:write

Subscribe to receive the saved tax zone after it is created in a market.

Payload fields

Field	Type	Description
`tax_zone.id`	`string`	Always present The stable tax zone id.
`tax_zone.market_id`	`string`	Selectable in the Payload builder The market where this zone is matched.
`tax_zone.name`	`string`	Selectable in the Payload builder The merchant-facing tax zone name.
`tax_zone.description`	`string`	Selectable in the Payload builder The optional explanation of the jurisdiction this zone covers.
`tax_zone.countries`	`array`	Selectable in the Payload builder ISO 3166-1 alpha-2 country codes claimed by the zone.
`tax_zone.subdivisions`	`array`	Selectable in the Payload builder Canonical country-subdivision codes claimed by the zone.
`tax_zone.is_default`	`boolean`	Selectable in the Payload builder Whether this zone catches addresses not matched by a more specific zone.
`tax_zone.priority`	`integer`	Selectable in the Payload builder The order in which the zone was created, assigned by Tringify (newer zones are higher). Zones never overlap, so it does not change which zone an address matches.
`tax_zone.tax_exemption.type_mismatch`	`boolean`	Selectable in the Payload builder
`tax_zone.tax_exemption.custom_pattern`	`string`	Selectable in the Payload builder
`tax_zone.tax_exemption.custom_example`	`string`	Selectable in the Payload builder
`tax_zone.tax_exemption.translations`	`object`	Selectable in the Payload builder
`tax_zone.tax_exemption.enabled`	`boolean`	Selectable in the Payload builder Whether this zone's business tax treatment is on.
`tax_zone.tax_exemption.type`	`string`	Selectable in the Payload builder The exemption configuration type used by this zone.
`tax_zone.tax_exemption.effect`	`string`	Selectable in the Payload builder The business tax treatment: exempt removes tax for a buyer verified as tax exempt; invoice_only keeps tax and marks the order for a business invoice for such a buyer or any buyer who enters a tax ID.
`tax_zone.tax_exemption.checkout_text`	`string`	Selectable in the Payload builder The customer-facing guidance shown when exemption details are requested.
`tax_zone.tax_exemption.custom_label`	`string`	Selectable in the Payload builder The custom customer-facing label for the exemption field.
`tax_zone.tax_exemption.custom_placeholder`	`string`	Selectable in the Payload builder The custom placeholder shown in the exemption field.
`tax_zone.created_at`	`string`	Selectable in the Payload builder When the tax zone was created.
`tax_zone.updated_at`	`string`	Selectable in the Payload builder When the tax zone last changed.

Payload shape

Sample payload

{
  "tax_zone": {
    "countries": [
      "US"
    ],
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "California shipping addresses",
    "id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
    "is_default": false,
    "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "California",
    "priority": 10,
    "subdivisions": [
      "US-CA"
    ],
    "tax_exemption": {
      "checkout_text": "Enter the tax exemption details shown on your certificate.",
      "custom_example": "...",
      "custom_label": "Exemption certificate number",
      "custom_pattern": "...",
      "custom_placeholder": "CA-EXEMPT-1042",
      "effect": "exempt",
      "enabled": true,
      "translations": "...",
      "type": "custom",
      "type_mismatch": false
    },
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Tax zone updated

EVENT tax_zones/update App scope: read_markets Staff permission: markets:write

Subscribe to receive the current tax zone after its geography, priority, default status, or exemption settings change.

Payload fields

Field	Type	Description
`tax_zone.id`	`string`	Always present The stable tax zone id.
`tax_zone.market_id`	`string`	Selectable in the Payload builder The market where this zone is matched.
`tax_zone.name`	`string`	Selectable in the Payload builder The merchant-facing tax zone name.
`tax_zone.description`	`string`	Selectable in the Payload builder The optional explanation of the jurisdiction this zone covers.
`tax_zone.countries`	`array`	Selectable in the Payload builder ISO 3166-1 alpha-2 country codes claimed by the zone.
`tax_zone.subdivisions`	`array`	Selectable in the Payload builder Canonical country-subdivision codes claimed by the zone.
`tax_zone.is_default`	`boolean`	Selectable in the Payload builder Whether this zone catches addresses not matched by a more specific zone.
`tax_zone.priority`	`integer`	Selectable in the Payload builder The order in which the zone was created, assigned by Tringify (newer zones are higher). Zones never overlap, so it does not change which zone an address matches.
`tax_zone.tax_exemption.type_mismatch`	`boolean`	Selectable in the Payload builder
`tax_zone.tax_exemption.custom_pattern`	`string`	Selectable in the Payload builder
`tax_zone.tax_exemption.custom_example`	`string`	Selectable in the Payload builder
`tax_zone.tax_exemption.translations`	`object`	Selectable in the Payload builder
`tax_zone.tax_exemption.enabled`	`boolean`	Selectable in the Payload builder Whether this zone's business tax treatment is on.
`tax_zone.tax_exemption.type`	`string`	Selectable in the Payload builder The exemption configuration type used by this zone.
`tax_zone.tax_exemption.effect`	`string`	Selectable in the Payload builder The business tax treatment: exempt removes tax for a buyer verified as tax exempt; invoice_only keeps tax and marks the order for a business invoice for such a buyer or any buyer who enters a tax ID.
`tax_zone.tax_exemption.checkout_text`	`string`	Selectable in the Payload builder The customer-facing guidance shown when exemption details are requested.
`tax_zone.tax_exemption.custom_label`	`string`	Selectable in the Payload builder The custom customer-facing label for the exemption field.
`tax_zone.tax_exemption.custom_placeholder`	`string`	Selectable in the Payload builder The custom placeholder shown in the exemption field.
`tax_zone.created_at`	`string`	Selectable in the Payload builder When the tax zone was created.
`tax_zone.updated_at`	`string`	Selectable in the Payload builder When the tax zone last changed.

Payload shape

Sample payload

{
  "tax_zone": {
    "countries": [
      "US"
    ],
    "created_at": "2026-06-09T12:00:00+05:30",
    "description": "California shipping addresses",
    "id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
    "is_default": false,
    "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "California",
    "priority": 10,
    "subdivisions": [
      "US-CA"
    ],
    "tax_exemption": {
      "checkout_text": "Enter the tax exemption details shown on your certificate.",
      "custom_example": "...",
      "custom_label": "Exemption certificate number",
      "custom_pattern": "...",
      "custom_placeholder": "CA-EXEMPT-1042",
      "effect": "exempt",
      "enabled": true,
      "translations": "...",
      "type": "custom",
      "type_mismatch": false
    },
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Tax zone deleted

EVENT tax_zones/delete App scope: read_markets Staff permission: markets:write

Subscribe to remove a deleted tax zone from your integration. Its rate lines are removed with it without separate tax_rates/delete events, so use the zone id to refresh affected rates.

Payload fields

Field	Type	Description
`tax_zone.id`	`string`	Always present The stable tax zone id.
`tax_zone.market_id`	`string`	Selectable in the Payload builder The market where this zone is matched.
`tax_zone.name`	`string`	Selectable in the Payload builder The merchant-facing tax zone name.

Payload shape

Sample payload

{
  "tax_zone": {
    "id": "7c9e4f2b-1a3d-4e5f-8b6c-2d0e1f3a4b5c",
    "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
    "name": "California"
  }
}