Create pricing timeband

POST /api/configuration/timebands

Success: 201 Created

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

Overview

Creates a pricing timeband — a named period of the day, such as peak or off-peak, that prices and entry rules can later be attached to. Despite the name, this endpoint does not define any times. The timeband it creates holds only an identifier, a description, an entry-restriction flag and optional translations; the actual start and end times, the days they apply to and the prices themselves are configured elsewhere against the timeband you create here.

You may supply your own id, or omit it and let the platform allocate the next identifier in the TBND series. If you supply one it is normalised before it is stored: converted to upper case with all spaces removed, so peak time becomes PEAKTIME. Compare and store the normalised form, not what you sent.

This call is not idempotent, and it returns nothing you can use. A success is 201 Created with an empty body. Retrying with an id that already exists returns 409 and changes nothing; retrying without an id allocates a fresh identifier and creates a second, duplicate timeband. Because no identifier is returned, always supply your own id unless you are prepared to list all timebands afterwards to find the one you just made.

Endpoint

POST {base_url}/api/configuration/timebands

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

Request body

Field	Type	Required	Description
`id`	string	No	The identifier you want the timeband to have, unique within your tenant. Maximum 15 characters, but request validation does not check this, so an over-long value fails as a `500` rather than a `400`. The value is normalised before storage — upper-cased with all spaces stripped, so `off peak` is stored as `OFFPEAK`. The uniqueness check runs against the normalised form. Omit it and the platform allocates the next free identifier in the `TBND` series (`TBND1`, `TBND2`, …); because nothing is returned in the response body, you will then have to list timebands to discover which identifier you were given.
`description`	string	Yes	The label shown wherever the timeband is presented, for example "Peak" or "Off-peak weekday". Must not be empty. Request validation permits up to 255 characters, but only 25 can be stored — anything between 26 and 255 characters passes validation and then fails as a `500`, so treat 25 characters as the real limit.
`restrictEntryInd`	integer (int32)	No	Whether this timeband blocks entry rather than merely pricing it: send `0` for do-not-restrict-entry, `1` for restrict-entry. The field is not nullable, so omitting it sends `0` and the timeband does not restrict entry. Values outside `0`–`255` fail with `500`; nothing rejects other values between `0` and `255`, and the behaviour of values other than `0` and `1` is undefined.
`translations`	array of object	No	Localised versions of the timeband's `description`, for tenants running more than one language. Omit it, or send an empty array, and no translations are written — `description` is then the only text available. Translations are saved before the timeband itself, and separately from it, so a create that subsequently fails can leave translations behind with no timeband attached to them.
`translations[].type`	string	No	The name of the property this entry translates. Send `description` in lower case — that is the only property the retrieval endpoints ask for when they read translations back, so an entry with any other value is stored but never returned to you. Maximum 50 characters.
`translations[].culture`	string	No	The culture the translation is written in, for example `cy-GB`. Maximum 20 characters.
`translations[].text`	string	No	The translated description itself. It has no length limit, so the 25-character limit that applies to `description` does not apply here.

Sample request

cURL

curl -X POST '{base_url}/api/configuration/timebands' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "string",
  "description": "string",
  "restrictEntryInd": 1,
  "translations": [
    {
      "type": "string",
      "culture": "string",
      "text": "string"
    }
  ]
}'

Response fields

This endpoint returns no response body. A success is 201 Created with an empty payload, and the identifier — whether you chose it or the platform generated it — is not echoed back. To read the timeband, call GET {base_url}/api/configuration/timebands/{timebandId} with the normalised (upper-cased, space-stripped) form of the id you sent.

Do not rely on the Location header either: it does not correspond to the retrieval route, timebands/{timebandId}.

Sample response

201 Created

HTTP/1.1 201 Created
Content-Length: 0

Errors

Status	Meaning	When
`400`	Bad request	`description` is missing or empty, or exceeds 255 characters. Returned as a validation error object keyed by field name, not as a plain string. Note that a `description` of 26–255 characters passes this check and fails later as a `500`.
`409`	Conflict	"The Timeband {id} already exists" — the normalised form of the `id` you supplied is already in use. Nothing is changed; use `PUT /api/configuration/timebands/{timebandId}` to modify the existing timeband. This check runs only when you supply an `id`.
`409`	Conflict	"This entry already exists in the database" — the timeband already exists, but the duplicate was caught at the final save rather than by the check above.
`500`	Internal server error	Any other failure, most commonly a `description` longer than 25 characters or an `id` longer than 15 characters, neither of which request validation catches. Translations may already have been written when this happens.

This page as markdown · All pages · llms.txt