Package google.shopping.merchant.promotions.v1beta

索引

• PromotionsService（接口）
• Attributes（消息）
• CouponValueType（枚举）
• GetPromotionRequest（消息）
• InsertPromotionRequest（消息）
• ListPromotionsRequest（消息）
• ListPromotionsResponse（消息）
• OfferType（枚举）
• ProductApplicability（枚举）
• Promotion（消息）
• PromotionStatus（消息）
• PromotionStatus.DestinationStatus（消息）
• PromotionStatus.DestinationStatus.State（枚举）
• PromotionStatus.ItemLevelIssue（消息）
• PromotionStatus.ItemLevelIssue.Severity（枚举）
• RedemptionChannel（枚举）
• StoreApplicability（枚举）

PromotionsService

用于管理商品促销活动的服务。

GetPromotion
rpc GetPromotion(GetPromotionRequest) returns (Promotion) 从您的 Merchant Center 账号检索促销活动。 插入或更新促销活动输入后，可能需要几分钟时间才能检索到更新后的促销活动。 授权范围 需要以下 OAuth 范围： https://www.googleapis.com/auth/content 如需了解详情，请参阅 OAuth 2.0 Overview。

InsertPromotion
rpc InsertPromotion(InsertPromotionRequest) returns (Promotion) 为您的 Merchant Center 账号插入促销活动。如果促销活动已存在，则系统会改为更新促销活动。 授权范围 需要以下 OAuth 范围： https://www.googleapis.com/auth/content 如需了解详情，请参阅 OAuth 2.0 Overview。

ListPromotions
rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse) 列出 Merchant Center 账号中的促销活动。响应中包含的项目数量可能少于 pageSize 指定的数量。依赖于 pageToken 来确定是否有更多要请求的项。 插入或更新促销活动后，可能需要几分钟才能检索到更新后的处理过的促销活动。 授权范围 需要以下 OAuth 范围： https://www.googleapis.com/auth/content 如需了解详情，请参阅 OAuth 2.0 Overview。

属性

属性。

字段
product_applicability	ProductApplicability 必需。促销活动适用于所有商品还是仅适用于特定商品。
offer_type	OfferType 必需。促销活动的类型。您可以使用此属性指明客户是否需要优惠券代码才能兑换您的促销。
generic_redemption_code	string 可选。促销活动的通用兑换码。可与 offerType 字段搭配使用，并且必须满足最低要求。
long_title	string 必需。促销活动的长标题。
coupon_value_type	CouponValueType 必需。优惠券价值类型属性，用于表明您开展的促销活动的类型。某些属性是必需的，具体取决于所选优惠券价值的类型。
promotion_destinations[]	DestinationEnum 必需。促销活动适用的目标平台列表。如果您未通过在数据源中添加受支持的值来指定目标平台，则默认情况下，您的促销活动将在购物广告和非付费商品详情中展示。 您以前可能提交了以下值作为商品目标平台：Shopping Actions、Surfaces across Google、Local surfaces across Google。如需表示这些值，请使用 FREE_LISTINGS、FREE_LOCAL_LISTINGS、LOCAL_INVENTORY_ADS。如需了解详情，请参阅促销活动目标位置
item_id_inclusion[]	string 可选。按促销活动的商品 ID 过滤商品。仅当符合促销条件的商品 product_applicability（适用商品）属性设置为 specific_products 时，商品过滤条件属性才适用。
brand_inclusion[]	string 可选。促销活动的按品牌过滤条件。仅当符合促销条件的商品 product_applicability（适用商品）属性设置为 specific_products 时，商品过滤条件属性才适用。
item_group_id_inclusion[]	string 可选。按促销活动的商品组 ID 过滤商品。仅当符合促销条件的商品 [product_applicability] 属性设置为 specific_products 时，商品过滤条件属性才适用。
product_type_inclusion[]	string 可选。按商品类型过滤促销商品。仅当符合促销条件的商品 product_applicability（适用商品）属性设置为 specific_products 时，商品过滤条件属性才适用。
item_id_exclusion[]	string 可选。按促销活动的商品 ID 排除对象过滤商品。仅当符合促销条件的商品 product_applicability（适用商品）属性设置为 specific_products 时，商品过滤条件属性才适用。
brand_exclusion[]	string 可选。促销活动的品牌排除对象过滤条件。仅当符合促销条件的商品 product_applicability（适用商品）属性设置为 specific_products 时，商品过滤条件属性才适用。
item_group_id_exclusion[]	string 可选。按商品组 ID 过滤商品。仅当符合促销条件的商品 product_applicability（适用商品）属性设置为 specific_products 时，商品过滤条件属性才适用。
product_type_exclusion[]	string 可选。促销活动的商品类型排除对象过滤条件。仅当符合促销条件的商品 product_applicability（适用商品）属性设置为 specific_products 时，商品过滤条件属性才适用。
minimum_purchase_amount	Price 可选。促销活动的最低交易额。
minimum_purchase_quantity	int64 可选。促销的最低购买数量。
limit_quantity	int64 可选。促销活动的购买数量上限。
limit_value	Price 可选。促销活动允许的商品价格上限。
percent_off	int64 可选。促销活动提供的折扣百分比。
money_off_amount	Price 可选。促销活动提供的折扣金额。
get_this_quantity_discounted	int64 可选。促销活动中享受折扣的商品数量。当 couponValueType 等于 buy_m_get_n_money_off 或 buy_m_get_n_percent_off 时，系统会设置此属性。
free_gift_value	Price 可选。促销活动的赠品价值。
free_gift_description	string 可选。促销活动的赠品说明。
free_gift_item_id	string 可选。促销活动的赠品商品 ID。
promotion_effective_time_period	Interval 必需。TimePeriod 促销活动生效日期的表示法。此属性用于指定促销活动可在此时间段内在您的网店中进行测试。
promotion_display_time_period	Interval 可选。TimePeriod 表示促销的展示日期。此属性用于指定在 Google.com 和购物广告上投放促销活动的日期和时间范围。如果未指定促销展示时间段 promotion_display_time_period 属性，则促销有效时间段 promotion_effective_time_period 将决定在 Google.com 和购物广告上展示促销活动的日期和时间范围。
store_applicability	StoreApplicability 可选。促销活动是适用于所有商店还是仅适用于指定商店。如果未包含适用商店，本地商品目录广告促销活动会抛出错误。如果 store_applicability 设置为 ALL_STORES，并且 store_codes_inclusion 或 score_code_exclusion 设置为某个值，则会抛出 INVALID_ARGUMENT 错误。
store_codes_inclusion[]	string 可选。要包含的商店代码（适用于促销活动）。仅当 store_applicability 属性设置为 specific_stores 时，商店过滤条件属性才适用。 销售相应商品的实体店的商店代码（商家资料中的商店 ID）。如需了解详情，请参阅本地商品目录数据规范。
store_codes_exclusion[]	string 可选。要排除的促销活动所涵盖的商店代码。仅当 store_applicability 属性设置为 specific_stores 时，商店过滤条件属性才适用。
promotion_url	string 可选。指向商家网站上展示促销活动的网页的网址。如果未包含 promotion_url，本地商品目录广告促销活动会抛出错误。网址用于确认促销活动有效，支持兑换。

CouponValueType

促销活动的优惠券价值类型。

枚举
COUPON_VALUE_TYPE_UNSPECIFIED	表示未指定优惠券价值类型。
MONEY_OFF	现金返还优惠券价值类型。
PERCENT_OFF	折扣优惠券价值类型。
BUY_M_GET_N_MONEY_OFF	“买 M 件，立减 N 元”优惠券价值类型。minimum_purchase_quantity 和 get_this_quantity_discounted 必须存在。money_off_amount 也必须存在。
BUY_M_GET_N_PERCENT_OFF	“买 M 件，立享 N 折”优惠券价值类型。minimum_purchase_quantity 和 get_this_quantity_discounted 必须存在。percent_off_percentage 也必须存在。
BUY_M_GET_MONEY_OFF	买 M 件，立减现金。minimum_purchase_quantity 和 money_off_amount 必须存在。
BUY_M_GET_PERCENT_OFF	买 M 件，立减现金。minimum_purchase_quantity 和 percent_off_percentage 必须存在。
FREE_GIFT	仅包含说明的赠品。
FREE_GIFT_WITH_VALUE	具有货币价值的赠品。
FREE_GIFT_WITH_ITEM_ID	带商品 ID 的赠品。
FREE_SHIPPING_STANDARD	标准免运费优惠券价值类型。仅适用于线上促销活动。
FREE_SHIPPING_OVERNIGHT	次日达免运费优惠券价值类型。仅适用于线上促销活动。
FREE_SHIPPING_TWO_DAY	隔日达免运费优惠券价值类型。仅适用于线上促销活动。

GetPromotionRequest

对 GetPromotion 方法的请求消息。

字段
name	string 必需。要检索的促销活动的名称。格式：accounts/{account}/promotions/{promotions}

InsertPromotionRequest

对 InsertPromotion 方法的请求消息。

字段
parent	string 必需。要插入促销信息的账号。格式：accounts/{account}
promotion	Promotion 必需。要插入的促销活动。
data_source	string 必需。促销活动的数据源格式：accounts/{account}/dataSources/{datasource}。

ListPromotionsRequest

对 ListPromotions 方法的请求消息。

字段
parent	string 必需。要列出已处理的促销活动的账号。格式：accounts/{account}
page_size	int32 仅限输出。要返回的促销活动的最大数量。服务返回的值可能小于此值。最大值为 250；大于 250 的值将被强制转换为 250。如果未指定，则会返回最大促销活动数量。
page_token	string 仅限输出。从之前的 ListPromotions 调用接收的页面令牌。利用其进行后续页面检索。 进行分页时，提供给 ListPromotions 的所有其他参数必须与提供页面令牌的调用匹配。

ListPromotionsResponse

ListPromotions 方法的响应消息。

字段
promotions[]	Promotion 指定账号中已处理的促销活动。
next_page_token	string 可作为 page_token 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。

OfferType

促销优惠的类型。

枚举
OFFER_TYPE_UNSPECIFIED	优惠类型未知。
NO_CODE	无需代码即可享受的优惠类型。
GENERIC_CODE	包含代码的优惠类型。当 offerType = GENERIC_CODE 时，必须提供促销活动的通用兑换码。

ProductApplicability

促销活动适用于哪件商品或商品列表。

枚举
PRODUCT_APPLICABILITY_UNSPECIFIED	促销优惠适用于哪些商品未知。
ALL_PRODUCTS	适用于所有商品。
SPECIFIC_PRODUCTS	仅适用于单个商品或商品列表。

促销

表示促销活动。如需了解详情，请参阅以下文章。

以下是必须提供的促销活动输入属性，以通过数据验证检查：

• 促销活动数据规范
• 本地促销活动数据规范

插入或更新促销活动输入后，可能需要几分钟才能检索到最终的促销活动。

字段
name	string 标识符。促销活动的名称。格式：accounts/{account}/promotions/{promotion}
promotion_id	string 必需。用户提供的促销活动 ID，用于唯一标识促销活动。请遵循最低要求，以免促销活动遭拒。
content_language	string 必需。促销活动的双字母 ISO 639-1 语言代码。 促销活动仅适用于部分语言。
target_country	string 必需。目标国家/地区，用作唯一标识符的一部分。表示为 CLDR 地区代码。 促销活动仅适用于部分国家/地区，非付费商品详情和购物广告 本地商品目录广告
redemption_channel[]	RedemptionChannel 必需。促销活动的兑换渠道。至少需要一个渠道。
data_source	string 仅限输出。促销活动的主要数据源。
attributes	Attributes 可选。促销属性列表。
custom_attributes[]	CustomAttribute 可选。自定义（商家提供）属性的列表。它还可用于以通用形式（例如 { "name": "size type", "value": "regular" }）提交数据规范的任何属性。这对于提交 API 未明确公开的属性非常有用。
promotion_status	PromotionStatus 仅限输出。促销活动的状态、数据验证问题，即异步计算的促销活动相关信息。
version_number	int64 可选。表示促销活动的现有版本（新鲜度），可用于在同时进行多次更新时保留正确的顺序。 如果设置，当版本号低于现有促销活动的当前版本号时，系统会阻止插入。您可以使用当前的 version_number 执行重新插入（例如，在 30 天后刷新促销活动）。 如果操作被阻止，系统会抛出中止异常。

PromotionStatus

促销活动的状态。

字段
destination_statuses[]	DestinationStatus 仅限输出。促销活动的预期目标平台。
item_level_issues[]	ItemLevelIssue 仅限输出。与促销活动相关的问题列表。
creation_date	Timestamp 仅限输出。促销活动的创建日期，采用 ISO 8601 格式：日期、时间和偏移量，例如 2020-01-02T09:00:00+01:00 或 2020-01-02T09:00:00Z
last_update_date	Timestamp 仅限输出。促销活动状态的上次更新日期（采用 ISO 8601 格式）：日期、时间和偏移量，例如 2020-01-02T09:00:00+01:00 或 2020-01-02T09:00:00Z

DestinationStatus

指定目的地的状态。

字段
reporting_context	ReportingContextEnum 仅限输出。促销活动目标的名称。
status	State 仅限输出。指定目的地的状态。

州

促销活动的当前状态。

枚举
STATE_UNSPECIFIED	促销状态未知。
IN_REVIEW	促销活动正在审核中。
REJECTED	促销活动被拒登。
LIVE	促销活动已获批准并处于有效状态。
STOPPED	促销活动已由商家停止。
EXPIRED	促销活动已过期。
PENDING	促销活动未停止，并且所有审核均已获批，但生效日期在未来。

ItemLevelIssue

与促销活动相关的问题。

字段
code	string 仅限输出。问题的错误代码。
severity	Severity 仅限输出。此问题对推广活动的投放有何影响。
resolution	string 仅限输出。商家是否可以解决此问题。
attribute	string 仅限输出。属性的名称（如果此问题是由单个属性引发的）。
reporting_context	ReportingContextEnum 仅限输出。问题适用的目的地。
description	string 仅限输出。以英文编写的简短问题说明。
detail	string 仅限输出。以英文编写的详细问题说明。
documentation	string 仅限输出。帮助解决此问题的网页的网址。
applicable_countries[]	string 仅限输出。问题适用的国家/地区代码 (ISO 3166-1 alpha-2) 列表。

严重程度

问题的严重程度。

枚举
SEVERITY_UNSPECIFIED	未指定。
NOT_IMPACTED	此问题属于警告性质，不会直接影响促销活动。
DEMOTED	促销活动会被降级，在搜索结果中的效果很可能不佳
DISAPPROVED	拒批促销活动。

RedemptionChannel

促销活动的渠道。

枚举
REDEMPTION_CHANNEL_UNSPECIFIED	表示未指定渠道。
IN_STORE	表示频道在商店中。这与用于 products 的 local 通道相同。
ONLINE	表示频道处于在线状态。

StoreApplicability

促销活动适用的商店代码或商店代码列表。仅适用于本地商品目录广告促销活动。

枚举
STORE_APPLICABILITY_UNSPECIFIED	促销优惠适用于哪些商店代码未知。
ALL_STORES	促销活动适用于所有商店。
SPECIFIC_STORES	促销活动仅适用于指定的商店。