ChatBeds개발자
API 레퍼런스

이 페이지는 아직 번역되지 않아 영어 버전을 보고 계십니다.

Negotiation

Ask the hotel for private offers for your guest's stay, counter, and book the agreed one: inside the hotel's own limits.

Hotels that bargain let Ana, ChatBeds' AI receptionist, make private offers inside limits the owner sets. Your app can take part for its guests: ask for offers for a stay, counter with what the guest would pay, and book the offer they accept. It is the same negotiation the hotel runs on its booking page, WhatsApp and the phone, with the same rules:

  • Trades, not discounts. Each kind of offer unlocks part of the allowance: base (the guest's dates), pay_now (the whole stay paid when booking), longer (one more night) and dates (a quieter date, when the guest can move).
  • Never under the floor. No night is priced under the hotel's lowest price for its room type, and how much comes off depends on how full the hotel is.
  • Private. Offers are prices for one stay, with an expiry. They are never a public rate, and the hotel's limits are never shown to you.

The hotel turns it on

Negotiation is off for partner apps until the hotel turns on Partner apps in Revenue → Negotiation. Until then, starting one answers 409. negotiation.terms tells you whether it is open.

The negotiation object

FieldTypeMeaning
iduuid
statusstringOPEN, BOOKED, DECLINED or EXPIRED
currencystring
arrival, departuredateThe stay asked for
adults, childreninteger
room_type_iduuid or nullThe room type asked for; null: the offers choose
offersarrayThe offers standing now (empty once it isn't OPEN). Each {id, kind, label, room_type_id, room_type, rate_plan_id, arrival, departure, nights, room_total, total, pay_now, gift?}. total is the whole stay with tax
saidarrayWhat was said, in order: {by: "guest" or "ana", said}
expires_in, expires_atinteger, datetimeSeconds left, and when the offers end
reservation_iduuid or nullThe booking, once booked
tokenstringThe negotiation's handle (you use id)

Get the terms

GET/properties/{property_id}/negotiation
Scope negotiation:readOperation negotiation.terms
200 OK
{ "open": true, "max_rounds": 3, "expiry_minutes": 30, "max_nights": 30, "room_type_ids": [], "kinds": ["base", "pay_now", "longer", "dates"] }

room_type_ids lists the room types the hotel bargains on; empty means every one. Counter-offers past max_rounds get the hotel's last word.

Ask for offers

POST/properties/{property_id}/negotiations
Scope negotiation:writeOperation negotiation.start
arrival daterequired
Today at the hotel or later.
departure daterequired
Up to 30 nights after arrival.
adults integer
1 to 20. Default 1.
children integer
0 to 20.
room_type_id uuid
The room type the guest wants. Leave out to let the offers choose.
budget number
What the guest would pay for the whole stay, with tax, if they said.
flexible_days integer
0 to 3: how far the guest's dates may move for a quieter date.
guest object
{first_name?, last_name?, email?, phone?}. A returning guest may get a little more.
Request
curl -X POST "https://app.chatbeds.app/partner/v1/properties/19306340-c7cf-465a-93d3-0b7873a7e85d/negotiations" \
  -H "Authorization: Bearer cbk_••••" -H "Content-Type: application/json" \
  -d '{"arrival": "2026-12-10", "departure": "2026-12-12", "adults": 2, "budget": 180,
       "guest": {"first_name": "Sara", "email": "sara@example.com"}}'
201 Created
{
  "negotiation": {
    "id": "c41f7e2a-9b3d-4e6a-8f15-2d7c9a0b3e58",
    "status": "OPEN",
    "currency": "USD",
    "arrival": "2026-12-10",
    "departure": "2026-12-12",
    "adults": 2,
    "children": 0,
    "room_type_id": null,
    "offers": [
      { "id": "o1", "kind": "base", "label": "Your dates", "room_type": "Deluxe", "nights": 2, "room_total": 190.0, "total": 190.0, "pay_now": false },
      { "id": "o2", "kind": "pay_now", "label": "Pay now", "room_type": "Deluxe", "nights": 2, "room_total": 180.0, "total": 180.0, "pay_now": true }
    ],
    "said": [{ "by": "ana", "said": "Here's what I can do..." }],
    "expires_in": 1800,
    "expires_at": "2026-11-05T12:30:00+00:00",
    "reservation_id": null
  }
}

Errors

StatusWhen
409The hotel isn't taking offers from partner apps, or the room type asked for has a fixed price
400Dates in the past, departure not after arrival, more than 30 nights, too many guests

Counter

POST/negotiations/{negotiation_id}/counter
Scope negotiation:writeOperation negotiation.counter

Say what the guest would pay for the whole stay (with tax). Ana accepts it, meets the guest part of the way, or shows the trade that comes closest, never under what the hotel's limits allow. The answer is the negotiation with its new offers.

amount numberrequired
The guest's price for the whole stay.
offer_id string
The offer it answers, when there are several.

409 once it is booked, declined or expired: ask again.

Book the agreed offer

POST/negotiations/{negotiation_id}/book
Scope negotiation:writeOperation negotiation.book

Books the offer for the guest at its price: a normal partner booking (source PARTNER:<partner>, your external_ref), on the tape chart, with the hotel told. The answer has the reservation and the negotiation, now BOOKED.

offer_id stringrequired
The offer the guest accepted.
guest objectrequired
{first_name, last_name, email?, phone?}.
external_ref string
Your reference for the booking.
paid_amount number
For a pay_now offer: the whole total, which your app took from the guest. Required for those.
payment_method string
How you took it: CARD (default), CASH or BANK_TRANSFER.
Request
r = requests.post(f"{BASE}/negotiations/{negotiation_id}/book", headers={**HEADERS, "Idempotency-Key": "OTA-778-book"},
                  json={"offer_id": "o2", "guest": {"first_name": "Sara", "last_name": "Khan", "email": "sara@example.com"},
                        "external_ref": "OTA-778", "paid_amount": 180, "payment_method": "CARD"})
reservation = r.json()["reservation"]        # 201 Created

Errors

StatusWhen
409The offers expired or changed, the negotiation isn't open, the room was taken meanwhile, or the guest can't be booked at this hotel
400A pay-now offer without its whole total in paid_amount, or the guest's names missing

Decline

POST/negotiations/{negotiation_id}/decline
Scope negotiation:writeOperation negotiation.decline

The guest said no: the negotiation is closed (DECLINED) and its offers end. Declining one already closed changes nothing.

Get and list

GET/negotiations/{negotiation_id}
Scope negotiation:readOperation negotiation.get
GET/properties/{property_id}/negotiations
Scope negotiation:readOperation negotiation.list

Your app sees only the negotiations it started. The list is newest first; filter with status (OPEN, BOOKED, DECLINED, EXPIRED) and limit (1 to 200, default 50).

무언가 만들고 계신가요?

이 페이지의 내용