購物

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

簡介

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

包含多個 occupancy 參數執行個體，即可要求相同房型的多個房間。每回傳送要求時，若同一客房有多次要求預訂，則只會回傳一組該標準房價。一次最多可要求預訂 8 間客房。如果您需要一次預訂 8 間以上的客房，請聯絡您的客戶經理。我們正在致力於擴大團體預訂，分享您的要求將有助於我們找到解決方案。

價格顯示變化

請注意，由於當地法規的近期變化：

加州價格展示條例（加州議會法案 537）自 2024-07-01 起生效
明尼蘇達州價格展示條例（第 111 章 -H.F.No. 3438）自 2025-01-01 起生效

我們預計會有其他法規出台，因此不會針對每項法規更新此頁面，這只是兩個範例。

為何會有這些變化？

某些司法管轄區正在實施法律，規定如何向旅客顯示價格。每項法律都略有不同，但是，我們實施變更的方式將允許個人化遵守。

Expedia Group 對其 API 進行了更改，以使 API 合作夥伴能夠以多種方式顯示定價。但最終，每個使用 Expedia Group 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 與供應商簽訂的合約中指定的貨幣，通常是酒店的當地貨幣。這與 request_currency無關，因為 property_inclusive和 property_inclusive_strikethrough欄位可能包括以當地貨幣在飯店收取的費用。此行為與 inclusive和 inclusive_strikethrough欄位不同，其中 Expedia Collect 費率的 billable_currency與 request_currency相同。

商店回應中的財產收集金額分組可能與內容回應中顯示的金額不同。總數應該仍然正確匹配。

這是對所有房產實施的全球性變更，例如對變更有任何疑問，請聯絡您的客戶經理。

會員點數

商務旅客預訂參與 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 月份的住宿提供更高的利潤。針對飯店 19248 發出購物 API 請求，以便從 12 月 22 日到 1 月 5 日入住。在購物 API 回應的 marketing_fee_incentives物件中，您將看到對於從 12 月 22 日至 12 月 31 日所請求的部分住宿，即 14 個住宿晚數中的 10 個，有獎勵。

要求範例

curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2023-12-22\
&checkout=2024-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": "2023-12-22",
                "end": "2023-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 參數允許您將旅行指定為商務旅行或休閒旅行。從 2024 年 4 月 1 日開始，有資格以企業房價購物的合作夥伴，將需要在購物要求中使用 travel_purpose=business，才能在購物回應中接收企業房價。如果要求中未提供 travel_purpose 參數，將假設其為休閒旅行，並且不會回傳企業房價。

範例

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

&travel_purpose=business

刪除線價格

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欄位可讓合作夥伴顯示所有可退款選項，為旅客提供價格透明度和增強的靈活性。

這三個選項是：

refundable
non_refundable
partially_refundable

部分退款是什麼意思？

部分退款是指以下情況的房價：

取消罰金大於 0，但小於預訂總價值。

和/或

停留期間內有 non-refundable 個日期範圍。

利用 current_refundability 欄位比單獨使用可退款布林標誌有什麼好處？

refundable布爾標誌表示價格是否可以全額退款，但對於部分退款的價格，它會返回 false結果，這會誤導旅行者。current_refundability欄位提供了更細緻的選項，可以提供有關利率可退款性的更準確資訊。

合作夥伴如何接收商店回應中的 current_refundability 欄位？

合作夥伴需要請求 Shop 請求中current_refundability參數下的include欄位。

範例

"property_id": "23060",
  "status": "available".
  "rates": [
    {
      "id": "201392692",
      "status": "available",
      ...
      ...
      ...
      ...
      "current_refundability": partially_refundable,
      "cancel_penalties":[
        {
          "start": "2024-10-08T23:59:00.000+02:00",
          "end": "2024-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的可計費金額可能會有大約 0.1%（每客房 × 人 × 晚）的輕微變化，其中可能包括調整為零的金額。當 request_currency和 billable_currency的 Expedia Collect 費率不同時，就會出現飯店應付費用的差異。API 功能不會受到此差異的影響。

保留和復原

某些庫存不符合保留和恢復的條件。使用保留和恢復的合作夥伴可以透過採用 non-holdable 費率的購物指標來存取這些增量費率。更多詳情請參閱此處。

付款選項

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

重要注意事項

language 僅使用兩位數的語言與國家/地區代碼連字號配對。整合任何代碼前，請檢查我們的支援語言。
此兩位數 country 代碼會設定旅客的銷售點，但不會影響已本地化的內容。
不會傳回任何靜態資料 (名稱、星級評等、地理資訊等等)。僅提供供應情況與房價相關資料。
記號化連結會在短時間內到期。若記號傳回 HTTP 503 錯誤，表示連結可能已到期。透過更新的「購物」回應取得新價格檢查或訂金連結，然後再試一次。請勿儲存連結值供長期重覆使用。
Rapid API 允許旅宿隨時更新其內容。我們要求您致力向旅客提供最新的資訊。「購物 API」提供可預訂的房型和房價最新資訊。若要取得此回應未傳回的額外旅宿層級、客房層級和房價等級資訊，請使用我們的「旅宿內容 API」。
API 提供的價格僅限一間客房，若要預訂多個房間，需另自行計算。啟動條件也要求您的整合在預訂過程的某些特定步驟，向使用者顯示詳細價格明細。您可在此「安全文件連結」後找到明細。

若要針對此服務執行測試要求，請參閱我們的「測試要求」說明文件。

購物