Update cost centre

PUT /api/configuration/cost-centres/{id}

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

Overview

Changes the description or the external reference of an existing cost centre. Cost centres are the top level of the financial reporting structure: departments are attached to a cost centre, and a cost centre with departments attached cannot be deleted. Only these two text fields are writable — there is nothing budgetary or operational behind this endpoint.

This is a partial update, not a full replacement. Each field is applied only when it is present and non-null, so a field you omit, or send as null, keeps its current value. You can safely send just the one field you want to change.

Be careful with empty strings, which are not the same as null here:

description: "" is rejected with 400 Description cannot be empty.
reference: "" is accepted and stores an empty reference, because only null is treated as "leave alone". Send null, or omit the field, if you do not intend to change it.

The cost centre must already exist; an unknown identifier returns 404. The identifier itself is not writable. On success the response is 204 No Content and the change is visible on the next read.

Endpoint

PUT {base_url}/api/configuration/cost-centres/{id}

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

Path parameters

Name	Type	Required	Description
`id`	string	Yes	Identifier of the cost centre to change, as listed by `GET /api/configuration/cost-centres`. System-generated identifiers carry a `CCTR` prefix. If it matches no cost centre the request fails with `404 CostCentre ID does not exist`.

Request body

Field	Type	Required	Description
`description`	string	No	The cost centre's name as it appears in finance listings and on the departments attached to it. Maximum 255 characters (`Description cannot be more than 255 characters`). Omit it, or send null, to leave the current description alone; sending an empty string is rejected with `400 Description cannot be empty`, so a description cannot be cleared once set.
`reference`	string	No	Your own or your finance system's reference for this cost centre — free text, not validated against anything and not used by the platform for matching. Maximum 255 characters (`Reference cannot be more than 255 characters`). Omit it, or send null, to leave the current value alone. Unlike `description`, an empty string is accepted and overwrites the stored reference with an empty value.

Sample request

cURL

curl -X PUT '{base_url}/api/configuration/cost-centres/{id}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "string",
  "reference": "string"
}'

Errors

Status	Meaning	When
`400`	Bad request	`description` was sent as an empty string — body is `Description cannot be empty`. Note that null is allowed and means "no change".
`400`	Bad request	`description` or `reference` exceeds 255 characters. The body is a validation error object keyed by field name, not a plain string.
`404`	Not found	No cost centre matches the path identifier — body is `CostCentre ID does not exist`.
`500`	Internal server error	An unexpected server-side failure, including a failure saving the record. No detail is returned.

This page as markdown · All pages · llms.txt