Idempotency
Retry any write safely with an Idempotency-Key, so a booking or a payment is never made twice.
Networks fail. When a POST to create a booking times out, you can't tell if the booking was made. Send an Idempotency-Key header with every write, and retry with the same key: the API does the work at most once.
How it works
curl -X POST "https://api.chatbeds.app/partner/v1/properties/$PROPERTY/reservations" \
-H "Authorization: Bearer $CHATBEDS_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: b2f1c9e4-booking-BK-104233" \
-d @booking.json| You send | You get |
|---|---|
| A new key | The request runs. Its answer is kept for 24 hours |
| The same key, same request, within 24 hours | The kept answer, with the header Idempotent-Replayed: true. Nothing runs again |
| The same key, a different request | 422: This Idempotency-Key was used for a different request. |
| The same key while the first request is still running | 409: A request with this Idempotency-Key is already being processed. |
| The same key after 24 hours | A new request |
"Same request" means the same method, path and body, byte for byte.
HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replayed: true
{"reservation": {"id": "a589df05-30ad-4ee5-9832-16ff6c2c1d0e", "ref": "A589DF", ...}}Failed requests aren't kept
Only answers that worked are kept. If a write fails (400, 409, 422...), nothing is stored, so you can fix the problem and send again with the same key. For example, after a 409 price change, show the guest the new price and book again with the new expected_total; the same key is fine.
Which operations
Every POST and PATCH takes the header:
| Operation | |
|---|---|
reservation.create | Always send one |
reservation.modify, reservation.cancel, reservation.addExtra | Recommended |
folio.addCharge, folio.addPayment | Always send one: these add money lines |
payment.createLink | Recommended |
GET requests change nothing and ignore the header.
Choosing keys
- One key per attempt at one action, sent again on every retry of that action. Your own booking ID works well for
reservation.create:booking-BK-104233. - Use a new key for a new action, even on the same booking. A second charge needs a new key, or you get the first charge's answer back.
- 1 to 255 characters. A UUID is a good default.
- Keys belong to one credential: two apps may use the same key without clashing.
Belt and braces
external_ref is a second guard for bookings: it is unique per partner and property, for ever. Even after the 24 hours, booking the same external_ref again is refused with 409. Send both.
Building something?