Taxes

A tax row is a named rate. Items point at one for sales and optionally another for purchases, and the point of sale applies it at the till. Get this wrong and every receipt in the merchant’s day is wrong — read the merchant’s existing rows before you create new ones.

Endpoints

Method	Path	Scope
GET	/v1/taxes	taxes.read
POST	/v1/taxes	taxes.write
PATCH	/v1/taxes/:id	taxes.write

List what exists

curl -s "$API_BASE_URL/taxes?status=1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    { "id": 3, "tax": "GST 5%", "taxRate": 5, "type": 0, "status": 1 },
    { "id": 4, "tax": "GST 18%", "taxRate": 18, "type": 0, "status": 1 },
    { "id": 7, "tax": "Zero rated", "taxRate": 0, "type": 0, "status": 1 }
  ],
  "meta": { "page": 1, "limit": 10, "total": 3 }
}

Create a tax

curl -s "$API_BASE_URL/taxes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "tax": "GST 12%",
    "taxRate": 12,
    "type": 0,
    "applyTo": 0,
    "compound": false
  }'

Field	Type	Required	Notes
tax	string	yes	Display name — it appears on receipts
taxRate	number	yes	Percentage. 12 means 12%, not 0.12
type	number	no	0 exclusive (default), 1 inclusive
applyTo	number	no	0 all sales (default), 1 a department, 2 selected items
department	string	no	Department name when applyTo is 1
compound	boolean	no	true calculates this tax on top of other taxes rather than on the net
status	number	no	1 active (default), 0 inactive
QuickbookTaxCode	string	no	Mapping code for QuickBooks exports
ZMTaxCode	string	no	Mapping code for fiscalisation, where required

Inclusive versus exclusive

type decides how the item’s rate is read:

type	Meaning	Item priced at 100 with a 10% tax
0	Exclusive — tax is added at the till	Customer pays 110, tax 10
1	Inclusive — tax is already inside the price	Customer pays 100, tax 9.09, net 90.91

Inclusive pricing is the norm where regulation requires shelf prices to be the price paid. Exclusive is the norm where tax is shown as a separate line. Getting it backwards silently shifts every net-sales figure the merchant reports.

Changing a tax rate is retroactive in effect, not in history

Patching taxRate changes what the till charges from that moment on. It does not restate past sales. When a jurisdiction changes a rate, create a new tax row and re-point items at it so historical reporting stays correct.

Attaching taxes to items

Items carry the tax by id:

curl -s -X PATCH "$API_BASE_URL/items/8841" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "taxId": 4, "PurchTaxId": 4 }'

Item field	Purpose
taxId	Applied when the item is sold
PurchTaxId	Applied when the item is purchased, where the two differ
cessId, Tax4Id	Additional levies stacked on top, in jurisdictions that use them
hsn	Tax classification code printed on compliant invoices

To re-point a whole category, list items with groupId and patch them — there is no bulk tax-reassignment endpoint in this version.