Package google.shopping.merchant.promotions.v1beta

Chỉ mục

PromotionsService

Dịch vụ quản lý chương trình khuyến mãi cho sản phẩm.

GetPromotion

rpc GetPromotion(GetPromotionRequest) returns (Promotion)

Truy xuất chương trình khuyến mãi từ tài khoản Merchant Center của bạn.

Sau khi chèn hoặc cập nhật thông tin về chương trình khuyến mãi, có thể mất vài phút để hệ thống lấy được chương trình khuyến mãi đã cập nhật.

Phạm vi uỷ quyền

Yêu cầu phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về OAuth 2.0.
InsertPromotion

rpc InsertPromotion(InsertPromotionRequest) returns (Promotion)

Chèn chương trình khuyến mãi cho tài khoản Merchant Center. Nếu đã tồn tại thì chương trình khuyến mãi sẽ được cập nhật.

Phạm vi uỷ quyền

Yêu cầu phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về OAuth 2.0.
ListPromotions

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

Liệt kê các chương trình khuyến mãi trong tài khoản Merchant Center của bạn. Phản hồi có thể chứa ít mục hơn so với chỉ định của pageSize. Dựa vào pageToken để xác định xem có mục nào khác cần được yêu cầu hay không.

Sau khi chèn hoặc cập nhật chương trình khuyến mãi, có thể mất vài phút để truy xuất chương trình khuyến mãi đã xử lý đã cập nhật.

Phạm vi uỷ quyền

Yêu cầu phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về OAuth 2.0.

Thuộc tính

Thuộc tính.

Trường
product_applicability

ProductApplicability

Bắt buộc. Phạm vi áp dụng chương trình khuyến mãi cho tất cả sản phẩm hoặc chỉ một số sản phẩm.
offer_type

OfferType

Bắt buộc. Loại khuyến mãi. Sử dụng thuộc tính này để cho biết liệu khách hàng có cần mã giảm giá để sử dụng chương trình khuyến mãi của bạn hay không.
generic_redemption_code

string

Không bắt buộc. Mã sử dụng ưu đãi chung cho chương trình khuyến mãi. Để sử dụng với trường offerType và phải đáp ứng các yêu cầu tối thiểu.
long_title

string

Bắt buộc. Tiêu đề dài của chương trình khuyến mãi.
coupon_value_type

CouponValueType

Bắt buộc. Thuộc tính loại giá trị phiếu giảm giá để cho biết loại chương trình khuyến mãi mà bạn đang chạy. Tuỳ thuộc vào loại giá trị của phiếu giảm giá đã chọn, bạn phải có một số thuộc tính.
promotion_destinations[]

DestinationEnum

Bắt buộc. Danh sách các điểm đến áp dụng chương trình khuyến mãi. Nếu bạn không chỉ định nền tảng bằng cách thêm giá trị được hỗ trợ vào nguồn dữ liệu, thì theo mặc định, chương trình khuyến mãi sẽ xuất hiện trong quảng cáo Mua sắm và trang thông tin miễn phí.

Trước đây, có thể bạn đã gửi các giá trị sau làm vị trí xuất hiện cho sản phẩm của mình: Mua sắm Trực tiếp, Các nền tảng của Google, Các nền tảng của Google tại địa phương. Để biểu thị các giá trị này, hãy sử dụng FREE_LISTINGS, FREE_LOCAL_LISTINGS, LOCAL_INVENTORY_ADS. Để biết thêm thông tin, hãy xem bài viết Trang đích khuyến mãi
item_id_inclusion[]

string

Không bắt buộc. Lọc sản phẩm theo mã mặt hàng để được hưởng chương trình khuyến mãi. Thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt thuộc tính product_applicability của sản phẩm đủ điều kiện được khuyến mãi cho sản phẩm áp dụng khuyến mãi thành specific_products.
brand_inclusion[]

string

Không bắt buộc. Bộ lọc sản phẩm theo thương hiệu cho chương trình khuyến mãi. Thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt thuộc tính product_applicability của sản phẩm đủ điều kiện được khuyến mãi cho sản phẩm áp dụng khuyến mãi thành specific_products.
item_group_id_inclusion[]

string

Không bắt buộc. Lọc sản phẩm theo mã nhóm mặt hàng cho chương trình khuyến mãi. Thuộc tính bộ lọc sản phẩm chỉ áp dụng khi thuộc tính sản phẩm đủ điều kiện được khuyến mãi cho sản phẩm áp dụng khuyến mãi [product_applicability] được đặt thành specific_products.
product_type_inclusion[]

string

Không bắt buộc. Lọc sản phẩm theo loại sản phẩm được khuyến mãi. Thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt thuộc tính product_applicability của sản phẩm đủ điều kiện được khuyến mãi cho sản phẩm áp dụng khuyến mãi thành specific_products.
item_id_exclusion[]

string

Không bắt buộc. Lọc sản phẩm theo tiêu chí loại trừ mã mặt hàng cho chương trình khuyến mãi. Thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt thuộc tính product_applicability của sản phẩm đủ điều kiện được khuyến mãi cho sản phẩm áp dụng khuyến mãi thành specific_products.
brand_exclusion[]

string

Không bắt buộc. Lọc sản phẩm theo tiêu chí loại trừ thương hiệu cho chương trình khuyến mãi. Thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt thuộc tính product_applicability của sản phẩm đủ điều kiện được khuyến mãi cho sản phẩm áp dụng khuyến mãi thành specific_products.
item_group_id_exclusion[]

string

Không bắt buộc. Lọc sản phẩm theo mã nhóm mặt hàng. Thuộc tính bộ lọc sản phẩm chỉ áp dụng khi thuộc tính product_applicability của sản phẩm đủ điều kiện được khuyến mãi cho sản phẩm áp dụng khuyến mãi được đặt thành tiêu chí loại trừ cho chương trình khuyến mãi là specific_products.
product_type_exclusion[]

string

Không bắt buộc. Lọc sản phẩm theo tiêu chí loại trừ loại sản phẩm cho chương trình khuyến mãi. Thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt thuộc tính product_applicability của sản phẩm đủ điều kiện được khuyến mãi cho sản phẩm áp dụng khuyến mãi thành specific_products.
minimum_purchase_amount

Price

Không bắt buộc. Số tiền mua hàng tối thiểu để được hưởng chương trình khuyến mãi.
minimum_purchase_quantity

int64

Không bắt buộc. Số lượng hàng tối thiểu phải mua để được hưởng chương trình khuyến mãi.
limit_quantity

int64

Không bắt buộc. Số lượng hàng tối đa được phép mua cho chương trình khuyến mãi.
limit_value

Price

Không bắt buộc. Giá tối đa của sản phẩm cho chương trình khuyến mãi.
percent_off

int64

Không bắt buộc. Phần trăm chiết khấu được cung cấp trong chương trình khuyến mãi.
money_off_amount

Price

Không bắt buộc. Số tiền giảm giá được cung cấp trong chương trình khuyến mãi.
get_this_quantity_discounted

int64

Không bắt buộc. Số lượng mặt hàng được giảm giá trong chương trình khuyến mãi. Thuộc tính này được đặt khi couponValueType bằng buy_m_get_n_money_off hoặc buy_m_get_n_percent_off.
free_gift_value

Price

Không bắt buộc. Giá trị quà tặng miễn phí cho chương trình khuyến mãi.
free_gift_description

string

Không bắt buộc. Nội dung mô tả quà tặng miễn phí cho chương trình khuyến mãi.
free_gift_item_id

string

Không bắt buộc. Mã mặt hàng của quà tặng cho chương trình khuyến mãi.
promotion_effective_time_period

Interval

Bắt buộc. TimePeriod cho biết ngày khuyến mãi có hiệu lực. Thuộc tính này quy định rằng bạn có thể kiểm tra chương trình khuyến mãi trên cửa hàng trực tuyến của mình trong khoảng thời gian này.
promotion_display_time_period

Interval

Không bắt buộc. TimePeriod biểu thị ngày giới thiệu chương trình khuyến mãi. Thuộc tính này quy định ngày và giờ mà chương trình khuyến mãi sẽ xuất hiện trên Google.com và quảng cáo Mua sắm. Nếu bạn không chỉ định thuộc tính thời gian hiển thị chương trình khuyến mãi promotion_display_time_period, thì khoảng thời gian có hiệu lực của chương trình khuyến mãi promotion_effective_time_period sẽ xác định ngày và khung giờ mà chương trình khuyến mãi sẽ xuất hiện trên Google.com và quảng cáo Mua sắm.
store_applicability

StoreApplicability

Không bắt buộc. Liệu chương trình khuyến mãi áp dụng cho tất cả cửa hàng hay chỉ một số cửa hàng. Chương trình khuyến mãi Quảng cáo kho hàng tại địa phương sẽ báo lỗi nếu không thuộc phạm vi áp dụng của cửa hàng. Hệ thống sẽ gửi lỗi INVALID_ARGUMENT nếu bạn đặt store_applicability thành ALL_STORES và store_codes_inclusion hoặc score_code_exclusion được đặt thành một giá trị.
store_codes_inclusion[]

string

Không bắt buộc. Mã cửa hàng cần đưa vào chương trình khuyến mãi. Thuộc tính bộ lọc cửa hàng chỉ áp dụng khi thuộc tính store_applicability được đặt thành specific_stores.

Mã cửa hàng (mã cửa hàng trong Trang doanh nghiệp của bạn) của cửa hàng thực tế bán sản phẩm. Vui lòng xem Quy cách dữ liệu kho hàng tại địa phương để biết thêm thông tin.
store_codes_exclusion[]

string

Không bắt buộc. Mã cửa hàng cần loại trừ khỏi chương trình khuyến mãi. Thuộc tính bộ lọc cửa hàng chỉ áp dụng khi thuộc tính store_applicability được đặt thành specific_stores.
promotion_url

string

Không bắt buộc. URL dẫn đến trang trên trang web của người bán nơi hiển thị chương trình khuyến mãi. Chương trình khuyến mãi Quảng cáo kho hàng tại địa phương sẽ báo lỗi nếu không có promotion_url. URL dùng để xác nhận rằng chương trình khuyến mãi là hợp lệ và có thể sử dụng.

CouponValueType

Loại giá trị của phiếu giảm giá của một chương trình khuyến mãi.

Enum
COUPON_VALUE_TYPE_UNSPECIFIED Cho biết rằng bạn chưa xác định loại giá trị của phiếu giảm giá.
MONEY_OFF Loại giá trị của phiếu giảm giá.
PERCENT_OFF Loại giá trị phần trăm giảm giá.
BUY_M_GET_N_MONEY_OFF Mua số lượng M, được giảm N tiền cho loại giá trị của phiếu giảm giá. Phải có minimum_purchase_quantity và get_this_quantity_discounted. Bạn cũng phải có money_off_amount.
BUY_M_GET_N_PERCENT_OFF Khi mua số lượng M, được giảm N phần trăm theo loại giá trị của phiếu giảm giá. Phải có minimum_purchase_quantity và get_this_quantity_discounted. Bạn cũng phải có percent_off_percentage.
BUY_M_GET_MONEY_OFF Mua số lượng M, được giảm tiền. Phải có minimum_purchase_quantity và money_off_amount.
BUY_M_GET_PERCENT_OFF Mua số lượng M, được giảm tiền. Phải có minimum_purchase_quantity và percent_off_percentage.
FREE_GIFT Quà tặng miễn phí chỉ có nội dung mô tả.
FREE_GIFT_WITH_VALUE Quà tặng miễn phí có giá trị bằng tiền.
FREE_GIFT_WITH_ITEM_ID Quà tặng miễn phí có mã mặt hàng.
FREE_SHIPPING_STANDARD Loại giá trị của phiếu giảm giá cho ưu đãi miễn phí vận chuyển tiêu chuẩn.
FREE_SHIPPING_OVERNIGHT Loại giá trị của phiếu giảm giá vận chuyển miễn phí qua đêm.
FREE_SHIPPING_TWO_DAY Loại giá trị của phiếu giảm giá vận chuyển miễn phí trong 2 ngày.

GetPromotionRequest

Thông báo yêu cầu cho phương thức GetPromotion.

Trường
name

string

Bắt buộc. Tên chương trình khuyến mãi cần truy xuất. Định dạng accounts/{account}/promotions/{promotions}

InsertPromotionRequest

Thông báo yêu cầu cho phương thức InsertPromotion.

Trường
parent

string

Bắt buộc. Tài khoản sẽ chèn chương trình khuyến mãi. Định dạng: accounts/{account}
promotion

Promotion

Bắt buộc. Chương trình khuyến mãi cần chèn.
data_source

string

Bắt buộc. Nguồn dữ liệu của Định dạng khuyến mãi: accounts/{account}/dataSources/{datasource}.

ListPromotionsRequest

Thông báo yêu cầu cho phương thức ListPromotions.

Trường
parent

string

Bắt buộc. Tài khoản để liệt kê các chương trình khuyến mãi được xử lý. Định dạng accounts/{account}
page_size

int32

Chỉ có đầu ra. Số lượng chương trình khuyến mãi tối đa có thể trả lại. Dịch vụ có thể trả về ít hơn giá trị này. Giá trị lớn nhất là 1000; các giá trị lớn hơn 1000 sẽ bị buộc thành 1000. Nếu bạn không chỉ định, hệ thống sẽ trả về số lượng chương trình khuyến mãi tối đa.
page_token

string

Chỉ có đầu ra. Mã thông báo trang, nhận được từ lệnh gọi ListPromotions trước đó. Cung cấp mã này để truy xuất trang tiếp theo.

Khi phân trang, tất cả các tham số khác được cung cấp cho ListPromotions phải khớp với lệnh gọi đã cung cấp mã thông báo trang.

ListPromotionsResponse

Thông báo phản hồi cho phương thức ListPromotions.

Trường
promotions[]

Promotion

Chương trình khuyến mãi được xử lý từ tài khoản được chỉ định.
next_page_token

string

Mã thông báo có thể được gửi dưới dạng page_token để truy xuất trang tiếp theo. Nếu trường này bị bỏ qua thì sẽ không có trang tiếp theo.

OfferType

Loại ưu đãi của một chương trình khuyến mãi.

Enum
OFFER_TYPE_UNSPECIFIED Loại ưu đãi không xác định.
NO_CODE Loại ưu đãi không có mã.
GENERIC_CODE Loại ưu đãi có mã. Bạn phải nhập mã sử dụng ưu đãi chung cho chương trình khuyến mãi khi offerType = GENERIC_CODE.

ProductApplicability

Sản phẩm hoặc danh sách sản phẩm được áp dụng chương trình khuyến mãi.

Enum
PRODUCT_APPLICABILITY_UNSPECIFIED Chưa xác định được chương trình khuyến mãi áp dụng cho những sản phẩm nào.
ALL_PRODUCTS Áp dụng cho tất cả sản phẩm.
SPECIFIC_PRODUCTS Chỉ áp dụng cho một sản phẩm hoặc danh sách sản phẩm.

Khuyến mãi

Đại diện cho chương trình khuyến mãi. Hãy xem các bài viết sau để biết thêm thông tin.

Dưới đây là các thuộc tính bắt buộc đầu vào của chương trình khuyến mãi để vượt qua các bước kiểm tra xác thực dữ liệu:

Sau khi chèn, cập nhật thông tin đầu vào của chương trình khuyến mãi, có thể mất vài phút trước khi hệ thống lấy được chương trình khuyến mãi cuối cùng.

Trường
name

string

Giá trị nhận dạng. Tên của quảng cáo. Định dạng accounts/{account}/promotions/{promotion}
promotion_id

string

Bắt buộc. Người dùng đã cung cấp mã khuyến mãi để xác định riêng biệt chương trình khuyến mãi đó. Hãy tuân thủ các yêu cầu tối thiểu để tránh bị từ chối chương trình khuyến mãi.
content_language

string

Bắt buộc. Mã ngôn ngữ gồm hai chữ cái theo tiêu chuẩn ISO 639-1 của chương trình khuyến mãi.

Chương trình khuyến mãi chỉ áp dụng cho các ngôn ngữ đã chọn.
target_country

string

Bắt buộc. Quốc gia mục tiêu được dùng trong giá trị nhận dạng duy nhất. Được biểu thị dưới dạng mã lãnh thổ CLDR.

Chương trình khuyến mãi chỉ áp dụng ở một số quốc gia, Trang thông tin miễn phí và quảng cáo Mua sắm Quảng cáo kho hàng tại địa phương
redemption_channel[]

RedemptionChannel

Bắt buộc. Kênh đổi thưởng cho chương trình khuyến mãi. Cần có ít nhất một kênh.
data_source

string

Chỉ có đầu ra. Nguồn dữ liệu chính của chương trình khuyến mãi.
attributes

Attributes

Không bắt buộc. Danh sách các thuộc tính của chương trình khuyến mãi.
custom_attributes[]

CustomAttribute

Không bắt buộc. Danh sách các thuộc tính tuỳ chỉnh (do người bán cung cấp). Bạn cũng có thể sử dụng thuộc tính này để gửi bất kỳ thuộc tính nào của quy cách dữ liệu ở dạng chung chung (ví dụ: { "name": "size type", "value": "regular" }). Cách này rất hữu ích khi gửi các thuộc tính không được API nêu rõ.
promotion_status

PromotionStatus

Chỉ có đầu ra. Trạng thái của chương trình khuyến mãi, vấn đề về xác thực dữ liệu, tức là thông tin về chương trình khuyến mãi được tính toán không đồng bộ.
version_number

int64

Không bắt buộc. Đại diện cho phiên bản hiện có (độ mới) của chương trình khuyến mãi, có thể được dùng để duy trì thứ tự phù hợp khi nhiều nội dung cập nhật được thực hiện cùng một lúc.

Nếu được đặt, việc chèn sẽ bị chặn khi số phiên bản thấp hơn số phiên bản hiện tại của chương trình khuyến mãi hiện có. Bạn có thể chèn lại (ví dụ: làm mới chương trình khuyến mãi sau 30 ngày) bằng version_number hiện tại.

Nếu thao tác này bị ngăn chặn, thì ngoại lệ bị huỷ sẽ được gửi.

PromotionStatus

Trạng thái của chương trình khuyến mãi.

Trường
destination_statuses[]

DestinationStatus

Chỉ có đầu ra. Các vị trí xuất hiện dự kiến cho chương trình khuyến mãi.
item_level_issues[]

ItemLevelIssue

Chỉ có đầu ra. Danh sách các vấn đề liên quan đến chương trình khuyến mãi.
creation_date

Timestamp

Chỉ có đầu ra. Ngày tạo chương trình khuyến mãi theo định dạng ISO 8601: Ngày, giờ và bù trừ, ví dụ: 2020-01-02T09:00:00+01:00 hoặc 2020-01-02T09:00:00Z
last_update_date

Timestamp

Chỉ có đầu ra. Ngày gần đây nhất mà trạng thái của chương trình khuyến mãi được cập nhật ở định dạng ISO 8601: Ngày, giờ và bù trừ, ví dụ: 2020-01-02T09:00:00+01:00 hoặc 2020-01-02T09:00:00Z

DestinationStatus

Trạng thái của đích đến được chỉ định.

Trường
reporting_context

ReportingContextEnum

Chỉ có đầu ra. Tên của nền tảng đăng chương trình khuyến mãi.
status

State

Chỉ có đầu ra. Trạng thái của đích đến được chỉ định.

Tiểu bang

Trạng thái hiện tại của chương trình khuyến mãi.

Enum
STATE_UNSPECIFIED Chương trình khuyến mãi có trạng thái không xác định.
IN_REVIEW Chương trình khuyến mãi này đang được xem xét.
REJECTED Quảng cáo bị từ chối.
LIVE Chương trình khuyến mãi đã được phê duyệt và đang hoạt động.
STOPPED Người bán đã ngừng chương trình khuyến mãi.
EXPIRED Chương trình khuyến mãi này không còn hoạt động nữa.
PENDING Chương trình khuyến mãi chưa bị dừng và mọi bài đánh giá đều được phê duyệt, nhưng ngày áp dụng là một ngày trong tương lai.

ItemLevelIssue

Vấn đề liên quan đến chương trình khuyến mãi.

Trường
code

string

Chỉ có đầu ra. Mã lỗi của vấn đề.
severity

Severity

Chỉ có đầu ra. Vấn đề này ảnh hưởng như thế nào đến việc phân phát quảng cáo.
resolution

string

Chỉ có đầu ra. Liệu người bán có thể giải quyết vấn đề này hay không.
attribute

string

Chỉ có đầu ra. Tên của thuộc tính, nếu vấn đề là do một thuộc tính duy nhất gây ra.
reporting_context

ReportingContextEnum

Chỉ có đầu ra. Đích đến xảy ra vấn đề.
description

string

Chỉ có đầu ra. Nội dung mô tả ngắn về vấn đề bằng tiếng Anh.
detail

string

Chỉ có đầu ra. Nội dung mô tả chi tiết về vấn đề bằng tiếng Anh.
documentation

string

Chỉ có đầu ra. URL của một trang web giúp giải quyết vấn đề này.
applicable_countries[]

string

Chỉ có đầu ra. Danh sách mã quốc gia (ISO 3166-1 alpha-2) có vấn đề áp dụng với mặt hàng.

Mức độ nghiêm trọng

Mức độ nghiêm trọng của vấn đề.

Enum
SEVERITY_UNSPECIFIED Chưa chỉ định.
NOT_IMPACTED Vấn đề này là một cảnh báo và không ảnh hưởng trực tiếp đến chương trình khuyến mãi.
DEMOTED Chương trình khuyến mãi bị giảm hạng và rất có thể có hiệu suất hạn chế trong kết quả tìm kiếm
DISAPPROVED Vấn đề sẽ từ chối chương trình khuyến mãi.

RedemptionChannel

Kênh của chương trình khuyến mãi.

Enum
REDEMPTION_CHANNEL_UNSPECIFIED Cho biết kênh chưa được chỉ định.
IN_STORE Cho biết rằng kênh đã có mặt tại cửa hàng. Kênh này giống với kênh local được dùng cho products.
ONLINE Cho biết rằng kênh đang trực tuyến.

StoreApplicability

Mã cửa hàng hoặc danh sách mã cửa hàng áp dụng chương trình khuyến mãi. Chỉ dành cho chương trình khuyến mãi Quảng cáo kho hàng tại địa phương.

Enum
STORE_APPLICABILITY_UNSPECIFIED Chưa xác định được mã cửa hàng áp dụng chương trình khuyến mãi này.
ALL_STORES Chương trình khuyến mãi áp dụng cho tất cả cửa hàng.
SPECIFIC_STORES Chương trình khuyến mãi chỉ áp dụng cho những cửa hàng được chỉ định.