Tax classes

Tax classes define the sales-tax rates your shop charges. Each class is a named bundle of one or more rate components (e.g. a state rate plus a county rate), can be marked tax-inclusive, and can be assigned to a single location for multi-location shops. Exactly one class per tenant is the default, it’s what invoices and estimates pick up when nothing more specific applies.

Rates are stored as exact integer parts-per-million (rate_ppm, so 6.625% = 66250) and echoed as a derived decimal percent (rate_percent). You can supply either form when writing.

The tax class object

{
  "object": "tax_class",
  "id": 3,
  "name": "NJ Sales Tax",
  "label": "NJ Sales Tax",
  "inclusive": false,
  "is_default": true,
  "active": true,
  "location_id": null,
  "components": [
    {
      "id": 7,
      "name": "State",
      "jurisdiction": "NJ",
      "rate_ppm": 66250,
      "rate_percent": 6.625,
      "compound": false,
      "ordinal": 0
    }
  ],
  "created_at": "2026-05-01T12:00:00.000Z",
  "updated_at": "2026-06-10T09:30:00.000Z"
}

Field	Type	Description
`id`	integer	Unique tax class ID
`name`	string	Class name
`label`	string\|null	Display label (defaults to `name`)
`inclusive`	boolean	`true` when prices already include this tax
`is_default`	boolean	Exactly one default class exists per tenant
`active`	boolean	`false` = soft-deactivated (kept for historical invoices)
`location_id`	integer\|null	`null` = tenant-wide; otherwise assigned to that location
`components`	array	Ordered rate components (see below)
`created_at`	string\|null	ISO-8601 creation timestamp
`updated_at`	string\|null	ISO-8601 last-updated timestamp

Component fields

Field	Type	Description
`id`	integer	Component ID
`name`	string	Component name (e.g. `"State"`)
`jurisdiction`	string\|null	Jurisdiction label
`rate_ppm`	integer	Exact integer rate in parts-per-million (6.625% = `66250`)
`rate_percent`	number	Derived decimal percent (`rate_ppm / 10000`)
`compound`	boolean	Applies on top of prior components’ tax
`ordinal`	integer	Application order

List tax classes

GET /api/v1/tax_classes

Returns the tenant’s complete tax-class catalog (not paginated, a settings-style list). Inactive classes are included by default so historical/deactivated classes stay discoverable; filter with active. The default class sorts first.

Scope required: tax.read

Query parameters

Parameter	Type	Description
`active`	boolean	Filter by active state (`true` = active only, `false` = deactivated only)

curl

curl "https://app.benchkey.com/api/v1/tax_classes?active=true" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const res = await fetch(
  "https://app.benchkey.com/api/v1/tax_classes?active=true",
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const { data } = await res.json();

Response

{
  "object": "list",
  "data": [ { "object": "tax_class", "id": 3, "name": "NJ Sales Tax", "is_default": true } ],
  "has_more": false,
  "next_cursor": null
}

Additional resource fields are omitted from this example.

Retrieve a tax class

GET /api/v1/tax_classes/:id

Returns a single tax class with its components.

Scope required: tax.read

curl

curl "https://app.benchkey.com/api/v1/tax_classes/3" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Response

Returns the tax class object. Returns 404 if no tax class with that ID exists.

Create a tax class

POST /api/v1/tax_classes

Creates a named tax class with one or more rate components. Each component takes rate_percent (decimal, e.g. 6.625) or rate_ppm (integer parts-per-million, e.g. 66250), not both; omitting both makes a 0% (exempt) component.

The tenant’s first tenant-scoped class is forced to be the default; is_default: true transactionally unseats the previous default. A location_id assigns the class to one location, at most one active class per location; conflicts return 409.

Scope required: tax.write

Send an Idempotency-Key header to make retries safe. See Idempotency.

Request body

Field	Required	Type	Description
`name`	yes	string	Class name (max 200 characters)
`components`	yes	array	One or more component objects (see below)
`label`	no	string\|null	Display label, max 200 characters (defaults to `name`)
`inclusive`	no	boolean	Prices already include this tax (default: `false`)
`is_default`	no	boolean	Promote this class to tenant default (default: `false`)
`location_id`	no	integer\|null	Assign the class to one location (immutable after create). `null`/omitted = tenant-wide

Component input fields

Field	Required	Type	Description
`name`	yes	string	Component name (max 200 characters)
`jurisdiction`	no	string\|null	Jurisdiction label (max 200 characters)
`rate_percent`	no	number	Decimal percent, 0–100 (e.g. `6.625`). Mutually exclusive with `rate_ppm`
`rate_ppm`	no	integer	Integer parts-per-million, 0–1,000,000 (e.g. `66250`). Mutually exclusive with `rate_percent`
`compound`	no	boolean	Applies on top of prior components’ tax (default: `false`)
`ordinal`	no	integer	Application order (defaults to array position)

curl

curl -X POST https://app.benchkey.com/api/v1/tax_classes \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: taxclass-create-$(uuidgen)" \
  -d '{
    "name": "NJ Sales Tax",
    "components": [
      { "name": "State", "jurisdiction": "NJ", "rate_percent": 6.625 }
    ]
  }'

Node.js

const res = await fetch("https://app.benchkey.com/api/v1/tax_classes", {
  method: "POST",
  headers: {
    Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    name: "NJ Sales Tax",
    components: [{ name: "State", jurisdiction: "NJ", rate_percent: 6.625 }],
  }),
});
const taxClass = await res.json(); // HTTP 201

Response

Returns the tax class object with HTTP 201.

Update a tax class

PATCH /api/v1/tax_classes/:id

Partial update: omitted fields are left untouched. components, when present, replaces the full component list.

is_default: true promotes this class (unseating the previous default). The default flag cannot be dropped directly, and the default class cannot be deactivated (409, promote another class first). location_id is immutable and not accepted here.

Scope required: tax.write

Request body

Field	Type	Description
`name`	string	Class name (max 200 characters)
`label`	string\|null	Display label (max 200 characters)
`inclusive`	boolean	Prices already include this tax
`active`	boolean	`true` re-activates a deactivated class
`is_default`	boolean	`true` promotes this class to tenant default
`components`	array	Replaces the full component list (same fields as create, min 1 item)

curl

curl -X PATCH "https://app.benchkey.com/api/v1/tax_classes/3" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" \
  -H "Content-Type: application/json" \
  -d '{ "label": "New Jersey Sales Tax", "inclusive": false }'

Response

Returns the updated tax class object.

Deactivate a tax class

DELETE /api/v1/tax_classes/:id

Soft-deactivates the class (active: false) and returns the updated object. The row is never hard-deleted, historical invoices and estimates reference it, and it can be re-activated via PATCH with active: true.

Deactivating the default class returns 409 (set another default first). Deactivating an already-inactive class is an idempotent no-op.

Scope required: tax.write

curl

curl -X DELETE "https://app.benchkey.com/api/v1/tax_classes/3" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Response

Returns the deactivated tax class object (active: false) with HTTP 200.

Error codes

HTTP status	Code	Meaning
`400`	`invalid_body`	Request body is not a JSON object
`400`	`unknown_field`	Body contains a field this endpoint doesn’t accept (e.g. `location_id` on PATCH)
`400`	`missing_field`	A required field is absent (`name`, `components`)
`400`	`invalid_field`	A field value is invalid, e.g. both `rate_percent` and `rate_ppm` supplied on one component, a rate out of range, or a non-string `name`
`400`	`invalid_query`	A list filter parameter was supplied as an array or object instead of a single scalar value
`400`	`invalid_param`	The `:id` is not a valid integer
`404`	`not_found`	No tax class with that ID exists for this tenant
`409`	`conflict`	The location already has an active class, the class is the tenant default and cannot be deactivated, or the default flag would be dropped without a replacement
`422`	`create_failed`	The tax class could not be created
`403`	`insufficient_scope`	API key lacks `tax.read` or `tax.write`

See Errors for the full error envelope format.

System status