# Updates a status

`PUT /api/configuration/statuses/{all}`

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

HTML version: [Updates a status](https://support.gladstonesoftware.cloud/reference/configuration/updates-a-status)

## Overview

Updates a member status — the label a member's record carries, such as "Active", "Frozen" or "Lapsed", together with the behaviour the platform applies to members holding it.

**This one is a genuine merge, not a full replacement.** Every field is written only when you send a non-null value, so a body containing just the one field you want to change leaves everything else alone. That makes this endpoint safer than most updates in this group — but note the two special cases: sending `description` as an empty string is treated as "no change" rather than "clear it", and sending `backColourHex` or `textColourHex` as an empty string does clear the colour.

Changing the behaviour flags takes effect for every member already holding the status, immediately and without any recalculation of their history. Turning on `treatMembersAsExpired` on a status that thousands of members hold expires all of them at once, so read the current values with [Get status by ID](get-a-specific-status-by-id.md) before you send anything.

**Two things to watch:**

- **An unknown `statusId` returns `400`, not `404`.** The message is `Status ID {statusId} does not exist`.
- **`description` is validated at 255 characters but only 25 are accepted.** Anything between 26 and 255 characters passes validation and then fails with `500`. Keep descriptions to 25 characters.

A successful update returns **`204 No Content` with an empty body**, not the updated status.

## Endpoint

`PUT {base_url}/api/configuration/statuses/{all}`

`{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 |
|------|------|----------|-------------|
| `statusId` | string | Yes | The status's identifier, as returned in `[].id` by [List member statuses](get-all-member-statuses.md). Maximum 15 characters, and matched case-insensitively, so case in the URL does not matter. An id matching no status is rejected with `400` and `Status ID {statusId} does not exist`, not `404`. |

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `description` | string | No | The status's display name, shown against the member wherever their status appears. **Effectively limited to 25 characters** — validation permits 255 but only 25 are accepted, so anything longer fails as a `500` rather than a `400`. Omitting it, sending null, *or sending an empty string* all mean "leave the stored description alone": there is no way to clear it through this endpoint. |
| `backColourHex` | string | No | The background colour used when the status is displayed as a badge. Accepts `#RRGGBB` hex, and also standard colour names such as `Red`. Send an empty string to clear the colour; omit the field or send null to leave it unchanged. It always comes back from the read endpoints as `#RRGGBB` upper-case hex, even if you sent a name. A value that cannot be parsed as a colour fails as a `500`, not a `400`. |
| `textColourHex` | string | No | The text colour used on that badge, in the same forms as `backColourHex` — hex or a standard colour name, empty string to clear, omitted to leave unchanged. Nothing checks that it contrasts with `backColourHex`, so it is on you to keep the pairing legible. |
| `collectSalesInvoices` | boolean | No | Whether sales invoices continue to be collected for members holding this status. Omitting it or sending null leaves the stored value unchanged. |
| `treatMembersAsExpired` | boolean | No | Whether members holding this status are treated as expired — which is how a status is made to deny access and stop counting as current membership. Applies to every member on the status the moment you save it. Omitting it or sending null leaves the stored value unchanged. |
| `freezeSubscriptions` | boolean | No | Whether subscriptions are frozen for members holding this status — the flag behind a "suspended" or "on hold" status. Omitting it or sending null leaves the stored value unchanged. |
| `prospectStatus` | boolean | No | Whether this status marks the holder as a prospect rather than a member — someone who has enquired but not joined. Omitting it or sending null leaves the stored value unchanged. |

## Sample request

```bash title="cURL"
curl -X PUT '{base_url}/api/configuration/statuses/{all}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "string",
  "backColourHex": "string",
  "textColourHex": "string",
  "collectSalesInvoices": true,
  "treatMembersAsExpired": true,
  "freezeSubscriptions": true,
  "prospectStatus": true
}'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | The status's identifier, maximum 15 characters — the value you pass as `statusId`. |
| `description` | string | The status's display name, maximum 25 characters. |
| `backColourHex` | string | The badge background colour as `#RRGGBB` upper-case hex. An empty string means no colour is set. |
| `textColourHex` | string | The badge text colour as `#RRGGBB` upper-case hex. An empty string means no colour is set. |
| `collectSalesInvoices` | boolean | Whether sales invoices are collected for members on this status. |
| `treatMembersAsExpired` | boolean | Whether members on this status are treated as expired. |
| `freezeSubscriptions` | boolean | Whether subscriptions are frozen for members on this status. |
| `prospectStatus` | boolean | Whether this status marks the holder as a prospect rather than a member. |

## Sample response

```json title="200 OK"
{
  "id": "string",
  "description": "string",
  "backColourHex": "string",
  "textColourHex": "string",
  "collectSalesInvoices": true,
  "treatMembersAsExpired": true,
  "freezeSubscriptions": true,
  "prospectStatus": true
}
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | No status has that `statusId` — `Status ID {statusId} does not exist`. This is what an unknown id returns; this endpoint does not return `404`. |
| `400` | Bad request | `description` exceeds 255 characters — `The status description cannot be more than 255 characters`, returned as a validation error object keyed by field name. Note that 26 to 255 characters passes this check and then fails as a `500`. |
| `404` | Not found | Not returned by this endpoint. |
| `409` | Conflict | Returned only if the update would duplicate a value that must be unique — `The record updating contains a key already in use` — which this endpoint's fields do not normally do, as the identifier cannot be changed. |
| `500` | Internal server error | `description` is longer than 25 characters, or `backColourHex`/`textColourHex` is not a parseable colour. Also any other unexpected server-side failure. The response body is empty. |