購物

「購物 API」可讓您存取全球超過 700,000 處住宿的即時房價和供應情況。

簡介

「購物 API」會針對指定旅宿傳回所有房型的房價和供應情況 (每項請求最多 250 家旅宿)。回應包含諸如促銷、房價是否為可退款、是否有取消罰款和完整價格明細等房價詳情，以符合您市場的價格顯示規定。

包含多個 occupancy 參數執行個體，即可要求相同房型的多個房間。每回傳送要求時，若同一客房有多次要求預訂，則只會回傳一組該標準房價。一次最多可要求預訂 8 間客房。若您需要一次預訂超過 8 間客房，請聯絡您的客戶經理。我們目前正致力於擴展團體預訂服務，若您能告知您的需求，將有助於我們制定解決方案。

價格顯示變化

某些司法管轄區正在實施法律，規定必須以何種方式向旅客顯示價格。雖然每項法律略有不同，但我們實施這些變更的方式，將能讓各單位依其自身情況符合規定。

價格標示法規的範例包括但不限於：

為何要進行這些變更？

Expedia Group 已對其 API 進行調整，以便 API 合作夥伴能以多種方式顯示價格。然而，最終而言，每位使用「Expedia Group's」API 的合作夥伴，均有責任確保其顯示 Expedia 旅遊資訊及價格的方式符合法律規定。

Expedia 已針對「Rapid API」進行了優化，新增了一個名為「property_inclusive」的欄位，其中包含總價格，該價格涵蓋基礎房價以及整個住宿期間由 Expedia 及旅宿收取的所有費用與稅金。此總價的刪除線版本亦可於新欄位中查看property_inclusive_strikethrough。除了新增的旅宿包容性顯示欄位外，我們也重新調整了 API 回應中稅金與費用的分類方式。Expedia 收取的所有費用均歸類於「每晚及住宿」property_fee 價格明細類型，而 Expedia 收取的所有稅金則歸類於「每晚及住宿」tax_and_service_fee 價格明細類型。

針對 Expedia Collect 費率，billable_currency 和property_inclusive 欄位的「property_inclusive_strikethrough」將採用 Expedia Group's 中與供應商簽訂的合約所指定的貨幣，該貨幣通常為旅宿的當地貨幣。這與request_currency 無關，因為property_inclusive 和property_inclusive_strikethrough 欄位可能包含在旅宿以當地貨幣收取的費用。此行為與「inclusive」及「inclusive_strikethrough」欄位不同，在這些欄位中，Expedia Collect 費率的「billable_currency」將與「request_currency」相同。

「Shop」回應中，旅宿所列的總額分組方式，可能與「Content」回應中呈現的金額分組方式不同。總數應該還是會正確相符。

這是針對所有物業實施的全球性變更，若對此變更有任何疑問，請聯絡您的客戶經理。

會員點數

商務旅客預訂參與 Expedia 企業房價計畫且提供會員計畫的飯店，即可在住宿期間獲得飯店會員點數。合作夥伴可利用購物回應的設施服務節點，在擷取旅客的會員資訊前，確認並顯示會員可累積資格。

合作夥伴也可在購物 API 要求中使用 loyalty 值篩選條件，僅搜尋符合會員計畫的企業房價。

**備註：**只有在飯店已有會員計畫的情況下，企業房價才可累積會員點數。

範例：

可累積會員點數的飯店企業房價，會在搜尋回應的 amenities 節點底下出現以下參數

{
  "id": "2096",
  "name": "Eligible for hotel loyalty points"
}

佣金獎勵

作為 Rapid API 合作夥伴，您可以獲得額外的佣金獎勵，在指定的預訂和住宿日期期間為旅宿提供更高的利潤。要找出含有效佣金獎勵的旅宿，只需在 Rapid 購物 API 要求中使用 include 參數的 rooms.rates.marketing_fee_incentives 值即可。針對全部或部分所要求住宿期間的佣金獎勵費率，購物 API 回應中的 marketing_fee_incentives 物件將內含相關的其他詳細資訊，包括獎勵來源和受影響的住宿期間。然後，您可以在庫存排序和選擇過程中考慮此欄位和現有的 marketing_fee 欄位；該欄位是行銷費用的估計值，其中包括所有可用的獎勵措施。

範例

旅宿 19248 為 12 月份的住宿提供更高的利潤。針對以下訂單發出購物 API 請求：旅宿 19248，入住日期為 12 月 22 日至 1 月 5 日。在 Shopping API 回應中的 ``marketing_fee_incentives 物件中，您會發現針對 12 月 22 日至 12 月 31 日這段期間的部分住宿天數 (即 14 晚住宿中的 10 晚) 有優惠方案適用。

要求範例

curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2026-12-22\
&checkout=2027-01-05\
&currency=USD\
&country_code=US\
&language=en-US\
&occupancy=2\
&property_id=19248\
&rate_plan_count=1\
&sales_channel=website\
&sales_environment=hotel_only\
&include=rooms.rates.marketing_fee_incentives\
&travel_purpose=leisure" \
 -H "accept: application/json, application/json"\
 -H "accept-encoding: gzip"\
 -H "authorization: EAN apikey=abcd1234,signature=090a77e7ddd7779980231,timestamp=1697664047"\
 -H "user-agent: TravelNow/3.30.112"

回應範例

[
  {
    "property_id": "19248",
    "rooms": [
      {
        "id": "123abc",
        "room_name": "Fancy Queen Room",
        "rates": [
          {
            "id": "333abc",
            ...
            "marketing_fee_incentives": [
              {
                "source": "property",
                "start": "2026-12-22",
                "end": "2027-12-31"
              }
            ],
            "occupancy_pricing": {
              "2": {
                "nightly": [ ... ],
                "stay": [ ... ],
                "totals": {
                  "inclusive": { ... },
                  "exclusive": { ... },
                  "inclusive_strikethrough": { ... },
                  "strikethrough": { ... },
                  "marketing_fee": {
                    "billable_currency": {
                      "value": "276.36",
                      "currency": "USD"
                    },
                    "request_currency": {
                      "value": "276.36",
                      "currency": "USD"
                    }
                  },
                  "gross_profit": { ... },
                  "minimum_selling_price": { ... },
                  "property_fees": { ... }
                },
                "fees": { ... }
              }
            }
          }
        ]
      }
    ]
  }
]

旅遊目的

透過「travel_purpose」參數，您可以將旅客歸類為商務旅客或休閒旅客。所有 Rapid 合作夥伴皆可使用「travel_purpose」參數，協助住宿業者更有效地識別並服務企業差旅旅客。

對於符合資格可查詢商業差餉的合作夥伴，必須在「查詢」請求中使用travel_purpose=business，才能在「查詢」回應中收到商業差餉資訊。如果要求中未提供 travel_purpose 參數，將假設其為休閒旅行，並且不會回傳企業房價。

範例

要指定旅客的旅遊目的為商務性質，只需在供應情況 API 要求中加入 24 個字元，非常簡單。

&travel_purpose=business

產品銷售

我們已對購物 API 進行調整，以支援商品陳列流程，並讓您能無縫整合商品陳列 API：合作夥伴可使用「快速購物庫存狀態」端點中新增的「deal」篩選條件，僅接收包含有效促銷活動的價格。這讓合作夥伴能夠靈活地建立僅以商品陳列為重點的購物請求，並確保所有回傳的費率都具備「deal」屬性。

>> 進一步了解 Merchandising API

刪除線價格

strikethrough 欄位提供適用任何飯店資助折扣之前的不含稅總價。此欄位應在美國等地區使用，這些地區通常在搜尋結果中顯示不含稅金和其他費用的基本價格。

inclusive_strikethrough 欄位顯示折扣前的總價，包括稅金和其他費用。此欄位旨在讓您更清楚地顯示提供全包價格 (即基本價格、稅金和其他費用) 的區域中適用的折扣。該欄位回傳以計費貨幣和要求貨幣表示的值。

範例

[
  {
    "property_id": "19248",
    "rooms": [
      {
        "id": "123abc",
        "room_name": "Fancy Queen Room",
        "rates": [
          {
            "id": "333abc",
            ...
            "occupancy_pricing": {
              "2": {
                "nightly": [ ... ],
                "stay": [ ... ],
                "totals": {
                  "inclusive": { ... },
                  "exclusive": { ... },
                  "inclusive_strikethrough": {
                    "billable_currency": {
                      "value": "726.63",
                      "currency": "CAD"
                    },
                    "request_currency": {
                      "value": "549.60",
                      "currency": "USD"
                    }
                  },
                  "strikethrough": {
                    "billable_currency": {
                      "value": "650.00",
                      "currency": "CAD"
                    },
                    "request_currency": {
                      "value": "491.64",
                      "currency": "USD"
                    }
                  },
                  "marketing_fee": { ... },
                  "gross_profit": { ... },
                  "minimum_selling_price": { ... },
                  "property_fees": { ... }
                },
                "fees": { ... }
              }
            }
          }
        ]
      }
    ]
  }
]

促銷及折扣價格顯示

顯示根據促銷活動提供的折扣優惠金額，或是供應情況與價格檢查 API 所提供的原價與優惠價比較金額時，特定銷售點會要求提供標準房價的詳細資訊 (也就是用來計算折扣的價格基礎)。有關用詞使用規定，請參閱下方說明。

**歐盟：**請提供標準房價的清楚詳細資訊 (例如：「此為根據您的搜尋，旅宿所提供的標準房價」)。

**義大利：**請使用以下文字敘述：「Questo prezzo è basato sulla tariffa generalmente applicabile fornita dalla struttura per questa camera e per queste date.」

退款選項

「current_refundability」欄位可讓合作夥伴顯示所有退款選項，為旅客提供價格透明度並提升靈活性。

這 3 個選項分別是：

refundable
non_refundable
partially_refundable

「部分可退款」是什麼意思？

「部分可退款」是指取消罰金高於 0 但低於預訂總金額的房價方案及／或，且入住期間內包含 non-refundable 所列的日期範圍。

>> 了解取消訂單的罰則

善用 ``current_refundability 欄位，究竟比僅使用可退還的布林標誌 (Boolean flag) 有何優勢？

refundable布林標誌用以標示某種房價是否為全額可退款，但對於部分可退款的房價，它會回傳false 的結果，這會誤導旅客。「current_refundability」欄位提供了一項更細緻的選項，能針對費率的可退還性提供更精確的資訊。

合作夥伴該如何在 Shop 回應中取得「`current_refundability`」欄位？

合作夥伴需在「Shop」請求中，於「current_refundability」參數下請求「include」欄位。

範例

"property_id": "23060",
  "status": "available".
  "rates": [
    {
      "id": "201392692",
      "status": "available",
      ...
      ...
      ...
      ...
      "current_refundability": partially_refundable,
      "cancel_penalties":[
        {
          "start": "2027-10-08T23:59:00.000+02:00",
          "end": "2027-10-09T23:59:00.000+02:00",
          "nights":"1",
          "currency": "EUR"
        }
      ]
    }
  ]

無法提供的原因

unavailable_reason 功能可讓您查詢旅宿在特定住宿條件下 (住宿日期和入住人數) 完全無法提供入住的原因，並提供可採取的行動資訊。購物時，必須包含可選的要求參數 include=unavailable_reason，才能在回應中接收此資訊。然而，並非所有無法提供的旅宿都有不可預訂的可訴理由。這些旅宿不會在回應中回傳。

「購物」回應可能包括可提供和無法提供的旅宿混合。無法提供的旅宿將包括 property_id、score 和 unavailable_reason 部分，其中包含 code 和對該旅宿無法提供的簡短說明 (以英文提供)，以及 data 以獲得可在要求中調整的其他資訊來提供旅宿/客房/房價計畫。例如，如果 unavailable_reason code 為 adults_exceed_threshold，則 data 中的 2 表示該客房/房價允許的最大人數為 2 名成人，任何大於 2 的入住人數都會回傳錯誤。

**注意：**旅宿可以套用多個限制，但只會回傳一個 unavailable_reason。

範例

[
  {
    "property_id": "824739",
    "score": 12345,
    "unavailable_reason": {
      "code": "adults_exceed_threshold",
      "data": "2"
    }
  }
]

>> 查看返回的完整代碼清單

設施服務篩選條件

或者，您可以使用 amenity_category 要求參數以及一項或多項特定設施服務來篩選在 Rapid 購物回應中回傳的旅宿。請參閱內容參考清單中的「設施類別」部分，以查看可用於篩選回應的設施清單。

>> 查閱內容參考清單

範例

單一設施服務篩選條件：

&amenity_category=free_breakfast

多項設施服務篩選條件：

&amenity_category=free_breakfast&amenity_category=free_airport_transfer&amenity_category=casino

速率限制

我們對合作夥採取速率限制，以實現流量最佳化。這些速率限制確保我們能夠為合作夥伴提供穩定且不間斷的服務，同時保證 Expedia Group 系統的使用效率。對於商店流量，決定負載的重要因素是每個要求中搜尋的旅宿數量、客房數量和住宿天數。

>> 進一步了解速率限制

價格檢查

確認「購物」回應傳回的價格。使用此 API 驗證先前選取的價格在預訂前仍然有效。若價格相符，則回應會傳回連結以要求預訂。若價格已變更，則回應會傳回新價格詳細資訊以及新價格的預訂連結。若房價不再適用，則回應會傳回新的購物要求連結以重新搜尋其他房價。

在PriceCheck 上顯示的totals.property_fees 及fees 應付金額，與先前 Shop 的回覆相比，可能會出現約 0.1% 的輕微差異 (以客房 × 人 × 晚為單位計算)，其中可能包含調整為零的金額。當request_currency 與billable_currency 兩者針對 Expedia Collect 費率的報價不同時，便會導致旅宿應付費率出現差異。API 功能不會受到此差異的影響。

保留和復原

部分庫存不適用「暫停與恢復」功能。使用「暫停與恢復」功能的合作夥伴，可透過採用「non-holdable」費率的購物指標，取得這些遞增費率。

>> 進一步了解「暫停與恢復」功能

付款選項

回傳當 Expedia 向最終旅客收取款項 (EPS MOR) 時，可接受的付款方式。使用此 API 啟動付款頁面，並顯示有效的付款方式，確保順利進行預訂。

重要注意事項

language僅使用以連字號連接的 2 位數語言代碼與國家代碼組合。

>> 查看我們支援的語言

這組 2 位數的「country」代碼用於設定旅客的銷售據點，不會影響在地化內容。
不會傳回任何靜態資料 (名稱、星級評等、地理資訊等等)。僅提供供應情況與房價相關資料。
記號化連結會在短時間內到期。若記號傳回 HTTP 503 錯誤，表示連結可能已到期。透過更新的「購物」回應取得新價格檢查或訂金連結，然後再試一次。請勿儲存連結值供長期重覆使用。
Rapid API 允許旅宿隨時更新其內容。我們要求您致力向旅客提供最新的資訊。「購物 API」提供可預訂的房型和房價最新資訊。若要取得本回應中未包含的 property-level, room-level, 及 rate-level 相關資訊，請使用我們的旅宿內容 API。

>> 了解旅宿內容 API

API 提供的價格僅限一間客房，若要預訂多個房間，需另自行計算。作為上線要求的一部分，您的整合系統應在預訂流程的特定步驟中，向終端使用者顯示詳細的價格明細。
>> 請至我們的安全合作夥伴網站查看詳細說明

>> 了解如何執行測試請求

購物

「購物 API」可讓您存取全球超過 700,000 處住宿的即時房價和供應情況。

簡介

價格顯示變化

為何要進行這些變更？

有哪些變更？

會員點數

佣金獎勵

旅遊目的

產品銷售

刪除線價格

促銷及折扣價格顯示

退款選項

「部分可退款」是什麼意思？

善用 ``current_refundability 欄位，究竟比僅使用可退還的布林標誌 (Boolean flag) 有何優勢？

合作夥伴該如何在 Shop 回應中取得「`current_refundability`」欄位？

無法提供的原因

設施服務篩選條件

速率限制

價格檢查

保留和復原

付款選項

可變稅項及費用

API 詳細資料

其他資源

「購物 API」可讓您存取全球超過 700,000 處住宿的即時房價和供應情況。

「部分可退款」是什麼意思？

善用 ``current_refundability 欄位，究竟比僅使用可退還的布林標誌 (Boolean flag) 有何優勢？

合作夥伴該如何在 Shop 回應中取得「current_refundability」欄位？

合作夥伴該如何在 Shop 回應中取得「`current_refundability`」欄位？