Businesses, tax rates and numbering

Create or update a tax rate

POST/v1/tax-rates

Creates a tax rate, or updates it when the body contains the id of an existing rate.

The same capability also answers PATCH /v1/tax-rates/{id} for partial updates. Rates support exclusive, inclusive and compound tax, and every tax amount is computed in integer minor units.

Document lines keep a frozen copy of the rate, so an update only affects lines added afterwards. See Taxes.

Permission: settings.manage
Type: Write. Creates or changes data and writes an audit entry.
Auth: API key, MCP token or signed-in session
Capability: upsert_tax_rate
CLI: freeinvoiceautomation tax-rate upsert
Available: At launch, 1 January 2027

upsert_tax_rate

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/tax-rates \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "VAT 20%",
  "rate": "20",
  "calculation": "exclusive",
  "compound": false
}'

{
  "data": {
    "id": "0193f2a0-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
    "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
    "name": "VAT 20%",
    "rate": "20.0000",
    "calculation": "exclusive",
    "compound": false,
    "preset_key": null,
    "archived_at": null,
    "created_at": "2027-01-02T08:31:10Z",
    "updated_at": "2027-01-02T08:31:10Z"
  }
}

Authorizations

Authorizationstringrequired

Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Headers

Idempotency-Keystring

Any unique string up to 255 characters. A retry with the same key and body returns the first response. See Idempotency.

Body

application/json

idstring<uuid>

Id of an existing rate to update. Leave out to create a new rate.

business_idstring<uuid>

Business that owns the rate. May be left out when you can reach exactly one business.

namestringrequired

Label printed on documents.

ratestringrequired

Percent as a decimal string, e.g. "20" or "17.5" (up to four decimals).

calculationenum<string>required

How the rate is applied to the line price.

Available options: exclusive, inclusive

compoundbooleandefault:false

Charge this tax on the line amount plus the other taxes.

preset_keystring

Tax preset the rate is based on, when you start from a country preset.

Response

201 - application/json

idstring<uuid>

Unique id of the tax rate.

business_idstring<uuid>

The business the rate belongs to.

namestring

Label printed on lines and totals, e.g. VAT 20%.

ratestring

Percent as a decimal string with up to four decimals, e.g. "20.0000" = 20%.

calculationenum<string>

exclusive adds the tax on top of the line price; inclusive treats the price as already containing the tax.

Available options: exclusive, inclusive

compoundboolean

When true, the tax is charged on the line amount plus the other taxes on that line.

preset_keystring | null

Key of the tax preset the rate was created from, if any.

archived_atstring<date-time> | null

When the rate was archived. Archived rates cannot be picked for new lines but stay on old documents.

created_atstring<date-time>

When the rate was created.

updated_atstring<date-time>

When the rate was last changed.

Errors

validation_failed

idempotency_key_reused

business_out_of_scope

Plus the common errors every call can return. See Errors.

Suggest edits Raise issue

List tax ratesPrevious Archive a tax rateNext