Skip to content

List service periods

GET
/api/v1/service-periods

The hospitality engine's service periods: which days a venue serves, between which times, on what turn. Engine-guarded, ordered by id: see GET /api/v1/services for why.

This is the endpoint that makes reservation availability explicable rather than magic. No active period for a weekday means an empty grid that day, and a program told "no availability" with no way to see why will simply keep asking.

startTime, endTime and lastSeating are wall-clock HH:MM:SS in the organization's own timezone (on GET /api/v1/organization), not instants. A service period is a rule about clock time, not a moment, so converting them here would be lossy. Group by dayOfWeek for a week grid.

Authorization

bearerApiKey service-periods:read
AuthorizationBearer <token>

Build with a test key (sk_test_...): it works only in your API sandbox and never emails or texts anyone. Scopes, errors and limits.

In: header

Scope: service-periods:read

Query Parameters

limit?integer

Clamped, never rejected: values below 1 or unparseable fall back to 50, values above 200 become 200. A ?limit=1e9 from a program is far more likely to be a client bug than an attack, and answering 200 rows beats answering an error it retries in a loop.

Range1 <= value <= 200
Default50
cursor?string

The nextCursor from the previous response, passed back unchanged. Omit it for the first page. Opaque: it is base64url of an internal position and the encoding is not part of the contract; treat it as a token, do not construct one. A cursor this API did not issue is a 400 invalid_cursor rather than a silently-ignored parameter, because silently restarting at page one is how a paging loop becomes an infinite one.

The scheme is keyset (seek) paging on (order column, id), not OFFSET. OFFSET is wrong under concurrent writes: a booking created between page 1 and page 2 shifts every later row back by one, and the caller silently never sees whichever row slid across the boundary. Filters and limit may change between pages; the cursor only says where you got to.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/service-periods"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "dayOfWeek": 0,      "startTime": "string",      "endTime": "string",      "lastSeating": "string",      "turnMinutes": 0,      "slotMinutes": 0,      "maxCovers": 0,      "active": true    }  ],  "nextCursor": "string"}

Record what a party spent (API key, POS)POST

A till reports a check's **total**, in the venue's currency's minor units. Never line items: itemised sales stay in the POS. This records spend against the visit and charges nothing. Idempotent by `externalId`, the till's own check number: sending it again updates the same check (reopened, a tip added, `voided`), so no `Idempotency-Key` is needed and a visit is never counted twice; a refund is the same check resent with its new total. Check numbers are kept apart per partner (the key's partner label, or the key itself), so two tills can both use 1001. A check number already on another reservation is refused. Any other field, line items included, is ignored and never stored. The guest's lifetime figure is `lifetimeSpend` on `GET /api/v1/clients`. `201` for a new check, `200` for an update.

Subscribe a webhookPOST

Registers an https endpoint for booking and guest events, owned by the calling key: what an automation tool calls when a user switches a trigger on (REST hooks). The same endpoints, signature (`Gaplessly-Signature`), retries and address rules as webhooks added in the dashboard; see the webhooks guide for verifying a delivery. **Each event also needs the read scope for its data**, because a webhook pushes what a list endpoint would return: `booking.created`, `booking.updated` and `booking.cancelled` need `reservations:read` (or `appointments:read`), and `guest.created` and `guest.merged` need `clients:read`. `check.updated` (a till's check total, table reservations only; an appointments business is a `400`) needs `reservations:read`. `message.received` (a guest's message, with its text) needs `messages:read`. `enquiry.created` and `enquiry.updated` (a big group's enquiry, table reservations only) need `reservations:read`. Without it the answer is `403 insufficient_scope` naming the missing scope. Only the key that registered an endpoint can remove it, and revoking the key removes all of its endpoints. At most 3 per key, within the organization's 10. A test key's endpoint hears only its sandbox's bookings. The signing `secret` is in this response and nowhere else. **Safe to retry.** A key subscribing a URL it already subscribed gets that endpoint back with `200`, secret included, rather than a second endpoint that would deliver every event twice. A repeat does not change the events; to change them, unsubscribe and subscribe again.