Tax

/api/integration/tax — domain: Tax

Three endpoints. Jurisdictions and areas model where tax applies and at what rate; GST posting rates model a second scheme keyed on posting groups.

Domain. Tax, which owns rates and the calculation applied to basket and order lines.

PUT /jurisdictions

Purpose. A taxing jurisdiction and its rates over time, per tax group.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "code": "VIC",
      "description": "Victoria",
      "rates": [
        {
          "taxGroupCode": "GST",
          "ratePercent": 10.0,
          "effectiveDate": "2026-07-01"
        },
        {
          "taxGroupCode": "FREE",
          "ratePercent": 0.0,
          "effectiveDate": "2026-07-01"
        }
      ]
    }
  ]
}

Field	Type	Required	Description
code	string	Yes	The natural key. Referenced by a tax area's jurisdictionCodes
description	string		Human-readable name for the jurisdiction
rates[]	array		The rates this jurisdiction levies, one per tax group per effective date

rates[]

Field	Type	Required	Description
taxGroupCode	string	Yes	Matches a product's taxGroupCode from Catalogue
ratePercent	decimal	Yes	The rate as a percentage — send 10.0, not 0.10
effectiveDate	date		When the rate takes effect. Date only. Part of the key

rates is a snapshot keyed on taxGroupCode plus effectiveDate. Send the complete history you want retained; a rate absent from the payload is removed. Keep past rates in the payload — removing them changes how historical orders are explained.

PUT /areas

Purpose. Group jurisdictions into an area, which is what a customer or ship-to address is tagged with.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "code": "AU-VIC",
      "description": "Australia — Victoria",
      "jurisdictionCodes": [
        "VIC",
        "AU-FED"
      ]
    }
  ]
}

Field	Type	Required	Description
code	string	Yes	The natural key. Referenced by taxAreaCode on a customer or ship-to address
description	string		Human-readable name for the area
jurisdictionCodes[]	array of string		Which jurisdictions apply in this area. A snapshot — omission removes the link

The chain is: a ship-to address names a tax area, the area names jurisdictions, each jurisdiction holds rates per tax group, and the product names the tax group. Break any link and the line is untaxed rather than wrongly taxed.

PUT /gst-posting-rates

Purpose. A rate matrix keyed on a business posting group and a product posting group — a parallel scheme to jurisdictions, used where tax is derived from posting groups instead of geography.

{
  "source": "BC",
  "timestamp": "2026-08-19T04:00:00Z",
  "data": [
    {
      "rates": [
        {
          "businessPostingGroup": "DOM",
          "productPostingGroup": "STD",
          "ratePercent": 10.0
        },
        {
          "businessPostingGroup": "EXPORT",
          "productPostingGroup": "STD",
          "ratePercent": 0.0
        }
      ]
    }
  ]
}

Field	Type	Required	Description
rates[]	array	Yes	The full rate matrix

rates[]

Field	Type	Required	Description
businessPostingGroup	string	Yes	Matches an account's gstBusinessPostingGroup from Customer
productPostingGroup	string	Yes	Matches a product's gstProductPostingGroup from Catalogue
ratePercent	decimal	Yes	The rate as a percentage — send 10.0, not 0.10

Note

This payload nests a rates array inside each envelope item, so the outer data array is normally a single element. The shape differs from the other two tax endpoints; it is not a mistake in your serialiser.

Response

One entry per item, keyed by code — or by the posting-group pair for GST rates.

{
  "data": [
    { "key": "VIC", "outcome": "Upserted" }
  ]
}