Place a reservation (async — a call is placed to the merchant)

Returns booking_id with state=queued immediately. Poll GET /v1/bookings/{id} or supply callback_url for webhooks. With accept_within_window=true (recommended), merchant counter-offers inside ±window_minutes auto-confirm without a round-trip. Retry safety: send a unique client_reference_id (or Idempotency-Key header); retrying with the same value returns the existing booking (200, idempotent_replay=true) instead of double-booking.

post/v1/bookings

Request

  • Base URL: https://mercantry.org
  • URL: https://mercantry.org/v1/bookings
  • Auth: one of:
    • none
    • API key in header x-api-key

Headers

Idempotency-Keystring

Alias for body field client_reference_id (body wins if both are sent).

Request body

merchant_idstring uuid required
party_sizeinteger required
datetimestring required

Requested time, ISO-8601. Naive (2026-07-18T19:00) means the merchant's local wall time; an explicit offset is also accepted.

window_minutesinteger
accept_within_windowboolean
reservation_namestring required
contactstring

Optional phone/email for confirmation relay to the end human.

special_requestsstring
callback_urlstring

Webhook URL for booking state-change events.

client_reference_idstring

Your unique ID for this booking request (a UUID is ideal). Retrying with the same value returns the existing booking instead of creating a duplicate; scoped per API key.

sandbox_outcome'confirmed' | 'no_answer' | 'counter_offer' | 'fully_booked' | 'merchant_declined' | 'bad_data'

TEST ONLY, sandbox merchants (sandbox: true): force the simulated call's result so an integration can exercise a chosen branch on demand. Rejected with sandbox_outcome_requires_sandbox_merchant for real merchants. Walkthrough: /demo.

Response

Idempotent replay: {ok, booking_id, state, idempotent_replay: true} — an existing booking matched client_reference_id; nothing new was created.

Changes

No recorded changes to this operation across all 1 revision of this API.