Update promo code

PUT /api/configuration/promotion-codes/{id}

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

Overview

Rewrites an existing promo code: the dates it is valid between, how many times it may still be used, whether it is live, whether it applies itself automatically, and which discounts it grants.

This is a full replacement, not a partial update. Every field is mandatory, so there is no way to change one setting without restating the others — read the code first with GET /api/configuration/promotion-codes and send everything back. discountIds is a full-set replace too: the existing discount mappings are deleted and rebuilt from the array you send.

The code string itself is not editable here. The path takes the numeric id, not the code text. (For retrieval, note that fetching by code text requires wrapping the code in curly braces in the path; that quirk does not apply to this endpoint, which only accepts the numeric id.)

Three rules catch integrations out:

Dates cannot be moved into the past. validFrom must be today or later and validTo must be later than today — unless the value you send is exactly the date already held, which is how you update an old code without shifting its dates.
maxUsages cannot be set below the usages still remaining, and because 0 means unlimited it is compared as the number zero: switching a part-used limited code to unlimited is rejected while any usages remain.
Changing maxUsages adjusts the remaining count by the difference, rather than resetting it. Raising a cap from 100 to 150 on a code with 20 left leaves 70 remaining, not 150.

Validation runs before anything is written; the promo code and its discount mappings are then saved together. On success the response is 204 No Content and the change is visible on the next read.

Endpoint

PUT {base_url}/api/configuration/promotion-codes/{id}

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

Path parameters

Name	Type	Required	Description
`id`	integer (int32)	Yes	Numeric identifier of the promo code, as returned when it was created or listed — not the code text customers type. If it matches nothing the request fails with `404 Promotion code {id} does not exist.`

Request body

Field	Type	Required	Description
`validFrom`	string (date-time)	Yes	First day the code can be used. Mandatory (`ValidFrom date must be provided`). Only the date part is kept; any time you send is discarded. It must be today or later, except when it exactly equals the date already stored and that stored date is in the past — otherwise the request fails with `The Valid From date must be from today onwards`. One quirk to be aware of: if you re-send an unchanged past `validTo` and the stored `validFrom` is empty, your `validFrom` is replaced with today's date.
`validTo`	string (date-time)	Yes	Last day the code can be used. Mandatory (`ValidTo date must be provided`), date part only, and must be strictly later than today — today itself is rejected — unless it exactly equals a stored date that is already today or earlier. Otherwise the request fails with `The Valid To date must be a future date`. It must also not be earlier than `validFrom`, which is checked first and fails with `The Valid To date must be after the Valid From date`.
`maxUsages`	integer (int32)	Yes	Total number of times the code may be used. Mandatory (`MaxUsages must be supplied`) and 0 or greater (`Max Usages must be 0 or greater`). `0` means unlimited, and is recorded as `-1`. When the value differs from the one stored, the remaining-usage count is adjusted by the difference rather than reset — so raising the cap adds headroom and lowering it removes headroom. A value below the usages still remaining is rejected with `There are currently {n} usages remaining, maxUsages cannot be less than the usages remaining`; because `0` is compared numerically, this also blocks switching a part-used code to unlimited.
`active`	boolean	Yes	Whether the code is live. Mandatory (`Active must be supplied`) — there is no default, so you must restate it on every update or the request is rejected. Setting it to `false` is how a code is withdrawn without deleting it or changing its dates.
`autoApply`	boolean	Yes	Whether the code is applied automatically rather than having to be typed in by the customer. Mandatory (`AutoApply must be supplied`).
`discountIds`	array of integer	Yes	The discounts this code grants. Mandatory and must contain at least one entry (`At least one discount ID must be supplied`) — a promo code cannot be left granting nothing. Every id must already exist, or the request fails with `The following discount IDs do not exist and can not be mapped to a promo-code: {ids}`, naming the ones it could not find. The existing mappings are deleted and rebuilt from this array, so send the complete set of discounts the code should grant, not just the new ones.

Sample request

cURL

curl -X PUT '{base_url}/api/configuration/promotion-codes/{id}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "validFrom": "2026-08-14T19:00:00Z",
  "validTo": "2026-08-14T19:00:00Z",
  "maxUsages": 1,
  "active": true,
  "autoApply": true,
  "discountIds": [
    12345
  ]
}'

Errors

Status	Meaning	When
`400`	Bad request	A mandatory field is missing, or `maxUsages` is negative — `ValidFrom date must be provided`, `ValidTo date must be provided`, `MaxUsages must be supplied`, `Max Usages must be 0 or greater`, `Active must be supplied`, `AutoApply must be supplied`, `At least one discount ID must be supplied`.
`400`	Bad request	`validTo` is earlier than `validFrom` — `The Valid To date must be after the Valid From date`. Checked before the promo code is even looked up, so it masks a `404`.
`400`	Bad request	`validFrom` is in the past and differs from the stored value — `The Valid From date must be from today onwards`.
`400`	Bad request	`validTo` is today or earlier and differs from the stored value — `The Valid To date must be a future date`.
`400`	Bad request	`maxUsages` is lower than the usages still remaining, including `0` for unlimited — `There are currently {n} usages remaining, maxUsages cannot be less than the usages remaining`.
`400`	Bad request	One or more discount ids do not exist — `The following discount IDs do not exist and can not be mapped to a promo-code: {ids}`.
`404`	Not found	No promo code has that numeric id — `Promotion code {id} does not exist.`
`500`	Internal server error	An unexpected server-side failure, including a failure saving the code or its discount mappings. No detail is returned.

This page as markdown · All pages · llms.txt