Create promotion

POST /api/configuration/promotions

Success: 201 Created

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

Overview

Builds a complete promotional offer in one call. The endpoint performs three steps in sequence: it creates one discount for every membership type you list, creates one promo code for every code string you supply, and finally creates the promotion record that ties them together. A promotion is the container an operator manages; the discount holds the money, and the promo codes are what a member types in to claim it.

You do not choose the identifier. On success you get 201 Created and a body containing the integer id the platform allocated for the promotion, plus the name you sent. Use that id with Retrieve promotion by id, Update promotion and Delete promotion.

The call is not idempotent and not all-or-nothing. There is no idempotency key, and promotion names are not checked for uniqueness, so two identical requests that carry no promoCodes produce two separate promotions with different ids. Promo code strings, by contrast, are unique across the whole account: repeat a request that carried codes and it fails at the second step with 400 and a message ending A promo-code with the code '{code}' already exists with an ID of {id}. Because the three steps are not all-or-nothing and nothing is rolled back, that failed retry still leaves a fresh set of discounts behind. If a call fails part-way, clean up before retrying rather than sending the same body again.

Everything the request references must already exist. discount.membershipTypeIds are validated against the membership types on the account, and discount.siteId, if you send one, against the sites.

Endpoint

POST {base_url}/api/configuration/promotions

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

Request body

The body has two required top-level objects: promotion and discount. The table below describes the members of promotion; the members of discount follow underneath it. Send the wrapped form shown in the sample request, not the promotion fields unwrapped at the top level.

discount is required — omit the object entirely and the call fails with Discount is required. Its members are:

• membershipTypeIds (array of string, required) — the membership types the discount applies to, taken from Retrieve all membership types. One discount is created per id, all sharing the amounts below. The list may not be empty, may not repeat an id, and every id must exist.
• discountRegularAmount (number, required) — the percentage off the recurring subscription payments, applied for the number of months in discountUntilUnit. Between 0 and 100; 0 means no regular discount. Send 0 rather than omitting the field — a missing value fails validation.
• discountIntroductoryAmount (number, required) — the percentage off the initial fee. On a Direct Debit membership this covers only the first pro-rata portion. Same 0–100 scale and the same "send 0 for none" rule.
• discountOneOffAmount (number, required) — the percentage off the one-off joining fee, on memberships that charge one. Same 0–100 scale and the same "send 0 for none" rule.
• discountUntilUnit (integer, required) — the number of months the regular discount lasts for. 0 combined with a discountRegularAmount above 0 makes the discount perpetual — it never lapses. Must be 0 or greater, and may only be greater than 0 when discountRegularAmount is greater than 0.
• discountBanner (string, optional) — free text shown as a banner alongside the offer. Maximum 510 characters. Blank or whitespace-only is saved as null.
• discountText (string, optional) — free text describing the offer. Maximum 510 characters. Blank or whitespace-only is saved as null.
• isActive (boolean) — ignored. It is always replaced by promotion.isActive.
• siteId (string, optional) — restricts the discount to a single site, taken from Retrieve all sites. To apply the discount across every site, send null, an empty string or omit the field — all three are normalised to "no site restriction" before validation. Only one site can be named; there is no list. An id that does not exist fails with Discount could not be created as siteId does not exist.

Sample request

curl -X POST '{base_url}/api/configuration/promotions' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "promotion": {
    "promotionName": "Summer 2026 joining offer",
    "validFrom": "2026-06-01T00:00:00Z",
    "validTo": "2026-08-31T00:00:00Z",
    "isActive": true,
    "promoCodes": [
      "SUMMER26"
    ],
    "promotionType": "Membership"
  },
  "discount": {
    "membershipTypeIds": [
      "GYMPLUS"
    ],
    "discountRegularAmount": 10,
    "discountIntroductoryAmount": 0,
    "discountOneOffAmount": 100,
    "discountUntilUnit": 3,
    "discountBanner": "Summer offer",
    "discountText": "10% off for your first three months and no joining fee",
    "isActive": true,
    "siteId": null
  }
}'

Sample response

{
  "id": 4127,
  "name": "Summer 2026 joining offer"
}

Errors

Every failure below is returned as a 400, with the underlying message wrapped in the text Error creating promotion code: {message}, whichever of the three steps failed. Read the trailing message, not the prefix — it says "promotion code" even when the discount or the promotion itself was the problem.

This page as markdown · All pages · llms.txt