Create a block booking schedule with recurring reservations

POST /api/bookings/block-bookings

Success: 200 OK

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

Overview

Books the same slot repeatedly for one member in a single call. You describe the series — a start and end date-time, a frequency, and optionally which days of the week — and the endpoint expands it into individual bookings, creates an activity to hold them, and raises a sales invoice per booking.

The expansion works like this: dateTimeFrom and dateTimeTo supply both the range of the series and the time-of-day of every occurrence, so a slot cannot cross midnight. frequency then decides how the range is walked, and days, recursEvery, recurranceType and recursOn refine it. Dates listed in exclusionDates are dropped.

You must price the series yourself. products carries one entry per product per occurrence, and every date the expansion produces must be covered by at least one entry, or the call fails. Send checkOnly=true first to expand and clash-check the series without writing anything.

Three failure shapes are worth designing for, and all of them return the full response body rather than a message:

occurrences that overlap each other — 400, with overlappingDates populated
clashes with existing bookings or schedule exceptions on the same resources — 409, with existingBookings and existingExceptions populated
nothing created and errors non-empty — 400

On success the call returns 201 Created (or 200 OK for a checkOnly run) with the scheduleId that identifies the series for later updates and deletes.

Block bookings are invoiced, not paid at the till: the payment method must collect through an invoicing account and the member must have one configured, otherwise the request is rejected.

Use this endpoint to:

Reserve a recurring slot — a weekly coaching session, a monthly club night
Dry-run a proposed series against existing bookings before committing it
Create a whole term's bookings, and their invoices, in one call

Endpoint

POST {base_url}/api/bookings/block-bookings

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

Query parameters

Name	Type	Required	Description
`checkOnly`	boolean	No	When true, performs validation and conflict checking only without creating bookings. Returns 200 OK if no conflicts are found.

Request body

Field	Type	Required	Description
`siteId`	string	Yes	The site the series belongs to. Must be non-empty (`Site ID must be specified`) and must exist (`Invalid Site ID '{siteId}'`). It also determines the default payment method used when `paymentMethodId` is omitted, and the counters that allocate booking ids and booking references.
`memberId`	integer (int32)	Yes	The member every booking in the series, and every invoice raised for it, belongs to. Must be 1 or greater (`Member ID must be specified`) and must exist (`Invalid Member ID '{memberId}'`). Their name is used as each booking's display name and their surname supplies the default `description`. Where the payment method collects through an invoicing account, that account must exist on this member.
`products`	array of object	No	The priced lines that become each occurrence's sales invoice, one entry per product per date. Required whenever bookings are actually created (`One or more Products must be specified`); the per-product checks are skipped when `checkOnly=true`, but the time bands in it are still validated, so send it either way. Every date the series generates must be covered by at least one entry, otherwise the call fails with `One or more booking dates have no matching products: {dates}`. Entries whose `date` matches no generated occurrence are ignored.
`products[].date`	string (date-time)	No	Which occurrence this line belongs to. Sent as a real UTC date-time, but only the calendar date is matched against the occurrence's start date. A missing value is rejected with `One or more products are missing a Date`. It is re-based using `dateTimeFrom`'s UTC offset, so a series crossing a daylight-saving change still lines up with the occurrences it generates.
`products[].productId`	string	No	The product invoiced on that date. Must be an existing standard product (`One or more Product IDs are invalid '{ids}'`). The same product may repeat across different dates, but not twice on the same date — that is rejected with `Duplicate product entries for the same date: {product} on {date}`.
`products[].quantity`	integer (int32)	No	How many units of the product to invoice for that occurrence. Must be greater than zero (`One or more products have an invalid quantity`). The invoice line total is `price` multiplied by this.
`products[].price`	number (double)	No	The unit amount invoiced for the line. Must be zero or greater (`One or more products have an invalid price`). The series is not priced for you — the value you send is used on the invoice line as-is, and the invoice total is the sum of price × quantity across the lines for that occurrence.
`products[].taxCodeId`	string	No	The tax code the line is charged under. Required on every entry (`One or more products are missing a Tax Code ID`); its rate is applied and both are recorded on the invoice line.
`products[].timeBandId`	string	No	The time band the line is charged under, recorded on the invoice line. Required on every entry (`One or more products are missing a Time Band ID`) and must be an existing time band (`One or more Time Band IDs are invalid '{ids}'`).
`activityGroupId`	string	No	The activity group the activity created for this series is filed under. Required whenever bookings are actually created (`Activity Group ID must be specified`) and must exist (`Invalid Activity Group ID '{id}'`); both checks are skipped when `checkOnly=true`.
`frequency`	string	Yes	How the series repeats: `Daily`, `Weekly` or `Monthly`, matched case-insensitively. Anything else is rejected with `Invalid Frequency '{value}', must be one of 'Daily', 'Weekly', 'Monthly'`. This choice decides which of `recursEvery`, `recurranceType` and `recursOn` are permitted — sending one that does not apply is an error rather than being ignored.
`recursEvery`	integer (int32)	No	The gap between repeats: every N weeks for `Weekly`, every N months for `Monthly`. Defaults to `1` when omitted and must be greater than zero. Must not be sent for `Daily`, which always steps a day at a time (`RecursEvery cannot be specified for Daily frequency`).
`recurranceType`	string	No	Only for `frequency: Monthly`, where it is mandatory (`RecurranceType must be specified for Monthly frequency`). `ByDate` repeats on the same day of the month as `dateTimeFrom` and forbids `recursOn` and `days`; `ByDay` repeats on the nth named weekday of the month and requires both. Any other value is rejected with `Invalid RecurranceType '{value}', must be one of 'ByDate', 'ByDay'`. Must not be sent for `Daily` or `Weekly`.
`recursOn`	integer (int32)	No	Which occurrence of the weekday within the month, `1` to `5`. Required, and only allowed, when `frequency` is `Monthly` and `recurranceType` is `ByDay`; a value outside 1–5 is rejected with `RecursOn must be between 1 and 5`. Must not be sent for `Daily`, `Weekly` or `ByDate`.
`paymentMethodId`	string	No	How the invoices raised for the series are collected. Omit it and the site's default host payment method is used. A supplied value must exist (`Invalid Payment Method ID '{id}'`). Whether supplied or defaulted, it must be a method that collects through an invoicing account and the member must have that account configured — otherwise the request fails with `Payment method '{id}' is not an invoicing account. Block bookings must be paid via an invoicing account.`, returned as a `400`.
`resourceProductIds`	array of string	Yes	The resource products reserved on every occurrence in the series — the things being booked out, as opposed to the `products` being charged for. At least one is required (`One or more Resource Products must be specified`), duplicates are rejected (`Duplicate Resource Product IDs found in request`) and each must exist (`One or more Resource Product IDs are invalid '{ids}'`). These are also what clash detection runs against: an existing booking or schedule exception on any of them, overlapping any generated occurrence, blocks the request.
`days`	array of string	No	Restricts the series to particular days of the week. Use full English day names, matched case-insensitively (`monday`, `tuesday`, …); an unrecognised name is rejected with `Invalid day in request` and repeats with `Duplicate Days found in request`. Omit it, or send an empty array, and every date in range that the frequency produces is used. For `frequency: Monthly` it is required with `recurranceType: ByDay` and forbidden with `ByDate`.
`dateTimeFrom`	string (date-time)	Yes	Start of the series, as a real UTC date-time. Its date is the first date an occurrence can fall on; its time of day is the start time of every occurrence. It must be supplied (`Invalid DateTimeFrom or DateTimeTo`) and must be earlier than `dateTimeTo`. Its UTC offset is also the reference used to interpret `dateTimeTo`, `exclusionDates` and `products[].date`, which keeps every occurrence at the same wall-clock time across a daylight-saving change.
`dateTimeTo`	string (date-time)	Yes	End of the series, as a real UTC date-time. Its date is the last date an occurrence can fall on; its time of day is the end time of every occurrence. It must be later than `dateTimeFrom` both overall and by time of day, so a single occurrence cannot run past midnight (`DateTimeTo time ({time}) must be after DateTimeFrom time ({time})`); model an overnight slot as separate series.
`exclusionDates`	array of string	No	Dates to skip — a closure day or a holiday, for instance. Only the calendar date is compared, so the time component is irrelevant. Every entry must fall between `dateTimeFrom` and `dateTimeTo` (`Exclusion dates must fall within the booking date range…`) and none may repeat (`Duplicate exclusion dates found in request`). Excluded dates are echoed back in the response's `excludedDates`, and no product entry is needed for them.
`notes`	string	No	Free-text comments copied onto every booking in the series. Omit it and each booking's comments are an empty string.
`reference`	string	No	Your own reference, stored on every booking the series creates. Maximum 255 characters.
`activityId`	string	No	An identifier of your own for the activity that holds the series. Omit it and a unique one is generated. If supplied it must be 15 characters or fewer (`ActivityId cannot exceed 15 characters`) and must not already be in use (`ActivityId '{id}' already exists`); both checks also run under `checkOnly=true`, so you can validate a candidate id before committing. If every booking then fails to create, the activity is removed so the same id can be retried.
`description`	string	No	The booking name, shown against every occurrence in the series. Maximum 25 characters: a longer value is rejected with `400` and the message `Booking name cannot be greater than 25 characters`, and nothing is created, even when `checkOnly=true`. Leave it blank and each booking is described as `Hosted {member surname}`. To rename the series later, send a new value to Update an existing block booking schedule with `editType: All`; a rename is not possible from a given date onwards.
`invoiceGroupingPeriod`	integer (int32)	Yes	Required — an absent value is rejected with `Invoice Grouping Period must be specified`, and it has no default. An integer from 0 to 255, set as the activity's invoice grouping period indicator.
`invoiceItemisation`	boolean	Yes	Required — an absent value is rejected with `Invoice Itemisation must be specified`, and it has no default. Sent as a boolean; the activity records it as `1` for itemised or `0` for not.
`participantNumber`	integer (int32)	No	A theoretical participant capacity for the activity, held for reporting only — it is not enforced against the number of people actually booked. Set as both the minimum and maximum bookee count on the activity. Must be between 0 and 32767; omitted on create, it defaults to `0`.

Sample request

cURL

curl -X POST '{base_url}/api/bookings/block-bookings' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "siteId": "string",
  "memberId": 12345,
  "products": [
    {
      "date": "2026-08-14T19:00:00Z",
      "productId": "string",
      "quantity": 1,
      "price": 10.5,
      "taxCodeId": "string",
      "timeBandId": "string"
    }
  ],
  "activityGroupId": "string",
  "frequency": "string",
  "recursEvery": 1,
  "recurranceType": "string",
  "recursOn": 1,
  "paymentMethodId": "string",
  "resourceProductIds": [
    "string"
  ],
  "days": [
    "string"
  ],
  "dateTimeFrom": "2026-08-14T19:00:00Z",
  "dateTimeTo": "2026-08-14T19:00:00Z",
  "exclusionDates": [
    "2026-08-14T19:00:00Z"
  ],
  "notes": "string",
  "reference": "string",
  "activityId": "string",
  "description": "string",
  "invoiceGroupingPeriod": 1,
  "invoiceItemisation": true,
  "participantNumber": 1
}'

Response fields

Field	Type	Description
`bookingIds`	array of integer	The ids of the bookings that were created, one per occurrence, in the order they were created. Empty for a `checkOnly` run, and empty if every booking failed.
`dates`	array of object	The occurrences that were created, with their booking and invoice ids. On a `checkOnly` run the same list is returned to show what would be created, but with `bookingId` and `salesInvoiceId` of `0`. Occurrences that failed appear in `failedBookings` instead.
`dates[].bookingId`	integer (int32)	The id of the booking created for this occurrence; use it against the single-booking endpoints. `0` on a `checkOnly` run.
`dates[].salesInvoiceId`	integer (int32)	The id of the sales invoice raised for this occurrence from its matching `products` entries. `0` on a `checkOnly` run.
`dates[].startDate`	string (date-time)	When the occurrence starts, in real UTC — the occurrence's date at `dateTimeFrom`'s time of day.
`dates[].endDate`	string (date-time)	When the occurrence ends, in real UTC — the same date at `dateTimeTo`'s time of day.
`excludedDates`	array of string	The `exclusionDates` you sent, echoed back as plain dates. Empty when you sent none.
`scheduleId`	string (uuid)	Identifies the series as a whole; keep it, as the update and delete block-booking endpoints work on this rather than on individual bookings. It is generated only when bookings are actually created, so a `checkOnly` run and any failed request return the empty GUID `00000000-0000-0000-0000-000000000000`.
`selectedDates`	array of object	Every occurrence the recurrence rule produced, after `days` filtering and `exclusionDates` removal, whether or not it was created. It is returned even when the request fails, so it is the field to read when checking that your rule expands to the dates you expected.
`selectedDates[].startDate`	string (date-time)	Start of the generated occurrence, in real UTC.
`selectedDates[].endDate`	string (date-time)	End of the generated occurrence, in real UTC.
`errors`	array of string	Why the series was refused, as sentences — for example `No valid dates found for the specified days`, `One or more bookings overlap with each other`, `One or more bookings overlap with existing bookings for the same product(s)`, `One or more bookings overlap with existing exceptions for the same product(s)` or `All bookings failed to create`. Present and non-empty with no `bookingIds` means nothing was written, and the call returns `400`.
`overlappingDates`	array of object	Occurrences in this request that overlap one another — usually a recurrence rule that produces two slots on the same day. Any entry here makes the response a `400` and nothing is created.
`overlappingDates[].dateTimeFrom`	string (date-time)	Start of the occurrence that clashes with a later one, in real UTC.
`overlappingDates[].dateTimeTo`	string (date-time)	End of that occurrence, in real UTC.
`overlappingDates[].productId`	string	Never included for this list, because a self-overlap is between two occurrences rather than against a particular product. Do not depend on it.
`existingBookings`	array of object	Bookings that already exist on one of your `resourceProductIds` and overlap a generated occurrence. Any entry here makes the response a `409` and nothing is created; free the resource, change the times, or exclude the date, then retry.
`existingBookings[].bookingId`	integer (int32)	The id of the clashing booking.
`existingBookings[].recurringScheduleId`	string (uuid)	The schedule the clashing booking belongs to, when it is itself part of a block booking. Null for an ad-hoc booking.
`existingBookings[].dateTimeFrom`	string (date-time)	Start of the clashing booking, in real UTC.
`existingBookings[].dateTimeTo`	string (date-time)	End of the clashing booking, in real UTC.
`existingBookings[].productId`	string	Which of your `resourceProductIds` the clash is on. A single booking appears once per resource it clashes on.
`existingExceptions`	array of object	Schedule exceptions — periods where a resource is unavailable — that overlap a generated occurrence. Treated like `existingBookings`: any entry makes the response a `409` and nothing is created.
`existingExceptions[].dateTimeFrom`	string (date-time)	Start of the blocking exception, in real UTC.
`existingExceptions[].dateTimeTo`	string (date-time)	End of the blocking exception, in real UTC.
`existingExceptions[].productId`	string	Which of your `resourceProductIds` the exception applies to.
`failedBookings`	array of object	Occurrences that passed validation but could not be written. Creation is per-occurrence, not all-or-nothing: a partly successful call returns `201` with entries in both `dates` and `failedBookings`, so check this list even on success. If every occurrence failed, `errors` carries `All bookings failed to create` and the activity created for the series is removed.
`failedBookings[].startDate`	string (date-time)	Start of the occurrence that could not be created, in real UTC.
`failedBookings[].endDate`	string (date-time)	End of that occurrence, in real UTC.
`failedBookings[].error`	string	The failure message explaining why that occurrence could not be created.

Sample response

200 OK

{
  "bookingIds": [
    12345
  ],
  "dates": [
    {
      "bookingId": 12345,
      "salesInvoiceId": 12345,
      "startDate": "2026-08-14T19:00:00Z",
      "endDate": "2026-08-14T19:00:00Z"
    }
  ],
  "excludedDates": [
    "string"
  ],
  "scheduleId": "b7f3c1e2-9a44-4f2b-8c17-0d5e9a1b6c33",
  "selectedDates": [
    {
      "startDate": "2026-08-14T19:00:00Z",
      "endDate": "2026-08-14T19:00:00Z"
    }
  ],
  "errors": [
    "string"
  ],
  "overlappingDates": [
    {
      "dateTimeFrom": "2026-08-14T19:00:00Z",
      "dateTimeTo": "2026-08-14T19:00:00Z",
      "productId": "string"
    }
  ],
  "existingBookings": [
    {
      "bookingId": 12345,
      "recurringScheduleId": "b7f3c1e2-9a44-4f2b-8c17-0d5e9a1b6c33",
      "dateTimeFrom": "2026-08-14T19:00:00Z",
      "dateTimeTo": "2026-08-14T19:00:00Z",
      "productId": "string"
    }
  ],
  "existingExceptions": [
    {
      "dateTimeFrom": "2026-08-14T19:00:00Z",
      "dateTimeTo": "2026-08-14T19:00:00Z",
      "productId": "string"
    }
  ],
  "failedBookings": [
    {
      "startDate": "2026-08-14T19:00:00Z",
      "endDate": "2026-08-14T19:00:00Z",
      "error": "string"
    }
  ]
}

Errors

Status	Meaning	When
`400`	Bad request	Validation failed: a missing or malformed field, an unknown site, member, activity group, product, resource product, time band or payment method, a payment method that does not collect through an invoicing account, or a generated booking date with no matching product entry. Also returned when the generated occurrences overlap each other (body carries `overlappingDates`), when nothing was created and `errors` is non-empty, and when saving fails — `A database error occurred. Please ensure that the ID supplied is unique`.
`400`	Bad request	`description` is longer than 25 characters (`Booking name cannot be greater than 25 characters`). Nothing is created.
`404`	Not found	Not returned for unknown references — an unknown site, member, activity group, product or resource product returns `400`.
`409`	Conflict	Existing bookings, or schedule exceptions, on the requested `resourceProductIds` overlap one or more generated occurrences. The body is the full response with `existingBookings` and `existingExceptions` populated, so you can resolve the clashes and retry. Nothing is created.
`422`	Unprocessable entity	Not returned — a payment method that is not an invoicing account returns `400`.
`500`	Internal server error	An unexpected internal server error occurred.

This page as markdown · All pages · llms.txt