Reserves
Court booking for external booking services (aggregators).
Model. A court (res_object) belongs to a branch and a room (location). The online services linked to a court define the booking options: each service has a duration and a price. A booking is identified by the external service’s own external_id (up to 64 characters: Latin letters, digits, -, _), unique per Api-Key. Bookings are visible to and can be changed only with the Api-Key that created them. Every booking belongs to a club client: the client is found by phone number within the club network, or created.
Lifecycle.
GET /reserves/availability— free starts with options and base prices.POST /reserves— create the booking (unpaid). The response tells how much the client has to pay (payment.to_pay) and which payment methods are available (payment.methods).- Pay with one of the methods:A booking with
to_pay = 0is paid on creation (method: free).card—POST /reserves/{external_id}/payreturns the URL of the LuckyFit payment page; the client pays there through the club’s payment service, and the booking becomes paid when the payment completes;ticket/deposit— paid from the client’s membership or deposit. The client confirms with a code first:POST /reserves/{external_id}/codesends it by e-mail or SMS;external— the external service took the money itself and records the payment;in_club— nothing is paid now, the client pays at the club (only if the club allows unpaid bookings).
POST /reserves/{external_id}/cancel— cancel under the club’s rules.GET /reserves/changes— poll for changes: payment completed on the payment page, booking moved or cancelled by the club, unpaid booking expired. Or receive them as webhooks (see below).
Webhooks. Register an https URL with PUT /reserves/webhook (one webhook per Api-Key) to be notified, instead of polling, when:
- a court becomes busy, free, or a busy time changes — whoever booked it (club staff, the club’s mobile app, any external service, including you):
slot.occupied,slot.changed,slot.released(schemaReserveSlotWebhookEvent). Only courts visible inavailabilityof the branches available to the Api-Key, and only future bookings; no client data; - one of your bookings changed (payment completed, moved, cancelled, expired):
reserve.changedwith the current booking, the same object as in/reserves/changes(schemaReserveBookingWebhookEvent).
Delivery: POST with a JSON body, one event per request, headers X-LuckyFit-Event-Id, X-LuckyFit-Timestamp (Unix seconds) and X-LuckyFit-Signature: sha256=<hex>, where <hex> is HMAC-SHA256 of "<X-LuckyFit-Timestamp>.<raw body>" with the webhook secret. Reply with any 2xx within 5 seconds. On an error or timeout the delivery is repeated (after 30 s, 1, 5, 15, 30 minutes, then hourly); an event that cannot be delivered within about a day is dropped. Delivery order is not guaranteed and events may be repeated — deduplicate by id, apply slot events as an upsert by slot.id (the booking ID) and ignore an event older (occurred_at) than the one already applied to the same booking. availability remains the source of truth: re-read it after downtime. The room’s limit of simultaneous bookings and the service’s allowed hours are not sent as events — they are reflected only in availability.
Club rules. The API follows the booking rules the club has set for its mobile app:
- online court booking must be enabled;
- the start must be within the club’s booking window (not earlier / not later than N hours before the start);
- the number of a client’s future court bookings may be limited;
- booking may be restricted to clients with an active membership;
- if the club does not allow unpaid bookings, an unpaid booking is cancelled automatically at
payment.expires_at(cancelled_by: expired); - cancellation deadline and refunds follow the club’s settings.
Prices. availability returns the base price of the branch, and POST /reserves checks price against it. payment.to_pay of the booking includes the client’s personal discount, if any.
Test mode. There is no separate test flag: the club provides a test branch and an Api-Key restricted to that branch.
Errors. Business errors return 200 OK with success: false, a message in error and a string code in error_code:
| When |
|---|---|
| missing or invalid parameters, or the operation does not fit the booking state |
| the branch is not available to the Api-Key |
| the club’s booking rules forbid the booking (disabled, outside the booking window, limit reached, no active membership) |
| no such court |
| the service is not an online service of the court |
| the start is not on the court’s time grid |
| the time is taken or otherwise not available |
| the price does not match; the correct one is in |
| no such booking for this Api-Key |
| the payment method is not available for this booking (see |
|
|
| the code is wrong or expired, or too many attempts |
|
|
| the |
| too late to cancel under the club’s rules |
| the payment can be refunded only at the club |
A missing or invalid Api-Key still returns 401 Unauthorized.
Endpoints
/reserves/availability?organization_id=&date=2026-11-10&days=1&res_object_id=
/reserves
/reserves/{external_id}
reserves/{external_id}/code
/reserves/{external_id}/pay
/reserves/{external_id}/cancel
reserves/changes?since=2026-11-09T12:00:00.000Z&limit=500
reserves/webhook
reserves/webhook
/reserves/webhook
reserves/webhook/test