Package google.shopping.merchant.promotions.v1beta

索引

PromotionsService

管理產品促銷活動的服務。

GetPromotion

rpc GetPromotion(GetPromotionRequest) returns (Promotion)

從 Merchant Center 帳戶擷取促銷活動。

插入或更新促銷活動輸入內容後，可能需要幾分鐘才能擷取更新後的促銷活動。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/content

詳情請參閱 OAuth 2.0 Overview。
InsertPromotion

rpc InsertPromotion(InsertPromotionRequest) returns (Promotion)

為 Merchant Center 帳戶插入促銷活動。如果促銷活動已存在，則會改為更新促銷活動。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/content

詳情請參閱 OAuth 2.0 Overview。
ListPromotions

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

列出 Merchant Center 帳戶中的促銷活動。回應中包含的項目可能少於 pageSize 指定的項目數量。請依據 pageToken 判斷是否還有其他項目可要求。

插入或更新促銷活動後，可能需要幾分鐘的時間才能擷取已更新的已處理促銷活動。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/content

詳情請參閱 OAuth 2.0 Overview。

屬性

屬性。

欄位
product_applicability

ProductApplicability

必要欄位。促銷活動適用於所有產品，或是僅限特定產品。
offer_type

OfferType

必要欄位。促銷活動的類型。這項屬性可用來指明消費者是否需要優待券代碼才能兌換促銷優惠。
generic_redemption_code

string

選用設定。促銷活動的通用兌換代碼。如要與 offerType 欄位搭配使用，必須符合最低需求。
long_title

string

必要欄位。促銷活動的長標題。
coupon_value_type

CouponValueType

必要欄位。優待券值類型屬性，用於指出要進行的促銷活動類型。視所選優待券值的類型而定，部分屬性為必填屬性。
promotion_destinations[]

DestinationEnum

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

你先前可能提交過購物行動 (Shopping Actions)、Google 跨平台顯示 (Surfaces across Google)、本地 Google 跨平台顯示 (Local surfaces across Google) 這些值來當做產品目的地，如要表示這些值，請使用 FREE_LISTINGS、FREE_LOCAL_LISTINGS 和 LOCAL_INVENTORY_ADS。詳情請參閱「宣傳活動目的地」
item_id_inclusion[]

string

選用設定。依促銷活動的商品 ID 篩選產品。只有在符合促銷活動資格的產品，產品適用性 product_applicability 屬性設為 specific_products 時，產品篩選器屬性才會發揮作用。
brand_inclusion[]

string

選用設定。促銷活動的產品篩選器 (依品牌)。只有在符合促銷活動資格的產品，產品適用性 product_applicability 屬性設為 specific_products 時，產品篩選器屬性才會發揮作用。
item_group_id_inclusion[]

string

選用設定。依促銷活動的商品群組 ID 篩選產品。只有在符合促銷活動資格的產品，產品適用性 [product_applicability] 屬性設為 specific_products 時，產品篩選器屬性才會發揮作用。
product_type_inclusion[]

string

選用設定。依促銷活動的產品類型篩選產品。只有在符合促銷活動資格的產品，產品適用性 product_applicability 屬性設為 specific_products 時，產品篩選器屬性才會發揮作用。
item_id_exclusion[]

string

選用設定。依促銷活動的商品 ID 排除條件篩選產品。只有在符合促銷活動資格的產品，產品適用性 product_applicability 屬性設為 specific_products 時，產品篩選器屬性才會發揮作用。
brand_exclusion[]

string

選用設定。促銷活動的產品篩選器依據品牌排除條件。只有在符合促銷活動資格的產品，產品適用性 product_applicability 屬性設為 specific_products 時，產品篩選器屬性才會發揮作用。
item_group_id_exclusion[]

string

選用設定。依商品群組 ID篩選產品。只有在符合促銷活動資格的產品，產品適用性 product_applicability 屬性設為 specific_products 時，產品篩選器屬性才會發揮作用。
product_type_exclusion[]

string

選用設定。依促銷活動的產品類型排除條件篩選產品。只有在符合促銷活動資格的產品，產品適用性 product_applicability 屬性設為 specific_products 時，產品篩選器屬性才會發揮作用。
minimum_purchase_amount

Price

選用設定。促銷活動的最低消費金額。
minimum_purchase_quantity

int64

選用設定。促銷活動的最低購買數量。
limit_quantity

int64

選用設定。促銷活動的最高購買數量。
limit_value

Price

選用設定。促銷活動最高產品價格。
percent_off

int64

選用設定。促銷活動提供的折扣百分比。
money_off_amount

Price

選用設定。促銷活動提供的折扣金額。
get_this_quantity_discounted

int64

選用設定。促銷活動中折扣商品的數量。當 couponValueType 等於 buy_m_get_n_money_off 或 buy_m_get_n_percent_off 時，系統會設定這項屬性。
free_gift_value

Price

選用設定。促銷活動的贈禮價值。
free_gift_description

string

選用設定。促銷活動的免費贈禮說明。
free_gift_item_id

string

選用設定。促銷活動的免費贈禮項目 ID。
promotion_effective_time_period

Interval

必要欄位。TimePeriod 代表促銷活動的生效日期。這項屬性可用來指定促銷活動可在這個時間範圍內於網路商店進行測試。
promotion_display_time_period

Interval

選用設定。TimePeriod 代表促銷活動的顯示日期。這個屬性可指定促銷活動在 Google.com 和購物廣告上刊登的日期和時間範圍。如果未指定促銷活動顯示日期 promotion_display_time_period 屬性，系統將依據促銷活動有效日期 promotion_effective_time_period，決定促銷活動在 Google.com 和購物廣告上刊登的日期和時間範圍。
store_applicability

StoreApplicability

選用設定。促銷活動是否適用於所有商店，或僅限特定商店。如果未納入商店適用性，店面商品目錄廣告促銷活動就會發生錯誤。如果 store_applicability 設為 ALL_STORES，而 store_codes_inclusion 或 score_code_exclusion 設為值，系統就會擲回 INVALID_ARGUMENT 錯誤。
store_codes_inclusion[]

string

選用設定。要加入的代碼，用於促銷活動。只有在 store_applicability 屬性設為 specific_stores 時，商店篩選器屬性才會發揮作用。

產品銷售實體商店的商店代碼 (商家檔案中的商店 ID)。詳情請參閱店面商品目錄資料規格。
store_codes_exclusion[]

string

選用設定。要排除的商店代碼 (適用於促銷活動)。只有在 store_applicability 屬性設為 specific_stores 時，商店篩選器屬性才會發揮作用。
promotion_url

string

選用設定。指向商家網站上促銷活動顯示的網頁網址。如果未納入 promotion_url，店面商品目錄廣告促銷活動就會擲回錯誤。我們會使用這個連結來確認促銷活動是否有效且可供兌換。

CouponValueType

促銷活動的優待券值類型。

列舉
COUPON_VALUE_TYPE_UNSPECIFIED 表示未指定優待券值類型。
MONEY_OFF 折扣優待券值類型。
PERCENT_OFF 折扣優待券值類型。
BUY_M_GET_N_MONEY_OFF 購買 M 件商品，可折抵 N 元優待券值類型。必須提供 minimum_purchase_quantity 和 get_this_quantity_discounted。money_off_amount 也必須存在。
BUY_M_GET_N_PERCENT_OFF 購買 M 件商品，可享 N 折優待券折扣。必須提供 minimum_purchase_quantity 和 get_this_quantity_discounted。percent_off_percentage 也必須存在。
BUY_M_GET_MONEY_OFF 購買 m 項可折價。minimum_purchase_quantity 和 money_off_amount 必須存在。
BUY_M_GET_PERCENT_OFF 購買 m 項可折價。minimum_purchase_quantity 和 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 兩天到貨免運費優待券值類型。僅適用於線上促銷活動。

GetPromotionRequest

GetPromotion 方法的要求訊息。

欄位
name

string

必要欄位。要擷取的促銷活動名稱。格式：accounts/{account}/promotions/{promotions}

InsertPromotionRequest

InsertPromotion 方法的要求訊息。

欄位
parent

string

必要欄位。要插入促銷活動的帳戶。格式：accounts/{account}
promotion

Promotion

必要欄位。要插入的促銷活動。
data_source

string

必要欄位。促銷活動的資料來源格式：accounts/{account}/dataSources/{datasource}。

ListPromotionsRequest

ListPromotions 方法的要求訊息。

欄位
parent

string

必要欄位。要列出已處理促銷活動的帳戶。格式：accounts/{account}
page_size

int32

僅供輸出。要傳回的促銷活動數量上限。服務傳回的產品數量可能會少於這個值。許可的最大值為 250；超出的數值將一律指定為 250。如未指定，系統會傳回促銷活動的最大數量。
page_token

string

僅供輸出。從先前 ListPromotions 呼叫收到的網頁權杖。提供此項目即可擷取後續網頁。

進行分頁時，提供至 ListPromotions 的所有其他參數須與提供網頁權杖的呼叫相符。

ListPromotionsResponse

ListPromotions 方法的回應訊息。

欄位
promotions[]

Promotion

指定帳戶中已處理的促銷活動。
next_page_token

string

可做為 page_token 傳送的權杖，用於擷取後續網頁。如果省略這個欄位，就不會有後續頁面。

OfferType

促銷活動的優惠類型。

列舉
OFFER_TYPE_UNSPECIFIED 不明的優惠類型。
NO_CODE 不含代碼的優惠類型。
GENERIC_CODE 含有代碼的優惠類型。當 offerType = GENERIC_CODE 時，必須提供促銷活動的通用兌換代碼。

ProductApplicability

促銷活動適用的產品或產品清單。

列舉
PRODUCT_APPLICABILITY_UNSPECIFIED 促銷活動適用的產品不明。
ALL_PRODUCTS 適用於所有產品。
SPECIFIC_PRODUCTS 僅適用於單一產品或產品清單。

宣傳

代表促銷活動。如需詳細資訊，請參閱以下文章。

以下主要定義了促銷活動輸入屬性，可讓系統通過資料驗證檢查：

插入或更新促銷活動輸入內容後，可能需要幾分鐘才能擷取最終促銷活動。

欄位
name

string

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

string

必要欄位。使用者提供的促銷活動 ID 可用於識別促銷活動。請遵守最低規定，避免促銷活動遭拒登。
content_language

string

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

促銷活動僅適用於特定語言。
target_country

string

必要欄位。用於唯一識別碼的目標國家/地區。以 CLDR 地域代碼表示。

促銷活動僅適用於特定國家/地區、免費產品資訊和購物廣告 店面商品目錄廣告
redemption_channel[]

RedemptionChannel

必要欄位。促銷活動的兌換管道。必須提供至少一個管道。
data_source

string

僅供輸出。促銷活動的主要資料來源。
attributes

Attributes

選用設定。促銷活動屬性清單。
custom_attributes[]

CustomAttribute

選用設定。自訂 (商家提供) 屬性清單。也可以用來以泛型形式 (例如 { "name": "size type", "value": "regular" }) 提交資料規格的任何屬性。這對於提交 API 未明確公開的屬性相當實用。
promotion_status

PromotionStatus

僅供輸出。促銷活動狀態、資料驗證問題，也就是非同步計算的促銷活動資訊。
version_number

int64

選用設定。代表促銷活動的現有版本 (新鮮度)，可用於在同時進行多項更新時，保留正確的順序。

如果已設定，當版本號碼低於現有促銷活動的目前版本號碼時，就會防止插入。您可以使用目前的 version_number 執行重新插入作業 (例如在 30 天後重新發布宣傳活動)。

如果作業遭到阻止，系統會擲回中止例外狀況。

PromotionStatus

促銷活動的狀態。

欄位
destination_statuses[]

DestinationStatus

僅供輸出。促銷活動的預定目的地。
item_level_issues[]

ItemLevelIssue

僅供輸出。與促銷活動相關的問題清單。
creation_date

Timestamp

僅供輸出。以 ISO 8601 格式表示的促銷活動建立日期：日期、時間和偏移量，例如 2020-01-02T09:00:00+01:00 或 2020-01-02T09:00:00Z
last_update_date

Timestamp

僅供輸出。促銷活動狀態上次更新的日期，採 ISO 8601 格式：日期、時間和偏移量，例如 2020-01-02T09:00:00+01:00 或 2020-01-02T09:00:00Z

DestinationStatus

指定目的地的狀態。

欄位
reporting_context

ReportingContextEnum

僅供輸出。促銷活動目的地的名稱。
status

State

僅供輸出。指定目的地的狀態。

州

促銷活動的目前狀態。

列舉
STATE_UNSPECIFIED 不明的促銷活動狀態。
IN_REVIEW 促銷活動正在審核中。
REJECTED 促銷活動已遭拒登。
LIVE 促銷活動已通過核准並生效。
STOPPED 商家已停止促銷活動。
EXPIRED 這項促銷活動已無效。
PENDING 促銷活動並未停止，且所有審查都已核准，但有效日期尚未到來。

ItemLevelIssue

促銷活動相關問題。

欄位
code

string

僅供輸出。問題的錯誤代碼。
severity

Severity

僅供輸出。這個問題對促銷活動的影響程度。
resolution

string

僅供輸出。商家是否可解決這個問題。
attribute

string

僅供輸出。屬性名稱 (如果問題是因單一屬性造成)。
reporting_context

ReportingContextEnum

僅供輸出。問題適用的目的地。
description

string

僅供輸出。問題的簡短英文說明。
detail

string

僅供輸出。問題的詳細英文說明。
documentation

string

僅供輸出。協助解決問題的說明網頁網址。
applicable_countries[]

string

僅供輸出。適用於商品的國家/地區代碼 (ISO 3166-1 alpha-2) 清單。

嚴重性

問題的嚴重程度。

列舉
SEVERITY_UNSPECIFIED 不指定。
NOT_IMPACTED 這個問題代表警告，不會對促銷活動造成直接影響。
DEMOTED 促銷活動會降級，在搜尋結果中的成效也可能會受到限制
DISAPPROVED 問題導致促銷活動遭拒登。

RedemptionChannel

促銷活動的管道。

列舉
REDEMPTION_CHANNEL_UNSPECIFIED 表示未指定管道。
IN_STORE 表示頻道已上架。這與 products 使用的 local 管道相同。
ONLINE 表示頻道已上線。

StoreApplicability

促銷活動適用的商店代碼或商店代碼清單。僅適用於店面商品目錄廣告宣傳活動。

列舉
STORE_APPLICABILITY_UNSPECIFIED 促銷活動適用的商店代碼不明。
ALL_STORES 促銷活動適用於所有商店。
SPECIFIC_STORES 促銷活動僅適用於指定商店。