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 總覽。
InsertPromotion

rpc InsertPromotion(InsertPromotionRequest) returns (Promotion)

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

授權範圍

需要下列 OAuth 範圍：

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

詳情請參閱 OAuth 2.0 總覽。
ListPromotions

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

在 Merchant Center 帳戶中列出促銷活動。回應包含的項目可能少於 pageSize 的指定數量。仰賴 pageToken 判斷是否有更多項目需要提供。

插入或更新促銷活動之後，系統可能需要幾分鐘才能擷取更新後的促銷活動。

授權範圍

需要下列 OAuth 範圍：

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

詳情請參閱 OAuth 2.0 總覽。

屬性

屬性。

欄位
product_applicability

ProductApplicability

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

OfferType

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

string

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

string

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

CouponValueType

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

DestinationEnum

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

你先前可能提交過購物行動、Google 跨平台顯示、本地 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

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

必要欄位。專屬 ID 中所用的指定國家/地區。以 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 促銷活動僅適用於指定的商店。