新建 Booking.com 优惠活动

在某个 Booking.com 住宿上新建优惠活动。优惠一建成就会在 Booking.com 上生效,发送前请核对折扣、日期、房型和价格计划。必填字段与允许的取值取决于 type(见下方各字段);明显无效的请求百居易会在调用 Booking.com 之前直接返回 400。

  • 必须带 idempotency_key。Booking.com 每收到一次请求就新建一条优惠,所以失败或超时后请用同一个 key 重发:百居易会返回第一次请求建出的那条优惠(created: false),而不是再建一条。这一保护从第一次请求起保持 24 小时。在用 GET /channel_accounts/booking/promotions 核对之前,不要换新 key 重试。502 的错误信息里列出了优惠 id 时,其中可能就有本次请求建出的那条:请核对这些优惠,不要再重试。
  • 请使用 JSON 请求体。
  • Booking.com 每个住宿只有一条 mobile_rate 优惠,每个国家渠道(target_channel)只有一条 geo_rate 优惠,id 固定(MR、GR<target_channel>)。已存在(无论启用与否)时再新建会覆盖那一条,所以百居易会先读取住宿的优惠,已存在时返回 409 并给出现有 id:请改用 PATCH /channel_accounts/booking/promotions/{promotion_id} 修改那条优惠。如果你是在重试一个可能已经成功的新建,409 里的 id 就是它建出的优惠。
  • non_refundable: true 时,如果住宿还没有不可退款政策,Booking.com 会自动新建一个 3 天不可退款政策。
  • Booking.com 优惠无法删除;要去掉一条优惠,请用 POST /channel_accounts/booking/promotions/{promotion_id}/deactivate 停用。
  • 除下面的每分钟限制外,每个 Booking.com 住宿每天(服务器时区)最多 20 次新建请求;429 响应带有 Retry-After。
  • 你的账号未开放新建与编辑优惠时返回 501(与 POST /channel_accounts/booking/promotions/excluded_dates 分开开放)。
  • 每个 Booking.com 住宿每分钟最多 10 次优惠写入,与 POST /channel_accounts/booking/promotions/excluded_dates 共用,此外仍受账号级限流约束;429 响应带有 Retry-After。
  • Booking.com 拒绝的取值返回 400,error_msg 中带有 Booking.com 错误码(如 DISCOUNT_NOT_IN_RANGE、ROOMS_INVALID、TARGET_CHANNEL_NO_ACCESS)。
  • 502 表示 Booking.com 暂时不可用或结果无法确认,改动仍可能在之后几分钟内生效。

需要可写的访问令牌。

Body Params
integer
required

Booking.com 渠道账号的 id,来自 GET /channel_accounts。一个 Booking.com 渠道账号对应一个 Booking.com 住宿;优惠活动属于住宿,而不是某个房型。

string
required
^[A-Za-z0-9_-]{8,64}$

你为这条新优惠自定的 key,8-64 位字母、数字、- 或 _。Booking.com 每收到一次请求就新建一条优惠,所以请求失败或超时后,请用同一个 key 重发:百居易会返回第一次请求建出的优惠,而不会再建一条(created: false)。这一保护从第一次请求起保持 24 小时,之后同一个 key 会新建一条优惠。每条新优惠都用一个新 key。同一个 key 配不同的优惠字段返回 409。

string
enum
required

优惠类型。basic、last_minute、early_booker、geo_rate(国家/地区价)、mobile_rate、campaign_black_friday、campaign_early_year、campaign_getaway、campaign_late_escape(只能在 Booking.com 活动报名期内新建,且入住日期须在活动窗口内),或 new_property_deal(固定 8 折,满 3 单或 90 天后自动结束;只适用于开业不满 12 个月且没有订单的住宿,不需要其他字段)。类型建成后不能修改。

string
length ≤ 255

优惠名称,最多 255 个字符。只在你的 Booking.com Extranet 中可见,客人看不到。除 geo_rate、mobile_rate 与 new_property_deal 外必填(Booking.com 不返回 geo_rate 与 mobile_rate 优惠的名称)。

integer
1 to 99

折扣百分比,整数。各类型的取值范围:basic、last_minute、early_booker 为 1-99(target_channel 为 subscribers 时 10-99);geo_rate 5-30;mobile_rate 10-80;campaign_getaway、campaign_late_escape、campaign_early_year 15-99;campaign_black_friday 30-99。new_property_deal 不使用(固定 20%)。除 new_property_deal 外必填。

string

优惠面向的客群。basic、last_minute、early_booker:public(默认)或 subscribers(Genius / 订阅会员)。mobile_rate:app(默认)或 all。geo_rate:Booking.com 的国家/地区渠道,必填;可从已有的 georate 优惠(GET /channel_accounts/booking/promotions)或 Booking.com Extranet 中照抄,并非每个住宿都能用所有国家/地区。`campaign*` 不使用。

integer
0 to 30

最少入住晚数。basic、last_minute、early_booker:0-30,0 表示沿用价格计划的最少入住,1 表示不限。geo_rate、mobile_rate:1-30。campaign_* 不使用。

boolean

为 true 时优惠只按不可退款条件提供。⚠️ 如果住宿还没有不可退款政策,Booking.com 会自动新建一个 3 天不可退款政策并套用。campaign_* 不使用。

stay_date
object

优惠适用的入住日期。除 geo_rate、mobile_rate 与 new_property_deal 外必填(Booking.com 不返回 geo_rate 与 mobile_rate 优惠的入住日期)。

additional_dates
array of dates

在 stay_date.start-stay_date.end 区间之外、优惠同样适用的单个入住日期,YYYY-MM-DD,最多 366 个。

additional_dates
book_date
object

客人可以预订该优惠的日期范围,YYYY-MM-DD。end 不能晚于 stay_date.end。last_minute、early_booker 与 campaign_* 不使用。不传表示不限。

book_time
object

每天可以预订该优惠的时段,0-24 时,按住宿所在时区。campaign_* 不使用。不传表示不限。

last_minute
object

距入住多近时优惠开始可订。last_minute 必填(unit 为 hour 或 day,value 1-1000)。geo_rate 与 mobile_rate 在 last_minute(unit 必须为 day,value 1-365)和 early_booker 中最多传一个。

integer
1 to 500

客人需要提前多少天预订。early_booker 必填(1-500)。geo_rate 与 mobile_rate 在 early_booker(1-365)和 last_minute 中最多传一个。提前预订窗口不能早于优惠新建当天。

rooms
array of strings

优惠适用的 Booking.com 房型 id:即 GET /listings 中 Booking.com listing_id(<房型 id>-<价格计划 id>)- 前面的部分,如 1320924403。basic、last_minute、early_booker 与 campaign_* 必填;geo_rate 与 mobile_rate 不使用。

rooms
parent_rates
array of strings

优惠适用的 Booking.com 价格计划 id:即 GET /listings 中 Booking.com listing_id - 后面的部分。必须是该住宿已启用的价格计划。优惠只作用于已存在的房型 × 价格计划组合,不会新建组合。除 new_property_deal 外各类型都必填。

parent_rates
Response

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json