目录

优惠 API

优惠 API 是仅向受邀者开放的封闭公测计划的一部分。如果您已受邀参与此计划，请联系您的 Meta 代表，获取访问权限。


通过使用此 API，您可以将优惠信息添加到商品目录，以便在 Facebook 和 Instagram 上启用优惠推销。对于已启用 Facebook 或 Instagram 结账功能的卖家，买家可以直接在 Meta 旗下应用中兑现优惠。

创建优惠

您可以通过优惠动态或手动通过电商管理工具创建优惠。

动态

要创建新的优惠动态，请向 /{product_catalog_id}/product_feeds 连线提出 POST 请求，并将 feed_type 设置为 OFFER。当发布至此连线时，系统将为 product_catalog_id 字段中指定的目录创建商品动态类型优惠。

优惠动态创建后，您可以通过 POST 请求将优惠数据上传至 /{product_feed_id}/uploads 连线。

动态栏

您可以将下方列出的大部分可用字段设为信息库文件的栏。创建时，只有标记为只读的字段无法被设置。

术语表

商品系列

商品系列是商品目录中的一组相关商品。

优惠目标商品

这是指优惠有效的商品。

优惠前提条件

这是指应用优惠时需要满足的前提条件。例如，您可以决定只有当人们至少购买特定数量的商品，或至少达到特定小计数量或价值的商品时，优惠才有效。目前，设有前提条件的商品来自目标商品。例如，所有鞋子打八折意味着购物车中的鞋子必须满足最低小计/数量要求。

优惠应用类型

优惠应用类型是指在您自己的网站上或在 Facebook 上结账时优惠应用的方式。例如，应用类型可用来决定是否在结账时自动应用优惠或要求输入抵用券代码来兑现。应用类型还表示某种优惠是否能与其他优惠叠加使用。如需了解更多信息，请参阅叠加使用优惠。

基本字段

以下字段可用于配置所有优惠类型。

字段描述

id

类型：numeric string

只读。

此商品的独特识别码 (Facebook ID)。

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 的购物界面（如商品详情页），且不会向买家推销。这是为了避免将私人代码或秘密代码不小心泄漏给买家。您可以通过指定用于推销优惠的公开抵用券代码来改变此行为。使用公开代码的优惠将与使用 AUTOMATIC_AT_CHECKOUT 的 application_type 的优惠以相同方式显示，但也具有代码文本。


公开抵用券代码长度不能超过 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 件衬衫，立享八折优惠”。


只能设置 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：代表应用于购物车中所有目标商品的折扣。例如，如果您拥有“鞋类立减 $30”的优惠，且购物车内有 3 双鞋子，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）列表。


例如，如需指定适用于标准和特急配送方式而不是次日送达的优惠，请使用：

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

对于已启用 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 件五折”优惠中，目标数量为 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 公共主页的粉丝。