{"openapi":"3.1.0","info":{"title":"Hotel API","version":"v1","description":"One REST API finds, books and cancels hotel stays worldwide, paid from your FlightOTA deposit. A stay takes five calls: find the destination, search hotels, list one hotel's rooms, re-check the chosen rate, book. A booking is either paid now (confirmed with the hotel at once) or held where the rate allows it, then paid before its deadline."},"servers":[{"url":"https://api.flightota.com/api/v1","description":"Production"},{"url":"https://sandbox.flightota.com/api/v1","description":"Sandbox"}],"security":[{"X-Api-Key":[],"X-Api-Secret":[]}],"paths":{"/ping":{"get":{"operationId":"hotels-ping","summary":"Ping","description":"Call GET /ping first. It returns your agency code and the IP we saw.","tags":["Getting started"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"ok":true,"partner":"PTR-000020","key_id":"ak_test_your_key_id","environment":"test","from_ip":"203.0.113.10","server_time":"2026-09-22T13:25:02+00:00"}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/hotels/destinations":{"get":{"operationId":"hotels-destinations","summary":"Find a destination","description":"Use the id in the search; ids are valid for about an hour, so look them up as the user types.","tags":["Destinations and search"],"parameters":[{"name":"term","in":"query","required":true,"description":"At least 2 characters.","schema":{"type":"string"},"example":"Dubai"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"term":"Dubai","destinations":[{"id":"loc_01m34q6gd14nc2ea9q39tbq8z0","name":"Dubai","full_name":"Dubai, Dubai, United Arab Emirates","type":"city","country":"AE"},{"id":"loc_01m34q6gd14nc2ea9q39tbq8z1","name":"Dubai (and vicinity)","full_name":"Dubai (and vicinity), Dubai, United Arab Emirates","type":"multiCity","country":"AE"},{"id":"loc_01m34q6gd14nc2ea9q39tbq8z2","name":"Dubai (DXB-Dubai Intl.)","full_name":"Dubai, United Arab Emirates (DXB-Dubai Intl.)","type":"airport","country":"AE"}]}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"422":{"description":"validation_failed: See errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_failed":{"value":{"error":{"code":"validation_failed","message":"See errors."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/hotels/search":{"post":{"operationId":"hotels-search","summary":"Search hotels","description":"Asks every hotel source at once, 10–40 seconds. Results stay bookable for 15 minutes. total is the cheapest stay at this hotel for the whole search (all rooms, all nights), in your currency, and is what your deposit pays.","tags":["Destinations and search"],"parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"search_id":"srh_01m34q7w1fmxw6tgp917fwnqrt","expires_at":"2026-09-22T14:25:13Z","currency":"BDT","offers":[{"offer_id":"ofr_01m34q7w1fmxw6tgp917fwnqrv","hotel_key":"htl_3e344d6c950e8809","hotel_country":"AE","total":{"amount":900792,"currency":"BDT"},"price":{"base":{"amount":900792,"currency":"BDT"},"taxes":{"amount":0,"currency":"BDT"},"fees":{"amount":0,"currency":"BDT"},"per_night":{"amount":450396,"currency":"BDT"}},"hotel":{"name":"Royal Tulip Hotel","star_rating":3,"address":"Opposite Delhi Resturant, Al Murar area Deira 116957 Dubai United Arab Emirates","city":"Dubai","country_code":"AE","coordinates":{"lat":25.276138,"long":55.31023},"thumbnail":"https://…/hotelImage.aspx?id=88054978","images":["https://…","…"],"description":"With a stay at Royal Tulip Hotel in Dubai (Deira), you'll be convenient to Naif Souq and Gold Souk…","check_in_time":null,"check_out_time":null,"property_type":"Hotel","amenities":["…"],"review":{"…":"…"}},"refundable":true,"free_cancellation":true,"free_breakfast":false,"pay_at_hotel":false,"more_rates":true,"sold_out":false}]}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"422":{"description":"validation_failed: See errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_failed":{"value":{"error":{"code":"validation_failed","message":"See errors."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Nothing changed; retry.\npricing_unavailable: Nothing changed; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Nothing changed; retry."}}},"pricing_unavailable":{"value":{"error":{"code":"pricing_unavailable","message":"Nothing changed; retry."}}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["check_in","check_out","rooms[]","rooms[].adults"],"properties":{"location_id":{"type":"string","description":"One of location_id and destination. A loc_… id from destinations."},"destination":{"type":"string","description":"One of location_id and destination. A place name, when you have no id."},"check_in":{"type":"object","description":"Check-out after check-in."},"check_out":{"type":"object","description":"Check-out after check-in."},"rooms[]":{"type":"object","description":"One entry per room."},"rooms[].adults":{"type":"object","description":"Adults in the room."},"rooms[].children":{"type":"object","description":"Children in the room."},"rooms[].child_ages[]":{"type":"object","description":"With children. Age of each child on check-in."},"nationality":{"type":"string","description":"Recommended. Lead guest's nationality, ISO code. Prices and PAN rules depend on it."},"residence":{"type":"string","description":"Defaults to nationality."},"filters.max_offers":{"type":"object","description":"Default 50."}}},"example":{"location_id":"loc_01m34q6gd14nc2ea9q39tbq8z0","check_in":"2026-10-27","check_out":"2026-10-29","rooms":[{"adults":2,"children":1,"child_ages":[7]}],"nationality":"BD","filters":{"max_offers":20}}}}}}},"/hotels/search/{search_id}":{"get":{"operationId":"hotels-search-get","summary":"Read a search again","description":"Returns the same results again while valid; an expired one answers 410 offer_expired.","tags":["Destinations and search"],"parameters":[{"name":"search_id","in":"path","required":true,"description":"The search id.","schema":{"type":"string"},"example":"srh_01m34q7w1fmxw6tgp917fwnqrt"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"search_id":"srh_01m34q7w1fmxw6tgp917fwnqrt","expires_at":"2026-09-22T14:25:13Z","currency":"BDT","offers":[{"offer_id":"ofr_01m34q7w1fmxw6tgp917fwnqrv","hotel_key":"htl_3e344d6c950e8809","hotel_country":"AE","total":{"amount":900792,"currency":"BDT"},"price":{"base":{"amount":900792,"currency":"BDT"},"taxes":{"amount":0,"currency":"BDT"},"fees":{"amount":0,"currency":"BDT"},"per_night":{"amount":450396,"currency":"BDT"}},"hotel":{"name":"Royal Tulip Hotel","star_rating":3,"address":"Opposite Delhi Resturant, Al Murar area Deira 116957 Dubai United Arab Emirates","city":"Dubai","country_code":"AE","coordinates":{"lat":25.276138,"long":55.31023},"thumbnail":"https://…/hotelImage.aspx?id=88054978","images":["https://…","…"],"description":"With a stay at Royal Tulip Hotel in Dubai (Deira), you'll be convenient to Naif Souq and Gold Souk…","check_in_time":null,"check_out_time":null,"property_type":"Hotel","amenities":["…"],"review":{"…":"…"}},"refundable":true,"free_cancellation":true,"free_breakfast":false,"pay_at_hotel":false,"more_rates":true,"sold_out":false}]}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"410":{"description":"offer_expired: Search again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"offer_expired":{"value":{"error":{"code":"offer_expired","message":"Search again."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/hotels/offers/{offer_id}/rooms":{"get":{"operationId":"hotels-rooms","summary":"List rooms and rates","description":"Each rate has its own offer_id: that is the rate_id you book. Sandbox: 171 rates for Royal Tulip in 10 s. notes are the hotel's own conditions (tourism fees paid at the hotel, ID at check-in). Show them before booking.","tags":["Rooms and rate check"],"parameters":[{"name":"offer_id","in":"path","required":true,"description":"The hotel's offer_id from search.","schema":{"type":"string"},"example":"ofr_01m34q7w1fmxw6tgp917fwnqrv"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"rooms_id":"srh_01m34q8qy2jd0tvbw50j887d1k","expires_at":"2026-09-22T14:25:42Z","currency":"BDT","rates":[{"offer_id":"ofr_01m34qg0zz8d40ew1ab159b48f","hotel_country":"AE","total":{"amount":1900946,"currency":"BDT"},"price":{"base":{"amount":1900946,"currency":"BDT"},"per_night":{"amount":950473,"currency":"BDT"},"taxes":{"amount":0,"currency":"BDT"},"fees":{"amount":0,"currency":"BDT"}},"room":{"name":"Standard Room","image":"https://…/3e7bcff9_b.jpg","beds":["1 Double or 1 Twin"],"max_adults":null},"board_basis":"Room Only","includes":[],"notes":["Upon your arrival please provide valid government-issued ID to the hotel front desk…"],"occupancy":{"adults":2,"children":1},"refundable":true,"free_cancellation":false,"pay_at_hotel":false,"deposit_required":false,"cancellation":[{"from":"2026-09-22T00:00:00Z","until":"2026-10-24T19:59:00Z","amount":{"amount":0,"currency":"BDT"},"percent":null},{"from":"2026-10-24T20:00:00Z","until":"2026-10-29T00:00:00Z","amount":{"amount":1900946,"currency":"BDT"},"percent":null}],"booking_modes":["hold","confirm"],"hold_deadline":null}]}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"409":{"description":"offer_unavailable: Hotel or room not bookable now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"offer_unavailable":{"value":{"error":{"code":"offer_unavailable","message":"Hotel or room not bookable now."}}}}}}},"410":{"description":"offer_expired: Search again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"offer_expired":{"value":{"error":{"code":"offer_expired","message":"Search again."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/hotels/rates/{rate_id}/price":{"get":{"operationId":"hotels-rate-price","summary":"Re-check a rate","description":"Asks the hotel again. Call it before collecting guest details. status: price_changed means rate.total is the new price and quoted the old one. Book with accept_total set to the new total to accept it. hold.available: true means you may book with hold: true and pay by hold.deadline.","tags":["Rooms and rate check"],"parameters":[{"name":"rate_id","in":"path","required":true,"description":"The rate's offer_id from rooms.","schema":{"type":"string"},"example":"ofr_01m34qg0zz8d40ew1ab159b48f"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":"confirmed","quoted":{"amount":1900946,"currency":"BDT"},"rate":{"offer_id":"ofr_01m34qg0zz8d40ew1ab159b48f","total":{"amount":1900946,"currency":"BDT"},"…":"the full rate"},"hold":{"available":true,"deadline":"2026-10-23T14:29:00Z"},"requirements":{"passport_required":false,"pan_required":false,"pan_for_all_guests":false}}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"409":{"description":"unavailable: Means the room is gone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unavailable":{"value":{"error":{"code":"unavailable","message":"Means the room is gone."}}}}}}},"410":{"description":"offer_expired: Means search again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"offer_expired":{"value":{"error":{"code":"offer_expired","message":"Means search again."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Nothing changed; retry.\npricing_unavailable: Nothing changed; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Nothing changed; retry."}}},"pricing_unavailable":{"value":{"error":{"code":"pricing_unavailable","message":"Nothing changed; retry."}}}}}}}}}},"/hotels/bookings":{"post":{"operationId":"hotels-book","summary":"Book a stay","description":"Books one rate. The rate is priced again first; your request never names a price. Without hold, the stay is paid from your deposit and confirmed with the hotel in the same call (up to about a minute). With \"hold\": true (only where the rate check said hold.available), nothing is charged until you pay. A rate can be booked only once: to book a second room of the same kind, fetch the rooms again for fresh rate ids.","tags":["Book a stay"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique per booking attempt.","schema":{"type":"string"},"example":"docs-hotel-001"}],"responses":{"201":{"description":"Successful response","content":{"application/json":{"example":{"status":"held","booking":{"booking_ref":"TFH-WD5BD2P4","state":"held","created_at":"2026-09-22T14:11:36Z","confirmed_at":null,"hold_expires_at":"2026-10-23T14:29:00Z","client_reference":"DOCS-HOTEL-001","hotel_confirmation":null,"needs_attention":false,"total":{"amount":1900946,"currency":"BDT"},"price":{"room_rate":{"amount":1900946,"currency":"BDT"},"taxes":{"amount":0,"currency":"BDT"}},"hotel":{"name":"Royal Tulip Hotel","star_rating":3,"address":"Opposite Delhi Resturant, Al Murar area Deira 116957 Dubai United Arab Emirates","city":"Dubai","country_code":"AE","phone":null,"check_in_time":null,"check_out_time":null},"stay":{"check_in":"2026-10-27","check_out":"2026-10-29","nights":2,"rooms":[{"adults":2,"children":1,"child_ages":[7]}],"nationality":"BD"},"room":{"name":"Standard Room","board_basis":"Room Only","refundable":true,"cancellation":["Free cancellation until 24 Oct 2026","From 24 Oct 2026 to 29 Oct 2026: 19,009.46 BDT charge"]},"guests":[{"position":1,"type":"adult","title":"MR","first_name":"ARIF","last_name":"RAHMAN"},{"position":2,"type":"adult","title":"MRS","first_name":"NUSRAT","last_name":"RAHMAN"},{"position":3,"type":"child","title":"MSTR","first_name":"AYAN","last_name":"RAHMAN"}],"special_requests":"Late arrival, around 23:00","cancellation":null}}}}},"400":{"description":"idempotency_key_required: Add the header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"value":{"error":{"code":"idempotency_key_required","message":"Add the header."}}}}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"402":{"description":"insufficient_funds: Top up your deposit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_funds":{"value":{"error":{"code":"insufficient_funds","message":"Top up your deposit."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"409":{"description":"price_changed: total is the new price; send accept_total with it to accept.\nroom_unavailable: Sold out; choose another rate.\nhold_unavailable: This rate cannot be held; book without hold.\nhold_refused: The hotel would not hold it now; book without hold or retry.\nrate_already_booked: This rate id was already booked (as booking_ref); fetch rooms again.\nduplicate_request: The key was used with a different body.\nrequest_in_progress: Still running.\noffer_unavailable: The room cannot be booked now; choose another.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"price_changed":{"value":{"error":{"code":"price_changed","message":"total is the new price; send accept_total with it to accept."}}},"room_unavailable":{"value":{"error":{"code":"room_unavailable","message":"Sold out; choose another rate."}}},"hold_unavailable":{"value":{"error":{"code":"hold_unavailable","message":"This rate cannot be held; book without hold."}}},"hold_refused":{"value":{"error":{"code":"hold_refused","message":"The hotel would not hold it now; book without hold or retry."}}},"rate_already_booked":{"value":{"error":{"code":"rate_already_booked","message":"This rate id was already booked (as booking_ref); fetch rooms again."}}},"duplicate_request":{"value":{"error":{"code":"duplicate_request","message":"The key was used with a different body."}}},"request_in_progress":{"value":{"error":{"code":"request_in_progress","message":"Still running."}}},"offer_unavailable":{"value":{"error":{"code":"offer_unavailable","message":"The room cannot be booked now; choose another."}}}}}}},"410":{"description":"offer_expired: Search again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"offer_expired":{"value":{"error":{"code":"offer_expired","message":"Search again."}}}}}}},"422":{"description":"validation_failed: See errors; for example rooms.0.guests.0.pan_number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_failed":{"value":{"error":{"code":"validation_failed","message":"See errors; for example rooms.0.guests.0.pan_number."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: Nothing changed; retry.\npricing_unavailable: Nothing changed; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"Nothing changed; retry."}}},"pricing_unavailable":{"value":{"error":{"code":"pricing_unavailable","message":"Nothing changed; retry."}}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hotel_offer_id","rate_id","rooms[]","rooms[].guests[]","guests[].type","guests[].title","guests[].first_name","guests[].last_name","contact.email","contact.dial_code","contact.mobile"],"properties":{"hotel_offer_id":{"type":"string","description":"The hotel's offer_id from search."},"rate_id":{"type":"string","description":"The rate's offer_id from rooms."},"hold":{"type":"boolean","description":"true to hold and pay later, where allowed."},"rooms[]":{"type":"object","description":"One entry per searched room, in the same order."},"rooms[].guests[]":{"type":"object","description":"Every guest of that room: exactly the adults and children it was searched for."},"guests[].type":{"type":"object","description":"adult (12 or over on check-in) or child; as many of each as the room was searched for."},"guests[].title":{"type":"string","description":"MR, MRS, MS, MISS, MSTR."},"guests[].first_name":{"type":"string","description":"Letters, spaces, hyphens, apostrophes."},"guests[].last_name":{"type":"string","description":"Letters, spaces, hyphens, apostrophes."},"guests[].nationality":{"type":"string","description":"ISO code; defaults to the search nationality."},"guests[].date_of_birth":{"type":"object","description":"Must fit adult or child on check-in. A child's must fit the age it was searched at: the room's first child is its first child_ages, and so on."},"guests[].passport_number":{"type":"string","description":"Lead guest, when requirements.passport_required."},"guests[].passport_expiry":{"type":"object","description":"Must be after check-out."},"guests[].pan_number":{"type":"string","description":"Indian lead guest when pan_required; every Indian guest when pan_for_all_guests. Format ABCDE1234F. Never needed for other nationalities."},"contact.email":{"type":"string","description":"For the hotel and the voucher."},"contact.dial_code":{"type":"string","description":"For the hotel and the voucher."},"contact.mobile":{"type":"string","description":"For the hotel and the voucher. mobile digits only."},"contact.name":{"type":"string","description":"Defaults to the lead guest."},"special_requests":{"type":"string","description":"Up to 500 characters; passed to the hotel, not guaranteed."},"arrival_time":{"type":"string","description":"e.g. 23:00."},"accept_total":{"type":"integer","description":"Integer minor units (currency units on a key with Amounts switched): accept a changed price up to this total."},"client_reference":{"type":"string","description":"Your own reference, up to 64 characters."}}},"example":{"hotel_offer_id":"ofr_01m34q7w1fmxw6tgp917fwnqrv","rate_id":"ofr_01m34q8qy88vwza13395cqh6bn","hold":true,"rooms":[{"guests":[{"type":"adult","title":"MR","first_name":"Arif","last_name":"Rahman","nationality":"BD","passport_number":"A01234567"},{"type":"adult","title":"MRS","first_name":"Nusrat","last_name":"Rahman","nationality":"BD"},{"type":"child","title":"MSTR","first_name":"Ayan","last_name":"Rahman","nationality":"BD","date_of_birth":"2019-09-22"}]}],"contact":{"email":"ops@agency.example","dial_code":"880","mobile":"1711000000"},"special_requests":"Late arrival, around 23:00","client_reference":"DOCS-HOTEL-001"}}}}},"get":{"operationId":"hotels-bookings-list","summary":"List stays","description":"Newest first, 25 a page.","tags":["Read, pay, cancel"],"parameters":[{"name":"state","in":"query","required":false,"description":"held, pending, confirmed, cancelled, expired, rejected.","schema":{"type":"string"}},{"name":"client_reference","in":"query","required":false,"description":"Your own reference.","schema":{"type":"string"}},{"name":"created_from","in":"query","required":false,"description":"Created on or after this date.","schema":{"type":"object","description":"YYYY-MM-DD"}},{"name":"created_to","in":"query","required":false,"description":"Created on or before this date.","schema":{"type":"object","description":"YYYY-MM-DD"}},{"name":"page","in":"query","required":false,"description":"The page.","schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"description":"per_page up to 100.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"bookings":[{"booking_ref":"TFH-WD5BD2P4","state":"cancelled","…":"…"}],"page":1,"per_page":25,"total":1,"last_page":1}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"422":{"description":"validation_failed: See errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"validation_failed":{"value":{"error":{"code":"validation_failed","message":"See errors."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/hotels/bookings/{booking_ref}":{"get":{"operationId":"hotels-booking-get","summary":"Read one stay","description":"Returns the booking in the shape shown under Book. Another agency's reference answers 404 booking_not_found.","tags":["Read, pay, cancel"],"parameters":[{"name":"booking_ref","in":"path","required":true,"description":"The booking reference, TFH-XXXXXXXX.","schema":{"type":"string"},"example":"TFH-WD5BD2P4"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"booking":{"booking_ref":"TFH-WD5BD2P4","state":"held","…":"the shape shown under Book"}}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"404":{"description":"booking_not_found: Unknown, or not your agency's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"booking_not_found":{"value":{"error":{"code":"booking_not_found","message":"Unknown, or not your agency's."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/hotels/bookings/{booking_ref}/pay":{"post":{"operationId":"hotels-pay","summary":"Pay a held stay","description":"No body, before hold_expires_at. The deposit pays and the hotel confirms. 202 requested means paid; our team is confirming with the hotel. (TestBooking is the hotel test system's confirmation; live stays carry the hotel's real number.)","tags":["Read, pay, cancel"],"parameters":[{"name":"booking_ref","in":"path","required":true,"description":"The booking reference, TFH-XXXXXXXX.","schema":{"type":"string"},"example":"TFH-WD5BD2P4"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":"confirmed","booking":{"booking_ref":"TFH-WD5BD2P4","state":"confirmed","confirmed_at":"2026-09-22T14:12:57Z","hotel_confirmation":"TestBooking","…":"…"}}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"402":{"description":"insufficient_funds: Top up; nothing charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_funds":{"value":{"error":{"code":"insufficient_funds","message":"Top up; nothing charged."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"409":{"description":"hold_expired: Too late; search again.\ninvalid_state: Not a held stay.\nduplicate_request: Key reused.\nrequest_in_progress: Still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"hold_expired":{"value":{"error":{"code":"hold_expired","message":"Too late; search again."}}},"invalid_state":{"value":{"error":{"code":"invalid_state","message":"Not a held stay."}}},"duplicate_request":{"value":{"error":{"code":"duplicate_request","message":"Key reused."}}},"request_in_progress":{"value":{"error":{"code":"request_in_progress","message":"Still running."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/hotels/bookings/{booking_ref}/cancellation":{"get":{"operationId":"hotels-cancellation","summary":"What cancelling would cost","description":"Changes nothing. charge is what the hotel keeps if you cancel now, service_charge our cancellation fee, and refund what returns to your deposit. cancellable: false comes with a reason.","tags":["Read, pay, cancel"],"parameters":[{"name":"booking_ref","in":"path","required":true,"description":"The booking reference, TFH-XXXXXXXX.","schema":{"type":"string"},"example":"TFH-WD5BD2P4"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"cancellable":true,"reason":null,"refundable":true,"rules":["Free cancellation until 24 Oct 2026","From 24 Oct 2026 to 29 Oct 2026: 19,009.46 BDT charge"],"free_until":"2026-10-24T19:59:00+00:00","total":{"amount":1900946,"currency":"BDT"},"charge":{"amount":0,"currency":"BDT"},"service_charge":{"amount":0,"currency":"BDT"},"refund":{"amount":1900946,"currency":"BDT"}}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"404":{"description":"booking_not_found: Unknown, or not your agency's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"booking_not_found":{"value":{"error":{"code":"booking_not_found","message":"Unknown, or not your agency's."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}}}}},"/hotels/bookings/{booking_ref}/cancel":{"post":{"operationId":"hotels-cancel","summary":"Cancel","description":"A held stay is released; nothing was charged, refund is 0. A confirmed stay is cancelled with the hotel under its rules, and refund is paid back to your deposit at once.","tags":["Read, pay, cancel"],"parameters":[{"name":"booking_ref","in":"path","required":true,"description":"The booking reference, TFH-XXXXXXXX.","schema":{"type":"string"},"example":"TFH-WD5BD2P4"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"example":{"status":"cancelled","refund":{"amount":1900946,"currency":"BDT"},"booking":{"booking_ref":"TFH-WD5BD2P4","state":"cancelled","cancellation":{"cancelled_at":"2026-09-22T14:13:17+00:00","charge":{"amount":0,"currency":"BDT"},"refund":{"amount":1900946,"currency":"BDT"}},"…":"…"}}}}},"401":{"description":"unauthenticated: Headers missing, or key or secret wrong.\ncredential_inactive: Key revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unauthenticated":{"value":{"error":{"code":"unauthenticated","message":"Headers missing, or key or secret wrong."}}},"credential_inactive":{"value":{"error":{"code":"credential_inactive","message":"Key revoked or expired."}}}}}}},"403":{"description":"ip_whitelist_required: Whitelist your server's IP on the key.\nip_not_whitelisted: Whitelist your server's IP on the key.\nproduct_not_allowed: The key is not enabled for hotels.\npartner_inactive: Account or API plan not active; live keys work after certification.\nsubscription_*: Account or API plan not active; live keys work after certification.\nenvironment_not_activated: Account or API plan not active; live keys work after certification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ip_whitelist_required":{"value":{"error":{"code":"ip_whitelist_required","message":"Whitelist your server's IP on the key."}}},"ip_not_whitelisted":{"value":{"error":{"code":"ip_not_whitelisted","message":"Whitelist your server's IP on the key."}}},"product_not_allowed":{"value":{"error":{"code":"product_not_allowed","message":"The key is not enabled for hotels."}}},"partner_inactive":{"value":{"error":{"code":"partner_inactive","message":"Account or API plan not active; live keys work after certification."}}},"subscription_*":{"value":{"error":{"code":"subscription_*","message":"Account or API plan not active; live keys work after certification."}}},"environment_not_activated":{"value":{"error":{"code":"environment_not_activated","message":"Account or API plan not active; live keys work after certification."}}}}}}},"409":{"description":"not_cancellable: Carries the reason (for example, a non-refundable rate the hotel will not cancel).\ninvalid_state: Not allowed in the current state; see message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_cancellable":{"value":{"error":{"code":"not_cancellable","message":"Carries the reason (for example, a non-refundable rate the hotel will not cancel)."}}},"invalid_state":{"value":{"error":{"code":"invalid_state","message":"Not allowed in the current state; see message."}}}}}}},"429":{"description":"rate_limited: Wait a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"value":{"error":{"code":"rate_limited","message":"Wait a minute."}}}}}}},"503":{"description":"supplier_unavailable: The hotel did not confirm the cancellation; the stay is unchanged, so retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"supplier_unavailable":{"value":{"error":{"code":"supplier_unavailable","message":"The hotel did not confirm the cancellation; the stay is unchanged, so retry."}}}}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"reason":{"type":"string","description":"Body optional."}}},"example":{"reason":"Guest cancelled the trip"}}}}}}},"components":{"securitySchemes":{"X-Api-Key":{"type":"apiKey","in":"header","name":"X-Api-Key"},"X-Api-Secret":{"type":"apiKey","in":"header","name":"X-Api-Secret"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}