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

必要欄位。用於唯一識別碼的目標國家/地區。以 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)

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

你先前可能提交過購物行動 (Shopping Actions)、Google 跨平台顯示 (Surfaces across Google)、本地 Google 跨平台顯示 (Local surfaces across 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 多媒體廣告。
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 Retail。

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 帳戶中的促銷活動。