BillKit/DocsConsole
Tax rates

Update tax rate

Correct a tax rate, retire it, or bring a retired one back into use.

POST/v1/tax_rates/{tax_rate_id}
Operation update_tax_rate·Scope tax_rates:write·OpenAPI v1.1.0

Parameters

ParameterDescription
tax_rate_idstring · pathrequiredId of the tax rate, which starts tr_.
activebooleanoptionalfalse stops the rate applying to new charges. true reactivates it and retires any other active rate for the same country.
display_namestring | nulloptionalA label for the rate. null clears it. At most 255 characters.
inclusivebooleanoptionalWhether prices charged in this country already include the tax (true) or have it added on top (false). Applies to prices whose tax_behavior is unspecified.
rate_basis_pointsintegeroptionalThe rate in basis points: 2100 is 21 percent. Between 0 and 10000.

Returns

Returns a TaxRateResponse object.

Errors

StatusCause
400The request was refused (type: invalid_request_error): a required parameter is missing (parameter_missing), one failed validation (parameter_invalid) or is not one the operation takes (parameter_unknown), and param names it.
401No credential, or one that does not authenticate.
402The account is suspended (tenant_suspended), or the payment provider refused a charge or refund the call made (type: payment_error, code: payment_refused).
403Authenticated, but not allowed: missing scope (insufficient_scope), a key of the wrong mode (mode_mismatch), or a refused origin. Needs the tax_rates:write scope.
404No such object in this account and mode.
409Conflicts with the object's current state (state_conflict, or a more specific code), or an operation still in flight (operation_pending).
413The request body is larger than the API accepts.
429Rate limited. Retry-After says when to try again.
500Something failed on BillKit's side (type: api_error). Retry with the same Idempotency-Key.
502The payment provider failed or did not answer.
503Temporarily unable to serve. reason says whether the request was attempted.
Request · curl
curl -X POST https://api.billkit.eu/v1/tax_rates/tr_9XKp2vQ1 \
  -H "Authorization: Bearer $BILLKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Request body · every field
{
  "active": false,
  "display_name": "Ada Lovelace",
  "inclusive": false,
  "rate_basis_points": 0
}
Response · 200 OK
{
  "active": false,
  "country_code": "NL",
  "created": 1789392000,
  "display_name": "Ada Lovelace",
  "id": "tr_9XKp2vQ1",
  "inclusive": false,
  "livemode": false,
  "object": "tax_rate",
  "rate_basis_points": 0
}