# Update cost centre

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

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

HTML version: [Update cost centre](https://support.gladstonesoftware.cloud/reference/configuration/update-cost-centre)

## 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](../../guides/authenticating-with-gladstone-apis.md).

## 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

```bash title="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. |