Search Documentation

Search for a documentation page...

Tax Rates API

REST API endpoints for managing tax rates assigned to products.

Tax rates define the percentage of tax applied to products at checkout (e.g. "Standard VAT" at 23%). A rate can also carry a special label instead of a numeric percentage (e.g. "Reverse charge"), in which case the rate is forced to 0.

List Tax Rates

GET /api/v1/tax-rates

Query Parameters

ParameterTypeDefaultDescription
limitnumber10Tax rates per page (1-100)
offsetnumber0Tax rates to skip
querystring—Search by tax rate name

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "name": "Standard VAT",
      "rate": 23,
      "label": null,
      "createdAt": "2024-05-20T10:30:00.000Z",
      "updatedAt": "2024-05-20T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1
  }
}

Create Tax Rate

POST /api/v1/tax-rates

Creates a tax rate. Provide either a numeric rate or a label — one is required. When a label is set, the rate is forced to 0.

Request Body

FieldTypeRequiredDescription
namestringYesDisplay name, e.g. Standard VAT
ratenumberNo*Percentage rate (e.g. 23 = 23%, range 0-100). Ignored if label is set
labelstringNo*Special label instead of a numeric rate (e.g. Reverse charge); forces rate to 0

* Provide either rate or label.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Standard VAT", "rate": 23}' \
  https://your-store.yns.store/api/v1/tax-rates

Response (201)

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Standard VAT",
  "rate": 23,
  "label": null,
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T10:30:00.000Z"
}

Get Tax Rate

GET /api/v1/tax-rates/:id

Returns a single tax rate by UUID.

Response

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Standard VAT",
  "rate": 23,
  "label": null,
  "createdAt": "2024-05-20T10:30:00.000Z",
  "updatedAt": "2024-05-20T10:30:00.000Z"
}

Update Tax Rate

PATCH /api/v1/tax-rates/:id

Replaces a tax rate's name, rate, and label. Uses the same body as Create Tax Rate.

Request Body

Same fields as Create Tax Rate.

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reduced VAT", "rate": 8}' \
  https://your-store.yns.store/api/v1/tax-rates/0191abc0-1234-7def-8000-000000000001

Response (200)

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "name": "Reduced VAT",
  "rate": 8,
  "label": null,
  "createdAt": "2024-05-20T10:30:00.000Z",
  "updatedAt": "2024-06-15T11:00:00.000Z"
}

Delete Tax Rate

DELETE /api/v1/tax-rates/:id

Hard-deletes the tax rate by UUID. If the rate is still assigned to one or more products, the request is rejected with a 409.

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/tax-rates/0191abc0-1234-7def-8000-000000000001

Response

{
  "ok": true,
  "deleted": 1
}

In Use (409)

{
  "error": "Cannot delete tax rate because it is still assigned to products"
}
PreviousShippingAPI ReferenceNextPickup LocationsAPI Reference