Create or update a tax group

ID-keyed upsert.

Create: omit id. name and at least one tax line are required.
Update: pass id. Any subset of fields is patched; omit a field to leave it untouched.

A group is referenced by price lists, and changing its rate re-prices every quote that uses it, so an integration syncing tax rules should update the existing group rather than create a second one.

Errors

422 tax_group_name_required — creating without a name.
422 tax_group_lines_required — creating with an empty taxLines.
404 tax_group_not_found — the id belongs to another tenant, or doesn’t exist.

POST/api/v1/tax-groups

Authorization

AuthorizationBearer token (bloomcount_...) · headerrequired

Header parameters

Idempotency-Keystring

Replays return the cached response. 24h TTL, scoped per API key.

Request body

requiredapplication/json

idstring

Existing tax group ID. Present → update; absent → create.

namestring

calculationMethodstring

How the tax lines combine into the total rate: - `combined` — lines are summed. Two lines of `0.05` and `0.07` give a total rate of `0.12` (12%). Use for jurisdictions where federal + provincial tax both apply to the pre-tax amount. - `compounding` — each line is applied on top of the previous. Lines of `0.05` then `0.07` give `(1 + 0.05) × (1 + 0.07) - 1 = 0.1235` (12.35%). Use for tax-on-tax regimes (e.g. Quebec QST stacks on GST).

default: "combined"

Allowed:combinedcompounding

taxLinesTaxLine[]

Show properties

Array of TaxLine

labelstringrequired

ratenumber<float>required

Decimal rate. e.g. 0.2 = 20%.

Responses

200Updated

taxGroupIdstringrequired

actionstringrequired

Allowed:createdupdated

201Created

taxGroupIdstringrequired

actionstringrequired

Allowed:createdupdated

401Missing or invalid API key, or revoked / expired.

errorstringrequired

403Authenticated, but the key lacks the required scope or the tenant has no API access.

errorstringrequired

422Request body or arguments failed validation.

errorstringrequired

429Per-minute rate limit (60/min) or per-month cap exceeded.

errorstringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (bloomcount_...)Remember on this deviceInclude my values in samples

Parameters

Idempotency-KeyheaderReplays return the cached response. 24h TTL, scoped per API key.

Bodyapplication/json

Request body

Request

curl -X POST "https://app.bloomcount.com/api/v1/tax-groups" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "name": "VAT 20%",
  "calculationMethod": "combined",
  "taxLines": [
    {
      "label": "VAT",
      "rate": 0.2
    }
  ]
}'

const response = await fetch("https://app.bloomcount.com/api/v1/tax-groups", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"id\": \"string\",\n  \"name\": \"VAT 20%\",\n  \"calculationMethod\": \"combined\",\n  \"taxLines\": [\n    {\n      \"label\": \"VAT\",\n      \"rate\": 0.2\n    }\n  ]\n}"
});

import requests

response = requests.post(
    "https://app.bloomcount.com/api/v1/tax-groups",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"id\": \"string\",\n  \"name\": \"VAT 20%\",\n  \"calculationMethod\": \"combined\",\n  \"taxLines\": [\n    {\n      \"label\": \"VAT\",\n      \"rate\": 0.2\n    }\n  ]\n}",
)

Response

{
  "taxGroupId": "tax_x7c4d8m2k9n1q5r6t3v8w2y4z",
  "action": "updated"
}

{
  "taxGroupId": "tax_x7c4d8m2k9n1q5r6t3v8w2y4z",
  "action": "created"
}

{
  "error": "string"
}

{
  "error": "string"
}

{
  "error": "string"
}

{
  "error": "string"
}