构建取消政策
了解 Rapid Lodging API 如何构建和公开取消政策
概述
快速购物 API 会在 Availability 响应中返回每个价格的取消政策详情。每种价格的具体取消政策均由以下关键对象构成：
- tri-state 标志
current_refundability准确地表示了提出请求时利率的可退款性。 cancel_penalties对象定义了具有开始/结束日期、处罚类型和值的政策窗口。nonrefundable_date_ranges定义了预订中将保留 non-refundable 的入住日期（优先于cancel_penalties）。
注意：cancel_penalties.start 和 cancel_penalties.end中返回的 ISO-8601 偏移量是显示和计算所依据的权威值。这通常与当地房产时间一致，但可能反映 supplier-configured 时区数据，不应根据房产地址/地理位置重新计算。
本页上的所有示例都明确显示了偏移量（例如，GMT+7:00），以强调您应该保留并按给定方式显示它。
准则
可退款性
使用 current_refundability作为 refundability-driven 逻辑和用户体验的主要控件；它是策略配置最准确的表示，尤其适用于 partial-penalty 场景。
| 值 | 含义 |
|---|---|
refundable | 可全额退款 |
non_refundable | 不予退款 |
partially_refundable | 罚款金额大于 0 但小于预订总额，和/或住宿期间存在 non-refundable 日期范围 |
refundable布尔值可以显示保单的可退款性，但其功能有限，无法完全描述部分或复杂的罚款是如何运作的，也无法说明是否可能适用其他费用。预订时不可全额退款的任何价格将显示refundable=false。
Non-refundable 日期范围
使用 nonrefundable_date_ranges 对象设置在预订时不可退款的住宿日期是可选的。请注意，nonrefundable_date_range包含每晚房价以及任何税费。
如果价格在 nonrefundable_date_ranges对象中定义了 non-refundable 日期，则这些晚数将与 cancel_penalties对象中规定的任何其他取消罚款一起收取。
住宿服务费
在提及取消预订时应支付的费用时，最佳做法是使用“物业费”而不是“取消费”一词，以便更准确地反映谁收取费用以及为什么需要收取该费用。
预订时
取消政策详情将根据预订是在取消罚款期限内还是期限外而有所不同。请参见以下示例中的 refundable属性。
在取消罚款期限内进行的预订：
{
"itinerary_id": "9999999999999",
...
"rooms": [
{
"links": {
...
},
"id": "1111",
...
"status": "booked",
"checkin": "2026-08-03",
"checkout": "2026-08-07",
...
"rate": {
"id": "2222",
...
"refundable": false,
"cancel_refund": {
"amount": "0.00",
"currency": "USD"
},
"cancel_penalties": [
{
"currency": "USD",
"percent": "100%",
"start": "2026-07-16T06:56:59.311-07:00",
"end": "2026-08-03T23:59:00.000-07:00"
}
],
...
"pricing": {
...
}
}
}
]
}在取消罚款期限之外进行的预订：
{
"itinerary_id": "9999999999999",
...
"rooms": [
{
"links": {
...
},
"id": "1111",
...
"status": "booked",
"checkin": "2026-09-27",
"checkout": "2026-10-02",
...
"rate": {
"id": "2222",
...
"refundable": true,
"cancel_refund": {
"amount": "-1131.85",
"currency": "EUR"
},
"cancel_penalties": [
{
"currency": "EUR",
"percent": "100%",
"start": "2026-07-18T01:21:30.000-07:00",
"end": "2026-09-27T23:59:00.000-07:00"
}
],
...
"pricing": {
...
}
}
}
]
}政策组成部分
您必须向旅客提供的取消政策源自四个主要的时间段，以及per-stay 退款规则。所有四个时间段都应该在你的逻辑中加以考虑，并在适用的情况下，在你的用户界面文本中加以考虑。
取消政策例外情况
定义依据： nonrefundable_date_ranges
这些是与预订时间完全不同的入住日期 non-refundable。如果预订的晚数落在这些范围内，无论旅客何时取消预订，该晚的房费都将全额收取。
日期范围包含所有日期；当晚 non-refundable 时，还将收取结束日期的每晚房价以及任何税费。
如果只有部分住宿与 non-refundable 范围重叠，则超出该范围的晚数仍可退款，但须遵守 cancel_penalties中的其他罚款窗口。
Traveler-facing 消息： 这些日期是 non-refundable 从预订开始计算的；如果您更改或取消预订，您将不会获得退款或可用于未来住宿的抵用金，并且还需要支付任何税费。
免费取消
这是从预订创建到 cancel_penalties对象中最早的政策等级窗口开始（带有罚款）之间的时间段，不包括 nonrefundable_date_ranges中的任何夜晚。找出所有窗口中最早的cancel_penalties.start，并将该时间戳用作免费取消窗口的结束时间。
注意： 取消政策最多可分为 3 个级别。
Traveler-facing 信息： 在[最早罚款期限的开始日期时间]之前取消您的预订，您将获得全额退款。在 non-refundable 日期范围内的任何已预订住宿日期均不予退款。
罚款取消
定义如下：cancel_penalties 中的每个元素（如果存在）。
支持的处罚类型
在每个处罚期限内，nonrefundable_date_ranges 中的夜晚仍为 non-refundable，并且任何其他处罚均按照适用的 cancel_penalties窗口中的配置执行。请注意，可以在同一时间段内组合金额 + 晚数或金额 + 百分比，但不能在单个层级窗口中晚数和百分比。
固定金额手续费
- 以指定货币支付的固定费用（e.g. 200 USD）
Traveler-facing 消息： 如果您在[保单窗口开始日期时间]之后取消，您将被收取[金额] [货币]。
每晚手续费
- 指定晚数的费用加上税费（如果预订多晚，则从第一晚开始收取费用）。
Traveler-facing 消息： 如果您在[保单生效日期时间]之后取消预订，您将被收取[晚数]晚的房费以及税费。
百分比手续费
- 住宿总费用和收费的百分比（e.g. 90%）。
Traveler-facing 消息： 如果您在[保单生效日期时间]之后取消预订，您将被 收取总住宿费用的[百分比]。
Post-check-in 取消和 no-show
这是上次设定的处罚窗口期之后的时期（cancel_penalties[end]）。换句话说，就是 check-in 时间之前的层级窗口。
Traveler-facing 消息： 如果您对本次预订执行 no-show 操作，或者在 check-in 时间之后取消或更改本次预订，您将被收取 [金额/货币/晚数/百分比，如上次配置的罚款窗口中所定义]。
per-stay 金额的退款
Per-stay 金额，已返回stay对象，遵循一条规则：
- 如果入住期间的任何一天是 non-refundable, per-stay，则金额为 non-refundable
- Per-stay 金额仅在以下情况下退还：整个住宿全额退款
**笔记：**对于 VRBO 房源，服务费收取和退款方面还有一些其他细微差别——请向您的集成顾问咨询更多信息。
加州房产政策展示更新
为了遵守加利福尼亚州的政策变更，取消期限必须在预订创建时间戳后 24 小时开始，除非预订是在 check-in 之后 72 小时内进行的。Expedia 系统会自动调整位于加利福尼亚州的任何房产的取消窗口。
预期行为示例：
- 对于位于加利福尼亚州且房价全额可退且不收取取消罚金的房产，取消政策将不会发生任何变化。
- 对于位于加利福尼亚州且预订时已收取取消罚金的 non-refundable 房型，取消政策将修改为在预订创建日期后 24 小时开始生效。
- 如果房产位于加利福尼亚州以外，即使预订是在加利福尼亚州进行的，取消政策也不会改变。
Pre-booking 取消政策
更新后的取消罚款窗口将在旅客购物时自动显示在 API 调用中。你可能会注意到，refundable对于 non-refundable 预订，该标志仍然为 false，因此您需要根据取消期限遵守此规定。对于酒店，该期限为预订时间戳起 24 小时。对于 Vrbo 房源，有效期至预订后当天结束。
Post-booking 取消政策
预订成功后，调整后的加州政策仍然适用。
- 使用
GET /itineraries和cancel_refund以“管理预订”作为您了解预订是否可退款以及应退款金额的权威来源。 - 确认邮件中也会显示调整后的取消政策。
- 购物中的
refundable布尔值不会因本次更改而修改；它仍然反映价格是否打算用于筛选目的 non-refundable。 - 检索行程响应中的
refundable参数反映了预订当前是否在适用的取消窗口期内；在显示 post-booking 选项时，使用此参数来决定预订是否可全额退款。