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

可选。按商品组 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。
YOUTUBE_SHOPPING_CHECKOUT YouTube Shopping 结账。
YOUTUBE_AFFILIATE YouTube 联属营销。
FREE_VEHICLE_LISTINGS 非付费车辆详情。
VEHICLE_ADS 车辆广告。
CLOUD_RETAIL Cloud Retail。
LOCAL_CLOUD_RETAIL 本地 Cloud 零售。

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 账号中的促销活动。