Tax Rates
Manage tax rate presets via the REST API
Tax rate presets let you define reusable tax rates (e.g. state sales tax) that can be applied to quotes, jobs, and invoices. Once a tax rate is created, reference it by ID when creating or updating those records.
List Tax Rates
Retrieve a paginated list of tax rate presets in your workspace.
GET /api/v1/tax-ratesRequired Scope: tax-rates:read
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
per_page | integer | 25 | Results per page (1-100) |
search | string | Search by name or description | |
sort_by | string | Field to sort by: id, name, rate, created_at, modified_at | |
sort_direction | string | desc | Sort direction (asc or desc) |
curl https://app.bluesuite.com/api/v1/tax-rates \
-H "Authorization: Bearer wk_YOUR_API_KEY"{
"success": true,
"data": [
{
"id": 1,
"name": "Maryland Sales Tax",
"description": "State sales tax",
"rate": 6,
"workspace_id": 123,
"created_at": "2025-03-01T10:00:00.000Z"
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total_pages": 1
}
}Create Tax Rate
Create a new tax rate preset.
POST /api/v1/tax-ratesRequired Scope: tax-rates:write
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Tax rate name (e.g. "Sales Tax", "VAT") |
description | string | No | Description of the tax rate |
rate | number | Yes | Tax rate percentage (e.g. 8.25 for 8.25%) |
curl -X POST https://app.bluesuite.com/api/v1/tax-rates \
-H "Authorization: Bearer wk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Virginia Sales Tax",
"description": "State sales tax for VA",
"rate": 6
}'{
"success": true,
"data": {
"id": 2,
"name": "Virginia Sales Tax",
"description": "State sales tax for VA",
"rate": 6,
"workspace_id": 123,
"created_at": "2025-03-15T12:00:00.000Z"
}
}Get Tax Rate
Retrieve a single tax rate preset by ID.
GET /api/v1/tax-rates/:idRequired Scope: tax-rates:read
curl https://app.bluesuite.com/api/v1/tax-rates/2 \
-H "Authorization: Bearer wk_YOUR_API_KEY"{
"success": true,
"data": {
"id": 2,
"name": "Virginia Sales Tax",
"description": "State sales tax for VA",
"rate": 6,
"workspace_id": 123,
"created_at": "2025-03-15T12:00:00.000Z"
}
}Update Tax Rate
Update an existing tax rate preset. All fields are optional -- only include the fields you want to change.
PUT /api/v1/tax-rates/:idRequired Scope: tax-rates:write
Request Body: Same fields as Create Tax Rate. All fields are optional.
curl -X PUT https://app.bluesuite.com/api/v1/tax-rates/2 \
-H "Authorization: Bearer wk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"rate": 6.5
}'{
"success": true,
"data": {
"id": 2,
"name": "Virginia Sales Tax",
"description": "State sales tax for VA",
"rate": 6.5,
"workspace_id": 123,
"created_at": "2025-03-15T12:00:00.000Z"
}
}Delete Tax Rate
Delete a tax rate preset by ID.
DELETE /api/v1/tax-rates/:idRequired Scope: tax-rates:write
curl -X DELETE https://app.bluesuite.com/api/v1/tax-rates/2 \
-H "Authorization: Bearer wk_YOUR_API_KEY"{
"success": true,
"data": {
"deleted": true
}
}