Tax rates

A tax rate is a named rate products reference by id. Rates are integer micro-units (8.875% is 88750); the API also accepts ratePercent.

Base URL: https://apiv2.venuerun.com/merchants/:merchantId/tax-rates

text

GET    /merchants/:merchantId/tax-rates
POST   /merchants/:merchantId/tax-rates
GET    /merchants/:merchantId/tax-rates/:taxRateId
PATCH  /merchants/:merchantId/tax-rates/:taxRateId
DELETE /merchants/:merchantId/tax-rates/:taxRateId

The tax rate object

Field	Type	Description
`id`	`string` (read-only)	Unique identifier, assigned by VenueRun.
`createdAt`	`string` (read-only)	When it was created (ISO 8601).
`updatedAt`	`string` (read-only)	When it last changed (ISO 8601).
`name`	`string`	Shown to the customer on the receipt and to the merchant on reports.
`rateMicro`	`integer`
`inclusive`	`boolean`	Whether the product price already contains this tax. Defaults to `false`.
`jurisdiction`	`string`	Free-form label for the merchant's own bookkeeping, e.g. "NY-STATE". Defaults to `""`.
`testMode`	`boolean`	Defaults to `false`.

json

{
  "id": "NTvVkBJIkueQ0gxKmlb8",
  "name": "Test tax A1B2C3",
  "rateMicro": 88750,
  "inclusive": false,
  "jurisdiction": "",
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

List tax rates

GET /merchants/:merchantId/tax-rates

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/tax-rates?testMode`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "testMode": true,
  "length": 1,
  "data": [
    {
      "id": "NTvVkBJIkueQ0gxKmlb8",
      "name": "Test tax A1B2C3",
      "rateMicro": 88750,
      "inclusive": false,
      "jurisdiction": "",
      "testMode": true,
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Create a tax rate

POST /merchants/:merchantId/tax-rates

Required attributes

Field	Type	Description
`name`	`string`	Shown to the customer on the receipt and to the merchant on reports.

Optional attributes

Field	Type	Description
`inclusive`	`boolean`	Whether the product price already contains this tax. Defaults to `false`.
`jurisdiction`	`string`	Free-form label for the merchant's own bookkeeping, e.g. "NY-STATE". Defaults to `""`.
`testMode`	`boolean`	Defaults to `false`.
`rateMicro`	`integer`
`ratePercent`	`number`

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/tax-rates`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Test tax A1B2C3",
    "ratePercent": "8.875",
    "testMode": true
  }),
});

Response:

json

{
  "id": "libQFE1PTxfZchFSmZRz",
  "name": "Test tax A1B2C3",
  "rateMicro": 88750,
  "inclusive": false,
  "jurisdiction": "",
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Retrieve a tax rate

GET /merchants/:merchantId/tax-rates/:taxRateId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/tax-rates/zXUl8nKoYxl7mDZur7xu`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "id": "zXUl8nKoYxl7mDZur7xu",
  "name": "Test tax A1B2C3",
  "rateMicro": 88750,
  "inclusive": false,
  "jurisdiction": "",
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Update a tax rate

PATCH /merchants/:merchantId/tax-rates/:taxRateId

Send only the fields you are changing — every attribute is optional.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/tax-rates/eEYnh4vyprGsydfbqkRI`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Renamed",
    "testMode": false
  }),
});

Response:

json

{
  "id": "eEYnh4vyprGsydfbqkRI",
  "name": "Renamed",
  "rateMicro": 88750,
  "inclusive": false,
  "jurisdiction": "",
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Delete a tax rate

DELETE /merchants/:merchantId/tax-rates/:taxRateId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/tax-rates/NOwKQuprdMCaInowmunN`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "id": "NOwKQuprdMCaInowmunN",
  "object": {
    "id": "NOwKQuprdMCaInowmunN",
    "name": "Order tax A1B2C3",
    "rateMicro": 100000,
    "inclusive": false,
    "jurisdiction": "",
    "testMode": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  },
  "message": "Tax rate deleted",
  "deleted": true,
  "UlxsYomqtIm36VM5sVS3": 0
}

Errors

Every error answers with a message. A request that fails validation is a 400:

json

{
  "message": "rateMicro: Invalid input: expected int, received number"
}