REST Resource: accounts.promotions

资源：促销

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

为了通过数据验证检查，必须填写的促销输入属性主要定义如下：

插入并更新促销活动输入内容后，系统可能需要几分钟时间才能检索到最终的促销活动。

JSON 表示法 
{
  "name": string,
  "promotionId": string,
  "contentLanguage": string,
  "targetCountry": string,
  "redemptionChannel": [
    enum (RedemptionChannel)
  ],
  "dataSource": string,
  "attributes": {
    object (Attributes)
  },
  "customAttributes": [
    {
      object (CustomAttribute)
    }
  ],
  "promotionStatus": {
    object (PromotionStatus)
  },
  "versionNumber": string
}
字段
name

string

标识符。促销活动的名称。格式：accounts/{account}/promotions/{promotion}
promotionId

string

必需。用户提供的促销 ID，用于唯一标识相应促销活动。遵循最低要求，防止促销活动遭到拒批。
contentLanguage

string

必需。促销活动的双字母 ISO 639-1 语言代码。

促销活动仅适用于部分语言。
targetCountry

string

必需。用作唯一标识符一部分的目标国家/地区。以 CLDR 地区代码表示。

促销活动仅在部分国家/地区提供，非付费商品详情和购物广告 本地产品目录广告
redemptionChannel[]

enum (RedemptionChannel)

必需。促销活动的兑换渠道。至少需要一个渠道。
dataSource

string

仅限输出。促销活动的主要数据源。
attributes

object (Attributes)

可选。促销活动属性列表。
customAttributes[]

object (CustomAttribute)

可选。自定义（商家提供的）属性列表。它还可用于以通用形式提交数据规范中的任何属性（例如，{ "name": "size type", "value": "regular" }）。这对于提交 API 未明确提供的属性非常有用。
promotionStatus

object (PromotionStatus)

仅限输出。促销活动的状态、数据验证问题，即异步计算的促销活动的相关信息。
versionNumber

string (int64 format)

可选。表示促销活动的现有版本（新鲜度），可用于在同时进行多项更新时保持正确的顺序。

设置后，当版本号低于现有促销活动的当前版本号时，系统会阻止插入。您可以使用当前的 versionNumber 重新插入（例如，在 30 天后刷新促销活动）。

如果操作被阻止，则会抛出已中止的异常。

RedemptionChannel

推广活动的渠道。

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

属性

属性。

JSON 表示法 
{
  "productApplicability": enum (ProductApplicability),
  "offerType": enum (OfferType),
  "genericRedemptionCode": string,
  "longTitle": string,
  "couponValueType": enum (CouponValueType),
  "promotionDestinations": [
    enum (DestinationEnum)
  ],
  "itemIdInclusion": [
    string
  ],
  "brandInclusion": [
    string
  ],
  "itemGroupIdInclusion": [
    string
  ],
  "productTypeInclusion": [
    string
  ],
  "itemIdExclusion": [
    string
  ],
  "brandExclusion": [
    string
  ],
  "itemGroupIdExclusion": [
    string
  ],
  "productTypeExclusion": [
    string
  ],
  "minimumPurchaseAmount": {
    object (Price)
  },
  "minimumPurchaseQuantity": string,
  "limitQuantity": string,
  "limitValue": {
    object (Price)
  },
  "percentOff": string,
  "moneyOffAmount": {
    object (Price)
  },
  "getThisQuantityDiscounted": string,
  "freeGiftValue": {
    object (Price)
  },
  "freeGiftDescription": string,
  "freeGiftItemId": string,
  "promotionEffectiveTimePeriod": {
    object (Interval)
  },
  "promotionDisplayTimePeriod": {
    object (Interval)
  },
  "storeApplicability": enum (StoreApplicability),
  "storeCodesInclusion": [
    string
  ],
  "storeCodesExclusion": [
    string
  ],
  "promotionUrl": string
}
字段
productApplicability

enum (ProductApplicability)

必需。促销活动是否适用于所有商品或仅适用于指定商品。
offerType

enum (OfferType)

必需。促销活动的类型。使用此属性可指明客户是否需要优惠券代码来兑换您的促销优惠。
genericRedemptionCode

string

可选。促销活动的通用兑换码。要与 offerType 字段搭配使用，且必须满足最低要求。
longTitle

string

必需。促销活动的长标题。
couponValueType

enum (CouponValueType)

必需。coupon value type 属性，用于指明您开展的促销活动的类型。根据所选优惠券值的类型，某些属性是必需属性。
promotionDestinations[]

enum (DestinationEnum)

必需。促销活动适用的目标平台的列表。如果您未通过在数据源中添加受支持的值来指定目标平台，则默认情况下，您的促销活动将在购物广告和非付费商品详情中展示。

您以前可能提交了以下值作为商品展示平台：购物行动计划、Google 跨平台呈现、本地 Google 平台呈现。如需表示这些值，请使用 FREE_LISTINGS、FREE_LOCAL_LISTINGS 和 LOCAL_INVENTORY_ADS。如需了解详情，请参阅促销平台
itemIdInclusion[]

string

可选。按促销活动的 item ID 过滤商品。仅当符合促销条件的商品 productApplicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
brandInclusion[]

string

可选。按品牌过滤促销活动的商品。仅当符合促销条件的商品 productApplicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
itemGroupIdInclusion[]

string

可选。按促销活动的商品组 ID 过滤商品。仅当符合促销条件的商品 [productApplicability] 属性设置为 specific_products 时，商品过滤条件属性才适用。
productTypeInclusion[]

string

可选。按促销活动的商品类型过滤商品。仅当符合促销条件的商品 productApplicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
itemIdExclusion[]

string

可选。按促销活动的商品 ID 排除过滤商品。仅当符合促销条件的商品 productApplicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
brandExclusion[]

string

可选。按促销活动的品牌排除过滤商品。仅当符合促销条件的商品 productApplicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
itemGroupIdExclusion[]

string

可选。按 item group ID 过滤商品。仅当符合促销条件的商品的适用商品 productApplicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
productTypeExclusion[]

string

可选。按促销活动的产品类型排除过滤产品。仅当符合促销条件的商品 productApplicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
minimumPurchaseAmount

object (Price)

可选。促销活动的最低交易额。
minimumPurchaseQuantity

string (int64 format)

可选。促销活动的最低购买数量。
limitQuantity

string (int64 format)

可选。促销活动的购买数量上限。
limitValue

object (Price)

可选。促销活动的最高商品价格。
percentOff

string (int64 format)

可选。促销活动中提供的百分比折扣。
moneyOffAmount

object (Price)

可选。促销活动中提供的折扣金额。
getThisQuantityDiscounted

string (int64 format)

可选。促销活动中打折的商品数量。当 couponValueType 等于 buy_m_get_n_money_off 或 buy_m_get_n_percent_off 时，系统会设置此属性。
freeGiftValue

object (Price)

可选。促销活动的赠品价值。
freeGiftDescription

string

可选。促销活动的赠品说明。
freeGiftItemId

string

可选。促销活动的赠品商品 ID。
promotionEffectiveTimePeriod

object (Interval)

必需。TimePeriod，表示促销活动的生效日期。此属性指定在此期间可以在您的网店中测试促销活动。
promotionDisplayTimePeriod

object (Interval)

可选。TimePeriod 表示促销活动展示日期。此属性用于指定在 Google.com 和购物广告上投放促销活动的日期和时间范围。如果未指定促销展示时间段 promotionDisplayTimePeriod 属性，则促销活动有效期 promotionEffectiveTimePeriod 将决定在 Google.com 和购物广告上投放促销活动的日期和时间范围。
storeApplicability

enum (StoreApplicability)

可选。促销活动适用于所有商店，还是仅适用于指定的商店。如果没有添加商店适用性信息，本地产品目录广告促销活动会抛出错误。如果 storeApplicability 设置为 ALL_STORES 且 storeCodesInclusion 或 score_code_exclusion 设置为一个值，则会抛出 INVALID_ARGUMENT 错误。
storeCodesInclusion[]

string

可选。要为促销活动添加的商店代码。商店过滤条件属性仅在 storeApplicability 属性设置为 specific_stores 时适用。

销售商品的实体店的商店代码（即您的商家资料中的商店 ID）。如需了解详情，请参阅本地商品目录数据规范。
storeCodesExclusion[]

string

可选。要为促销活动排除的商店代码。商店过滤条件属性仅在 storeApplicability 属性设置为 specific_stores 时适用。
promotionUrl

string

可选。指向商家网站上显示促销活动的网页的网址。如果未添加 promotionUrl，本地产品目录广告促销活动会抛出错误。网址用于确认促销活动有效且可以兑换。

ProductApplicability

促销活动适用的商品或商品列表。

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

OfferType

促销活动的优惠类型。

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

CouponValueType

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

枚举
COUPON_VALUE_TYPE_UNSPECIFIED 表示未指定优惠券值类型。
MONEY_OFF 折扣优惠券价值类型。
PERCENT_OFF 折扣优惠券价值类型。
BUY_M_GET_N_MONEY_OFF 优惠券价值类型是买 M 件，立减 N 笔。必须存在 minimumPurchaseQuantity 和 getThisQuantityDiscounted。moneyOffAmount。
BUY_M_GET_N_PERCENT_OFF 购买 M 件，立减 N% 的优惠券价值类型。必须存在 minimumPurchaseQuantity 和 getThisQuantityDiscounted。percent_off_percentage。
BUY_M_GET_MONEY_OFF 购 M 件，享优惠。必须有 minimumPurchaseQuantity 和 moneyOffAmount。
BUY_M_GET_PERCENT_OFF 购 M 件，享优惠。必须有 minimumPurchaseQuantity 和 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 两日免费配送优惠券值类型。

DestinationEnum

目标值。

枚举
DESTINATION_ENUM_UNSPECIFIED 未指定。
SHOPPING_ADS 购物广告。
DISPLAY_ADS 展示广告。
LOCAL_INVENTORY_ADS 本地产品目录广告。
FREE_LISTINGS 非付费商品详情。
FREE_LOCAL_LISTINGS 非付费本地商品详情。
YOUTUBE_SHOPPING YouTube Shopping。

StoreApplicability

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

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

PromotionStatus

促销活动的状态。

JSON 表示法 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
字段
destinationStatuses[]

object (DestinationStatus)

仅限输出。促销活动的目标平台。
itemLevelIssues[]

object (ItemLevelIssue)

仅限输出。与促销活动相关的问题列表。
creationDate

string (Timestamp format)

仅限输出。促销活动的创建日期（采用 ISO 8601 格式）：日期、时间和偏移值，例如 2020-01-02T09:00:00+01:00 或 2020-01-02T09:00:00Z
lastUpdateDate

string (Timestamp format)

仅限输出。促销状态的上次更新日期（ISO 8601 格式）：日期、时间和偏移值，例如 2020-01-02T09:00:00+01:00 或 2020-01-02T09:00:00Z

DestinationStatus

指定目标的状态。

JSON 表示法 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
字段
reportingContext

enum (ReportingContextEnum)

仅限输出。促销平台的名称。
status

enum (State)

仅限输出。指定目标的状态。

状态

促销活动的当前状态。

枚举
STATE_UNSPECIFIED 促销活动状态未知。
IN_REVIEW 促销活动正在审核中。
REJECTED 促销活动未获批准。
LIVE 促销活动已获批准并处于有效状态。
STOPPED 商家停止了促销活动。
EXPIRED 促销活动已失效。
PENDING 促销活动并未停止，并且所有审核都已获得批准，但生效日期是未来的日期。

ItemLevelIssue

与促销活动相关的问题。

JSON 表示法 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
字段
code

string

仅限输出。问题的错误代码。
severity

enum (Severity)

仅限输出。此问题对促销活动的投放有何影响。
resolution

string

仅限输出。商家能否解决问题。
attribute

string

仅限输出。属性的名称（如果问题是由单个属性导致的）。
reportingContext

enum (ReportingContextEnum)

仅限输出。问题适用的目标位置。
description

string

仅限输出。英文的简短问题说明。
detail

string

仅限输出。详细的问题说明（英文）。
documentation

string

仅限输出。帮助解决此问题的网页的网址。
applicableCountries[]

string

仅限输出。商品存在问题的国家/地区代码列表 (ISO 3166-1 alpha-2)。

严重级别

问题的严重程度。

枚举
SEVERITY_UNSPECIFIED 未指定。
NOT_IMPACTED 此问题只是一个警告，不会对促销活动产生直接影响。
DEMOTED 相应促销活动已降位，在搜索结果中的效果很可能会受到限制
DISAPPROVED 问题拒批了促销活动。

方法

get

 从您的 Merchant Center 帐号中检索促销活动。

insert

 为您的 Merchant Center 帐号插入促销活动。

list

 列出您的 Merchant Center 帐号中的促销活动。