Updates a status

PUT /api/configuration/statuses/{all}

Success: 200 OK

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

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

Path parameters

Name	Type	Required	Description
`statusId`	string	Yes	The status's identifier, as returned in `[].id` by List member statuses. 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

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

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.

This page as markdown · All pages · llms.txt