Changer l'heure d'une option

Vous retenez 20:00 pour un groupe de quatre et le client veut maintenant 21:00. L’API n’a aucun appel qui déplace une option : /v1/holds permet de créer, de lire et de libérer, rien qui modifie l’heure, la date, la taille du groupe ou la section, et une conversion qui nomme un autre créneau que celui de son option est refusée. Pour changer d’heure, vous posez une nouvelle option, puis vous libérez l’ancienne — un échange — avec des lectures de disponibilité entre les deux.

Le cas se présente surtout dans un parcours package qui pose son option tôt, pendant que le panier s’assemble encore, puis laisse le client changer d’avis. Poser et libérer une option est décrit dans Poser une option.

Lire les disponibilités sans votre propre option

Une option occupe sa table pendant toute la durée de réservation : chaque créneau qui la chevauche la perd, et ses couverts pèsent sur le plafond du service. Un parcours qui retient 20:00 et demande ensuite ce qui reste libre lit une journée dont 20:00 a disparu, et si l’option a pris la dernière table pour cette taille de groupe, le client se voit refuser l’heure qu’il retient lui-même.

excluding répond comme si l’option n’existait pas :

curl -G "https://api.useservice.app/v1/availability" \
  -H "Authorization: Bearer $SERVICE_API_KEY" \
  -d service_date=2026-10-04 \
  -d party_size=4 \
  -d excluding=hold_AbC3xK9

Le paramètre accepte un identifiant hold_… ou le resv_… d’une réservation, et uniquement des identifiants que votre clé pouvait déjà lire : une valeur qui ne répond pas sur GET /v1/holds/{id} ou GET /v1/reservations/{id} donne un 404, et une valeur qui n’a ni l’une ni l’autre forme donne un 400 nommant excluding. Il fait varier l’ETag, si bien qu’un parcours qui revalide reçoit bien la réponse sans l’option, et non celle qu’il avait déjà.

GET /v1/availability/months l’accepte aussi. La maille du calendrier est plus grossière, mais dans une petite salle une seule option suffit à vider une journée — et un calendrier qui grise la date que le client retient ne lui laisse nulle part où aller, puisqu’il se trouve en amont de la vue du jour qui lui aurait permis d’y revenir.

Poser la nouvelle option avant de libérer l’ancienne

Libérer puis créer ouvre une fenêtre pendant laquelle la table est à la vente et quelqu’un d’autre peut la prendre. Créer puis libérer n’en ouvre aucune : vous retenez deux tables le temps d’un aller-retour, et vous lâchez la perdante.

1. POST /v1/holds sur la nouvelle heure, prise dans la lecture des disponibilités. Une heure à laquelle le service n’accueille pas d’arrivée est refusée avec start_time_off_grid, et vous détenez toujours l’option d’origine.
2. En cas de succès, DELETE /v1/holds/{ancien_id}.
3. En cas d’échec, vous retenez toujours l’originale. Dites au client que cette heure vient de partir et laissez-le sur celle qu’il a. Une seule exception : un hold.released que vous n’avez pas provoqué signifie que le restaurant a libéré l’originale depuis son back-office, et il ne reste alors rien sur quoi le laisser.

Ne pas reposer une option à chaque clic

Les écritures sont limitées à une par seconde, avec une réserve de 20 et 2 000 par jour — voir Limites de débit. Un client qui bascule entre six heures, c’est douze écritures pour une réservation, et un samedi de ce régime atteint le plafond quotidien à lui seul. Posez l’option quand le client s’engage — sur « continuer », pas sur la sélection — et servez tout ce qui précède avec des lectures de disponibilité et excluding.

Les échanges arrivent dans vos webhooks comme du bruit

Chaque échange émet un hold.created et un hold.released. Un consommateur qui se synchronise sur ces événements voit six options et cinq libérations pour un groupe qui a réservé une fois : rapprochez sur la réservation plutôt que sur le flux des options.

Ce qu’une option posée tôt ne vous achète pas

Elle protège l’heure que vous avez proposée, si le client la prend. Dès qu’il en change, l’option n’a rien acheté pour l’heure qu’il a choisie : cette table n’a jamais été retenue, et la nouvelle option peut échouer comme n’importe quelle écriture.