Retrieve a tax code's details

GET /api/configuration/tax-codes/{taxcodeId}

Success: 200 OK

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

Overview

Returns one tax code and its translated descriptions, looked up by the string id you already hold.

Prefer List all tax codes when you are building a lookup list — it returns the same shape for every code in one call. Reach for this endpoint when you need to confirm a single code still exists and check its current rate before pricing against it, because unlike the list it reflects a recent change immediately.

An id that does not exist returns 404, not an empty body, which makes this a usable existence check.

Endpoint

GET {base_url}/api/configuration/tax-codes/{taxcodeId}

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Path parameters

Name	Type	Required	Description
`taxCodeId`	string	Yes	The tax code to retrieve, as returned in `id` by List all tax codes. Maximum 15 characters. Codes are upper-cased with spaces removed, so pass the value back exactly as you received it. An unrecognised id returns `404`.

Sample request

cURL

curl -X GET '{base_url}/api/configuration/tax-codes/{taxcodeId}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'

Response fields

Field	Type	Description
`id`	string	The tax code's identifier, unique within your tenant — a short string, not a number, and the value other configuration records use to reference this code. Maximum 15 characters. Echoes the `taxCodeId` you requested. Codes created without a caller-supplied id are generated with the prefix `TAXC`.
`description`	string	The default, untranslated label for the code, in the tenant's base language. Maximum 25 characters. Use `translations` in preference where you have a culture to render for.
`rate`	number (float)	The tax rate applied by this code. Rates are held to a maximum of two decimal places — creating or updating a code with more is rejected with `The tax rate can only be specified to two decimal places`. A code with no rate configured is returned as `0`, not `null`.
`reference`	string	A free-text reference held against the code, typically for matching to an external finance or accounting system. Maximum 25 characters. Returned unchanged; no format or uniqueness rule applies to it. May be `null`.
`translations`	array of object	Culture-specific versions of `description`, one entry per configured culture. Only the description is translatable for a tax code — no other field has translations. Returned as an empty array, not `null`, when nothing has been translated, so a client can iterate it unconditionally.
`translations[].type`	string	The property this entry translates. For tax codes it is always `description`, because that is the only translated property; treat any other value as unexpected rather than filtering on it.
`translations[].culture`	string	The culture the translation applies to — match it against the locale you are rendering for and fall back to `description` when there is no entry.
`translations[].text`	string	The translated description for this culture. Replaces `description` for display; it does not extend it.

Sample response

200 OK

{
  "id": "string",
  "description": "string",
  "rate": 10.5,
  "reference": "string",
  "translations": [
    {
      "type": "string",
      "culture": "string",
      "text": "string"
    }
  ]
}

Errors

Status	Meaning	When
`400`	Bad request	Returned only when the path segment cannot be read, with a validation error object keyed by field name as the body. There is no realistic way to trigger this — an unknown code produces `404`, not `400`.
`404`	Not found	No tax code exists with the id you supplied. The body is plain text, not JSON: `GetTaxCode could not find the id {taxCodeId}`.
`500`	Internal server error	An unexpected server-side failure while reading the code or its translations. The body is empty — the detail is not returned to you — so retry once and then raise it with support.

This page as markdown · All pages · llms.txt