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

ID。促銷活動名稱。格式：accounts/{account}/promotions/{promotion}
promotionId

string

必要欄位。使用者提供的促銷 ID，用於識別該促銷活動。請遵守基本規定，以免促銷活動遭到拒登。
contentLanguage

string

必要欄位。雙字母格式的促銷活動 ISO 639-1 語言代碼。

促銷活動僅適用於部分語言。
targetCountry

string

必要欄位。專屬 ID 中所用的指定國家/地區。以 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)

必要欄位。優待券值類型屬性可用於指出正在進行的促銷活動類型。視選取的優待券價值類型而定，部分屬性為必填項目。
promotionDestinations[]

enum (DestinationEnum)

必要欄位。促銷活動適用的目的地清單。如果未在資料來源中加入支援的值來指定目的地，促銷活動會依預設顯示在購物廣告和免費產品資訊中。

你先前可能提交過購物行動、Google 跨平台顯示、本地 Google 跨平台顯示等值做為產品目的地。如要表示這些值，請使用 FREE_LISTINGS、FREE_LOCAL_LISTINGS、LOCAL_INVENTORY_ADS。詳情請參閱「促銷活動目的地」
itemIdInclusion[]

string

選用設定。依促銷活動項目 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 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 帳戶中列出促銷活動。