目錄

優惠 API

優惠 API 是不公開、僅限邀請參與的測試版計畫。如果您已受邀參與此計畫，請與您的 Meta 代表合作取得存取權限。


您可以使用此 API 將優惠資訊新增至您的產品目錄，以便在 Facebook 和 Instagram 上推銷您的優惠。對於已啟用 Facebook 或 Instagram 結帳功能的賣家，買家將能夠直接在 Meta 系列應用程式中兌換您的優惠。

建立優惠

您可以透過優惠摘要或手動透過商業管理工具建立優惠。

摘要

若要建立新的優惠摘要，請發出 POST 要求至 /{product_catalog_id}/product_feeds 關係連線，並將 feed_type 設為 OFFER。發佈到此關係連線時，會為 product_catalog_id 欄位中指定的目錄建立優惠類型的產品摘要。

建立優惠摘要後，您可以發出 POST 要求至 /{product_feed_id}/uploads 關係連線，以上傳優惠資料。

摘要直欄

您可以將下面列出的大部分可用欄位設定為摘要檔案中的直欄。只有標示為「唯讀」的欄位不能在建立流程中設定。

詞彙表

商品組合

商品組合是指商品目錄中的相關商品群組。

優惠目標商品

這是指適用優惠的產品。

優惠的必要條件

這是指套用優惠需要達到的必要條件。例如，您可以決定用戶必須購買至少特定數量的產品，或至少達到這些產品的特定小計數量或價值時，才適用優惠。目前，必要產品是衍生自目標產品。例如，所有鞋類享有 20% 折扣，表示購物車中的鞋類必須達到小計最低金額／數量要求。

優惠套用類型

優惠的套用類型可指定在您自己的網站上或 Facebook 結帳功能內結帳時，如何套用優惠。例如，套用類型可用來決定是否在結帳時自動套用優惠，或是需要兌換優惠券代碼。套用類型也可以指出某項優惠與其他優惠的組合行為。如需更多詳細資訊，請參閱組合優惠。

基本欄位

以下欄位可用來配置所有優惠類型。

欄位說明

id

類型：numeric string

唯讀。

此商品的唯一識別碼（Facebook 編號）。

offer_id

類型：string

必要項目。

賣家已提供優惠的識別碼。


此欄位用來識別目錄中的專屬優惠。

title

類型：string

選用項目。

優惠商品的標題。


目前，此標題僅用於協助識別商業管理工具中的優惠，並不會對買家顯示。

description

類型：string

唯讀。

自動產生的優惠說明。

application_type

類型：enum{SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED}

必要項目。

決定套用優惠的方式和時機。可用選項有：

  • SALE：商品直接降價，對買家顯示劃掉的原價。這些優惠不需要買家達到任何必要條件，而且在結帳時不受其他商品的影響。系統一律選擇產生商品最低價格的促銷活動，因為促銷活動不得合併。促銷活動可以與其他優惠類型合併，但一律優先套用。如果產品已設定 sale_price 欄位，則會使用 sale_price 為基本價格來計算最終價格。
  • AUTOMATIC_AT_CHECKOUT：當買家達到必要的兌換標準時，會在結帳時自動套用優惠。此優惠有一些配置，使其不符合促銷活動資格，只能與促銷優惠合併使用。這類優惠一次最多可以有 25 項有效優惠。
  • BUYER_APPLIED：此優惠會依據買家採取的行動（例如輸入優惠代碼），在結帳時套用。這類優惠目前不能互相併用，或與結帳時自動套用的優惠併用。必須提供 [public_coupon_code、coupon_codes] 其中一項。

coupon_codes

類型：Array<string>

顧客在結帳時用來兌換優惠的優惠券代碼清單（不區分大小寫）。最多允許 100 個優惠券代碼。例如：["10OFF", "HOLIDAY_SALE"]


僅限在 application_type 為 BUYER_APPLIED 時，才能指定優惠券代碼。


若設定此欄位，則 public_coupon_code 必須為 null。

public_coupon_code

類型：string

選用項目。

不區分大小寫的單一優惠券代碼，將與優惠一起促銷，如果買家達到優惠的必要條件，則會在結帳時預先填入。


預設情況下，含有優惠券代碼的優惠不會在 Facebook 或 Instagram 購物介面（例如產品詳細資訊頁面）上對買家顯示。這是為了防止誤將不公開或秘密的代碼洩露給買家。若要變更此作法，您可以指定用來推銷優惠的公開優惠券代碼。含有公開代碼的優惠顯示方式與 application_type 為 AUTOMATIC_AT_CHECKOUT 的優惠相同，但​​也會提供代碼文字。


公開優惠券代碼的長度不能超過 20 個字元，而且您的目錄一次最多只能包含 10 個含有公開優惠券代碼的有效優惠。


僅限在 application_type 為 BUYER_APPLIED 時，才能設定公開優惠券代碼。


若設定此欄位，則 coupon_codes 必須為 null。

start_date_time

類型：timestamp

必要項目。

優惠開始時的 Unix 時間戳記（以秒為單位）。


輸入值可以是 Unix 時間戳記（以秒為單位），也可以是 ISO-8601 格式的日期字串（例如 2021-09-25T12:34:56Z）。

end_date_time

類型：timestamp

選用項目。預設為 null。

優惠結束時的 Unix 時間戳記（以秒為單位）。如果保留空白或 null，則優惠沒有結束日期。


輸入值可以是 Unix 時間戳記（以秒為單位），也可以是 ISO-8601 格式的日期字串（例如 2021-09-25T12:34:56Z）。

min_quantity

類型：int64

選用項目。預設為 0。


如果顧客必須購買最低數量的產品，才適用優惠，請使用此欄位。


此欄位表示顧客需要購買才適用優惠的產品數量。例如：「買 5 件襯衫，享 20% 折扣」。


僅限設定 min_quantity 或 min_subtotal 其中一項。

min_subtotal

類型：string

選用項目。預設為 null。


如果顧客的訂單必須達到特定小計值，才適用優惠，請使用此欄位。


必要產品的小計必須等於或大於此值，才能套用優惠。如果未設定明確的必要產品，則使用目標產品做為必要產品。


此欄位的格式應為金額，後面接著 3 個字母的 ISO 幣別代碼，金額與幣別之間空一格。例如：字串「30.99 USD」表示小計必須達到 30.99 美元，才能套用優惠。


僅限設定 min_quantity 或 min_subtotal 其中一項。

redeem_limit_per_user

類型：int64

選用項目。預設為 0（無限制）。

單一用戶可以使用此優惠的次數上限。


將此欄位設為 1，可建立一次性優惠券代碼。


application_type 必須為 BUYER_APPLIED，才能設定此欄位。

value_type

類型：enum {FIXED_AMOUNT, PERCENTAGE}

必要項目。

此優惠提供的折扣類型。


可用選項有：

  • FIXED_AMOUNT：套用擷取自 fixed_amount_off 的折扣值。
  • PERCENTAGE：套用擷取自 percent_off 的折扣百分比值。

fixed_amount_off

類型：string

如果 value_type 設為 FIXED_AMOUNT，則此為必要項目。

此優惠的折扣金額。格式應為金額，後面接著 3 個字母的 ISO 幣別代碼，金額與幣別之間空一格。例如，字串「30.99 USD」代表折扣 30.99 美元。


value_type 必須為 FIXED_AMOUNT，才能設定此欄位。

percent_off

類型：int64

如果 value_type 設為 PERCENTAGE，則此為必要項目。

此優惠的折扣百分比。應為 0 到 100 之間的整數。例如，「30」代表折扣 30%。


value_type 必須為 PERCENTAGE，才能設定此欄位。

target_granularity

類型：enum {ITEM_LEVEL, ORDER_LEVEL}

必要項目。

套用優惠折扣的層級。


可用選項有：

  • ITEM_LEVEL：代表套用於購物車中個別目標商品的折扣。
  • ORDER_LEVEL：代表套用於購物車中整批目標商品的折扣。例如，如果您設定購物車中 3 雙鞋享有「鞋子折扣 30 美元」的優惠，則 ITEM_LEVEL 會針對每雙鞋套用 30 美元的折扣（價值 90 美元），而 ORDER_LEVEL 會針對全部 3 雙鞋的總價套用 30 美元的折扣（最多 30 美元）。

請注意，ORDER_LEVEL 層級的優惠可能會導致購買時的折扣分配無法均分至訂單中的每項商品。處理這些不平均的折扣分配可能會導致履行時或退款時增加複雜性。

offer_terms

類型：string

選用項目。

規定買家使用優惠時的任何附加條款與條件。最多 2500 個字元。


Facebook 會根據優惠配置，自動產生說明優惠的條款。除了這些條款之外，您也可以使用 offer_terms 來增加說明自有優惠條款的語言。這些條款會顯示在 Facebook 的優惠條款下方。


內容必須遵循我們的內容政策。

指定符合條件的產品

適用優惠的目標商品，以及買家必須購買才能兌換優惠的必要商品，皆由商品組合定義。優惠 API 支援多種指定這些商品組合的方式，但每項優惠的每個商品組合類型只能使用一種方法。

欄位說明

target_selection

類型：enum{ALL_CATALOG_PRODUCTS, SPECIFIC_PRODUCTS}

必要項目。

此欄位用於區分套用於整個商品目錄的優惠，以及僅限於目錄中特定商品子集的優惠。


可用選項有：

  • ALL_CATALOG_PRODUCTS：優惠可套用於目錄中的任何產品。
  • SPECIFIC_PRODUCTS：優惠僅限套用於 target_filter、target_product_retailer_ids、target_product_group_retailer_ids 或 target_product_set_retailer_ids 指定的目標產品。

如果 target_selection 為 SPECIFIC_PRODUCTS，則需要下列其中一項：target_filter、target_product_retailer_ids、target_product_group_retailer_ids 或 target_product_set_retailer_ids。

target_filter

類型：JSON-encoded string

選用項目。


篩選規則，用以識別可套用優惠的產品。使用將產品加入商品組合時所使用的相同篩選規則邏輯。


如果指定的篩選規則與現有商品組合的篩選規則相符，則此優惠的目標會設定為該商品組合，否則會建立新的商品組合。


target_selection 必須設為 SPECIFIC_PRODUCTS，才能設定此欄位。

target_product_retailer_ids

類型：Array<product_retailer_id>

選用項目。


可套用優惠之產品的產品項目零售商編號清單。


target_selection 必須設為 SPECIFIC_PRODUCTS，才能設定此欄位。

target_product_group_retailer_ids

類型：Array<product_group_retailer_id>

選用項目。


可套用優惠之產品的產品群組零售商編號清單。


產品群組中包含的所有產品款式皆符合此優惠的條件。


target_selection 必須設為 SPECIFIC_PRODUCTS，才能設定此欄位。

target_product_set_retailer_ids

類型：Array<product_set_retailer_id>

選用項目。


包含可套用優惠之產品的商品組合零售商編號清單。此優惠將套用於評估指定商品組合後產生之所有產品的總合。

prerequisite_filter

類型：JSON-encoded string

選用項目。


篩選規則，用以識別買家必須購買才能兌換優惠的產品。使用將產品加入商品組合時所使用的相同篩選規則邏輯。通常用於「買 X 送 Y」型式的優惠。


如果指定的篩選規則與現有商品組合的篩選規則相符，則此優惠會使用該商品組合來定義必要產品，否則會建立新的商品組合。


若設定此欄位，則 prerequisite_product_retailer_ids、prerequisite_product_group_retailer_ids 和 prerequisite_product_set_retailer_ids 必須為 null。

prerequisite_product_retailer_ids

類型：Array<product_retailer_id>

選用項目。


買家必須購買才能兌換優惠的產品項目零售商編號。清單中包含的任何商品皆符合買家可用作兌換優惠的必要條件。通常用於「買 X 送 Y」型式的優惠。


若設定此欄位，則 prerequisite_filter、prerequisite_product_group_retailer_ids 和 prerequisite_product_set_retailer_ids 必須為 null。

prerequisite_product_group_retailer_ids

類型：Array<product_group_retailer_id>

選用項目。


買家必須購買才能兌換優惠的產品群組零售商編號。每個群組中包含的所有產品款式皆符合買家可用作兌換優惠的必要條件。通常用於「買 X 送 Y」型式的優惠。


若設定此欄位，則 prerequisite_filter、prerequisite_product_retailer_ids 和 prerequisite_product_set_retailer_ids 必須為 null。

prerequisite_product_set_retailer_ids

類型：Array<product_set_retailer_id>

選用項目。


包含買家必須購買才能兌換優惠之商品的商品組合零售商編號。評估商品組合後，從總合產生的任何商品皆符合買家可用作兌換優惠的必要條件。通常用於「買 X 送 Y」型式的優惠。


若設定此欄位，則 prerequisite_filter、prerequisite_product_retailer_ids 和 prerequisite_product_group_retailer_ids 必須為 null。

exclude_sale_priced_products

類型：bool enum {YES, NO}

選用項目。

優惠是否套用於目錄中已設定減價的產品，如產品項目的 sale_price 欄位所指定。


將此欄位設為 YES 可避免產品套用雙重折扣的可能性。忽略此欄位或將其設定為 NO，則會包含目錄中設定較低 sale_price 的產品。


設定後，此欄位會同時套用於優惠的目標產品和必要產品。

運費優惠

優惠 API 支援買家購買產品享有折扣價格的優惠，以及這些產品享有運費折扣的優惠。就像產品優惠一樣，運費可以透過優惠券代碼來套用優惠，也可以在有或沒有額外買家必要條件的情況下自動套用優惠。

若要建立運費優惠，target_type 必須設定為 SHIPPING。目前僅支援免運費優惠，因此 value_type 一律設定為 PERCENTAGE，而 percent_off 設定為 100。

欄位說明

target_type

類型：enum{LINE_ITEM, SHIPPING}

必要項目。

此優惠套用的物件類型：

  • LINE_ITEM：優惠套用於產品項目本身。
  • SHIPPING：優惠套用於運費。只有在 target_granularity 為 ITEM_LEVEL 時，此選項才有效。

target_shipping_option_types

類型：Array<shipping_service_tier>

如果 target_type 為 SHIPPING，則此為必要項目。

適用優惠的配送服務等級清單（例如 STANDARD、RUSH、EXPEDITED）。


例如，若要指定套用於標準和快速到貨但非隔日到貨的運費優惠，請使用：

  • target_type 為 SHIPPING
  • target_shipping_option_types 為 ["STANDARD", "RUSH"]

對於已啟用 Facebook 或 Instagram 結帳功能的賣家，您可以使用配送設定 API 來管理您商業帳號上的配送設定。

買 X 送 Y 優惠

「買 X 送 Y」型式的優惠可讓買家購買特定數量的精選「X 產品」，而得以用折扣價或免費獲得 1 或多件的「Y 產品」。此外，也支援「滿 X 送 Y」優惠，買家必須達到一組 X 產品的最低消費門檻，才能享有折扣。您可以設定 target_quantity 欄位以及 min_quantity 或 min_subtotal 欄位來建立「買 X 送 Y」優惠。

在某些情況下，例如常見的「買一送一」優惠，X 和 Y 可能是指同一組產品。不過，您也可以使用 prerequisite_filter、prerequisite_product_retailer_ids、prerequisite_product_group_retailer_ids 和 prerequisite_product_set_retailer_ids 來指定一組不同於目標 Y 產品的 X 產品。若要瞭解如何配置這些欄位，請參閱指定符合條件的產品。

欄位說明

target_quantity

類型：int64

選用項目。預設為 0（無限制）。

每次兌換優惠可享折扣的產品數量。設定 target_quantity > 0 即構成「買 X 送 Y」型式的優惠。


使用此欄位來控制買家達成兌換必要條件時，可享有折扣的產品數量。例如，在「買 2 件，1 件折 50%」的優惠中，目標數量為 1，在「買 5 送 2」的優惠中，目標數量為 2。

redemption_limit_per_order

類型：int64

選用項目。預設為 0（無限制）。

每筆訂單可以兌換此優惠的次數。


使用此欄位來限制優惠可套用於買家購買產品的次數。例如，在「襯衫買一送一」優惠中，預設購買 6 件襯衫的買家可享有 3 件全價和 3 件免費。然而，在同一範例中，如果 redemption_limit_per_order 設定為 2，則買家享有 2 件襯衫免費和 4 件襯衫全價。


若設定此欄位，則 target_quantity 必須大於 0。

合併優惠

對於在 Facebook 或 Instagram 上啟用結帳功能的賣家來說，在單筆交易中合併多項優惠的支援有限。一項優惠是否可與其他優惠合併，主要取決於其套用類型和目標類型。目前賣家無法配置此行為。以下規則概括優惠的疊加行為：

  • 針對給定的產品，如果有任何會導致劃掉原價（application_type = SALE）的優惠，則套用可導致最低產品價格的優惠。此行為會針對買家購物車中的所有商品重複操作。商品的新折扣價將用於所有未來優惠必要條件的計算。
  • 在單一訂單中，買家可以依據 target_type（LINE_ITEM 或 SHIPPING）兌換 1 項 BUYER_APPLIED 或 1 項 AUTOMATIC_AT_CHECKOUT 優惠。例如，買家可以套用免運費優惠券和買一送一優惠券，但不能兌換 2 項都能使產品折價的優惠。
  • Meta 有時候可能會提供優惠來吸引新客和回頭客，而賣家不需支付任何費用。由 Meta 提供的優惠一律可與賣家提供的優惠併用。

限制用戶獲得優惠的資格

目前，透過優惠 API 建立的優惠無法選擇性地向特定用戶群體促銷。在商業管理工具中建立的優惠可以配置用戶資格限制。透過優惠 API 建立的促銷優惠會向所有買家顯示，而任何買家只要在 Facebook 或 Instagram 結帳功能中達到優惠的必要條件（包括輸入任何優惠券代碼），都可以兌換該優惠。

在未來，優惠 API 可能會支援將跨國賣家的優惠限制在特定國家／地區，以及將優惠資格限制在特定用戶群組，例如進行首購的買家或賣家 Facebook 粉絲專頁的追蹤者。