建構取消規定
了解 Rapid Lodging API 如何建模並提供取消政策相關功能
簡介
Rapid Shopping API 會針對「房況」回應中的每種房價，回傳相應的取消政策詳情。各費率的具體取消政策係依據以下關鍵項目所制定：
- 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. Expedia 的系統會自動調整位於加利福尼亞州的任何旅宿的取消期限。
預期行為範例：
- 對於位於加州且費率可全額退還、無需支付取消費用的旅宿，其取消政策將維持不變。
- 對於位於加州、且採用「non-refundable」費率、並自預訂時起即適用取消罰金的旅宿，其取消政策將進行修訂，自預訂建立日期起滿 24 小時後正式生效。
- 若旅宿位於加州以外地區，即使預訂是在加州進行的，取消政策也不會有所變更。
Pre-booking 取消政策
當旅客正在選購時，更新後的取消罰金時限將自動顯示於 API 呼叫中。您可能會注意到，針對 non-refundable 的預訂，refundable 標記仍維持為 false；因此，您需要根據取消時限來遵守此規定。 對於飯店而言，該時限為自預訂時間戳記起算的 24 小時。對於 Vrbo 房源，期限為預訂完成後的次日結束前。
Post-booking 取消政策
預訂完成後，調整後的加州保單仍繼續適用。
- 請以「管理預訂」中的
GET /itineraries和cancel_refund作為判定預訂是否可退款及應退還金額的權威依據。 - 確認電子郵件中亦會顯示經調整的取消政策。
- 「Shopping」中的 ``refundable
- 「檢索行程」回應中的 ``refundable