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