L'objet option

Une option, c’est une prise sur un créneau qui occupe une vraie table sans être une réservation. Elle revient de tous les appels d’Options et de tous les webhooks hold.*.

Champs

Le tableau ci-dessous est généré depuis la spécification OpenAPI et reste en anglais, comme la référence de l'API : noms de champs, valeurs d'énumération et descriptions viennent du backend. Une traduction serait une copie qui ment dès la première évolution du contrat.

objectstring

Valeurs possibles : hold

The object type: always hold.

idstring

Opaque hold id (hold_…). A hold and the reservation it becomes are the same row and share this id’s suffix, so hold_AbC converts into resv_AbC.

kindstring

Valeurs possibles : basket commitment

basket releases the table the instant expires_at passes; commitment keeps it until the sweep that runs every five minutes picks the hold up. Both lapse on their own; only the minutes between the deadline and the table reopening differ.

statusstring

Valeurs possibles : held expired released converted

Lifecycle of the hold itself, not of a reservation.

• held: live and occupying a table. The only state a conversion works from.
• expired: the deadline passed and the table is back on sale. On a basket hold this is reported from the moment expires_at passes, because that kind reopens its table at read time. On a commitment hold the table is held past the deadline until the five-minute sweep resolves it, so the hold reads held for up to five minutes after expires_at and expired from then on. Either way it is the same lapse, and hold.expired announces it.
• released: handed back deliberately — you called DELETE /v1/holds/{id}, or the restaurant released it from its own board.
• converted: it became the booking named in reservation.

party_sizeinteger

How many guests the held seating is for.

service_datestring (date)

The service day of the held seating, YYYY-MM-DD in the restaurant’s timezone. A seating after midnight keeps the date its service began on.

starts_atstring (date-time)

Start of the SEATING the hold covers — not the hold deadline. ISO 8601 with the restaurant’s UTC offset.

ends_atstring (date-time)facultatifnullable

End of the seating the hold covers, in the same format. null when no seating duration applies.

expires_atstring (date-time)nullable

When the hold lapses. Authoritative: the server sets it, clamping whatever was requested. Null once the hold is over.

ended_atstring (date-time)nullable

When the hold was released or lapsed. Null while it is live, and null once it has converted — a converted hold did not end, it became the booking named in reservation.

reservationstringnullable

The booking this hold became (resv_…), or null.

tablesarray of Table

The tables the hold occupies, each with its seating area.

excluded_from_shift_limitsboolean

True when this hold does not count against the shift’s covers caps, with the same meaning as on a reservation: they neither charge it nor refuse it. It is carried onto the booking when the hold converts, so converting an exempt hold needs the reservations:write:override scope.

metadataobject

Your own reconciliation data, echoed verbatim. Carried onto the reservation when the hold converts. ⚠️ Readable by every integration this restaurant has authorised, not only by the one that wrote it: holds are scoped to the restaurant, so another of its API keys can read this hold and this object. Put reconciliation ids here, not commercial terms or anything you would not show a competitor.

created_atstring (date-time)

When the hold was taken: ISO 8601 with the restaurant’s UTC offset.

updated_atstring (date-time)

When the hold last changed, in the same format.

Les quatre statuts

Une option naît held et quitte cet état une seule fois. Vous la rendez (released), elle expire d’elle-même (expired) ou elle devient la réservation nommée dans reservation (converted). Les trois sont terminaux et held est le seul état depuis lequel une conversion fonctionne.

kind décide de la vitesse à laquelle une expiration se voit, pas de son existence. Les deux genres expirent seuls ; ce qui diffère, ce sont les minutes entre l’échéance et la remise en vente de la table, et la description du champ dit lesquelles.

Ce que l’option transmet

Trois choses passent de l’option à la réservation qu’elle devient, ce qui vaut la peine de les poser sur l’option plutôt qu’à la création :

• Le suffixe de l’identifiant. hold_AbC devient resv_AbC, donc une référence que vous avez stockée sur l’option désigne encore la réservation.
• metadata, à l’identique.
• excluded_from_shift_limits. Convertir une option exemptée demande donc la portée reservations:write:override, comme poser le marqueur sur une réservation.

Une option n’a ni client, ni coordonnées, ni guest_notes. Tout cela arrive à la conversion, sur le POST /v1/reservations qui porte le hold_id.

Ce que porte un webhook

hold.created, hold.converted, hold.released et hold.expired livrent l’objet entier dans data.object. Quel changement déclenche lequel est dans le catalogue d’événements.