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.

Sau khi chèn hoặc cập nhật thông tin đầu vào về chương trình khuyến mãi, có thể mất vài phút thì bạn mới có thể truy xuất 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 OAuth 2.0 Overview.
InsertPromotion

rpc InsertPromotion(InsertPromotionRequest) returns (Promotion)

Chèn một chương trình khuyến mãi cho tài khoản Merchant Center của bạn. Nếu chương trình khuyến mãi đã tồn tại, thì hệ thống sẽ cập nhật chương trình khuyến mãi đó.

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 OAuth 2.0 Overview.
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. Phản hồi có thể chứa ít mục hơn so với số lượng mà pageSize chỉ định. Hãy dựa vào pageToken để xác định xem có thêm mục nào cần yêu cầu 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 thì bạn mới có thể truy xuất chương trình khuyến mãi đã xử lý và 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 OAuth 2.0 Overview.

Thuộc tính

Thuộc tính.

Trường
product_applicability

ProductApplicability

Bắt buộc. Phạm vi áp dụng của 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 cụ thể.
offer_type

OfferType

Bắt buộc. Loại chương trình khuyến mãi. Hãy sử dụng thuộc tính này để cho biết 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 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ị của 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ị phiếu giảm giá đã chọn, một số thuộc tính là bắt buộc.
promotion_destinations[]

DestinationEnum

Bắt buộc. Danh sách các đích đế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 một 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 phần Nền tảng đăng chương trình khuyến mãi
item_id_inclusion[]

string

Không bắt buộc. Bộ lọc sản phẩm theo mã mặt hàng của chương trình khuyến mãi. Các thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt giá trị cho thuộc tính khả năng áp dụng cho sản phẩm product_applicability 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. Các thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt giá trị cho thuộc tính khả năng áp dụng cho sản phẩm product_applicability thành specific_products.
item_group_id_inclusion[]

string

Không bắt buộc. Bộ lọc sản phẩm theo mã nhóm mặt hàng của chương trình khuyến mãi. Các thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt giá trị cho thuộc tính khả năng áp dụng cho sản phẩm [product_applicability] thành specific_products.
product_type_inclusion[]

string

Không bắt buộc. Bộ lọc sản phẩm theo loại sản phẩm cho chương trình khuyến mãi. Các thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt giá trị cho thuộc tính khả năng áp dụng cho sản phẩm product_applicability thành specific_products.
item_id_exclusion[]

string

Không bắt buộc. Bộ lọc sản phẩm theo mã mặt hàng bị loại trừ cho chương trình khuyến mãi. Các thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt giá trị cho thuộc tính khả năng áp dụng cho sản phẩm product_applicability thành specific_products.
brand_exclusion[]

string

Không bắt buộc. Bộ lọc sản phẩm theo thương hiệu bị loại trừ cho chương trình khuyến mãi. Các thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt giá trị cho thuộc tính khả năng áp dụng cho sản phẩm product_applicability thành specific_products.
item_group_id_exclusion[]

string

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

string

Không bắt buộc. Bộ lọc sản phẩm theo loại trừ loại sản phẩm cho chương trình khuyến mãi. Các thuộc tính bộ lọc sản phẩm chỉ áp dụng khi bạn đặt giá trị cho thuộc tính khả năng áp dụng cho sản phẩm product_applicability thành specific_products.
minimum_purchase_amount

Price

Không bắt buộc. Số tiền mua hàng tối thiểu cho 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 khuyến mãi.
limit_quantity

int64

Không bắt buộc. Số lượng hàng tối đa được khuyến mãi khi 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 trong chương trình khuyến mãi.
percent_off

int64

Không bắt buộc. Mức chiết khấu theo phần trăm đượ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 đượ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 chiết khấu 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í của 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 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 thể hiện ngày có hiệu lực của chương trình khuyến mãi. Thuộc tính này chỉ định rằng bạn có thể thử nghiệm 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 thể hiện ngày hiển thị của chương trình khuyến mãi. Thuộc tính này quy định phạm vi ngày và giờ mà chương trình khuyến mãi sẽ được hiển thị trên Google.com và quảng cáo Mua sắm. Nếu bạn không chỉ định thuộc tính khoảng thời gian hiển thị chương trình khuyến mãi promotion_display_time_period, thì thuộc tính 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 phạm vi ngày và giờ mà chương trình khuyến mãi sẽ được hiển thị trên Google.com và quảng cáo Mua sắm.
store_applicability

StoreApplicability

Không bắt buộc. 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 cụ thể. Chương trình khuyến mãi của quảng cáo Kho hàng tại địa phương sẽ báo lỗi nếu không có thông tin về phạm vi áp dụng tại cửa hàng. Lỗi INVALID_ARGUMENT sẽ được gửi nếu store_applicability được đặt 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. Lưu mã để thêm cho chương trình khuyến mãi. Các thuộc tính bộ lọc cửa hàng chỉ áp dụng khi bạn đặt thuộc tính store_applicability thành specific_stores.

Mã cửa hàng (mã cửa hàng trong Trang doanh nghiệp) của cửa hàng thực tế bán sản phẩm. Hãy 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. Lưu trữ mã cần loại trừ cho chương trình khuyến mãi. Các thuộc tính bộ lọc cửa hàng chỉ áp dụng khi bạn đặt thuộc tính store_applicability thành specific_stores.
promotion_url

string

Không bắt buộc. URL đến trang trên trang web của người bán nơi chương trình khuyến mãi xuất hiện. Chương trình khuyến mãi của 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 được dùng để xác nhận rằng chương trình khuyến mãi 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 loại giá trị của phiếu giảm giá chưa được chỉ định.
MONEY_OFF Loại giá trị của phiếu giảm giá theo giá trị tiền.
PERCENT_OFF Loại giá trị của phiếu giảm giá theo tỷ lệ phần trăm.
BUY_M_GET_N_MONEY_OFF Loại giá trị của phiếu giảm giá: Mua số lượng M, được giảm N tiền. Bắt buộc 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 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á. Bắt buộc 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á vận chuyển miễn phí tiêu chuẩn. Chỉ áp dụng cho chương trình khuyến mãi trên mạng.
FREE_SHIPPING_OVERNIGHT Loại giá trị của phiếu giảm giá miễn phí vận chuyển qua đêm. Chỉ áp dụng cho chương trình khuyến mãi trên mạng.
FREE_SHIPPING_TWO_DAY Loại giá trị của phiếu giảm giá miễn phí vận chuyển trong 2 ngày. Chỉ áp dụng cho chương trình khuyến mãi trên mạng.

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 của 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 mà bạ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. Định dạng nguồn dữ liệu của chương trình 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 đã 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ần trả về. Dịch vụ có thể trả về ít hơn giá trị này. Giá trị tối đa là 250; các giá trị trên 250 sẽ được ép thành 250. 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 giá trị 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

Các chương trình khuyến mãi đã 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 bạn bỏ qua trường này, thì sẽ không có trang tiếp theo.

OfferType

Loại ưu đãi của 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 có mã đổ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 mà chương trình khuyến mãi áp dụng.

Enum
PRODUCT_APPLICABILITY_UNSPECIFIED Không xác định chương trình khuyến mãi áp dụng cho 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 một 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 chi tiết.

Dưới đây là các thuộc tính đầu vào bắt buộc 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 dữ liệu đầu vào về chương trình khuyến mãi, có thể mất vài phút thì bạn mới có thể truy xuất 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ã chương trình khuyến mãi để xác định riêng biệt chương trình khuyến mãi đó. 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ữ ISO 639-1 gồm hai chữ cái cho chương trình khuyến mãi.

Chương trình khuyến mãi chỉ dành cho một số ngôn ngữ.
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ỉ có ở 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 ưu đãi của 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 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ể 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 (ví dụ: { "name": "size type", "value": "regular" }). Điều này hữu ích khi gửi các thuộc tính không được API hiển thị rõ ràng.
promotion_status

PromotionStatus

Chỉ có đầu ra. Trạng thái của chương trình khuyến mãi, vấn đề về việc 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. Biểu thị phiên bản hiện tại (tính mới) của chương trình khuyến mãi. Bạn có thể dùng thuộc tính này để duy trì thứ tự phù hợp khi thực hiện nhiều lần cập nhật cùng một lúc.

Nếu được đặt, thao tác chèn sẽ bị ngăn 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 bị ngăn chặn, 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. Điểm đến dự kiến của 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 ở định dạng ISO 8601: Ngày, giờ và độ lệch, 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 cập nhật trạng thái chương trình khuyến mãi gần đây nhất ở định dạng ISO 8601: Ngày, giờ và độ lệch, 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 đã chỉ định.

Trường
reporting_context

ReportingContextEnum

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

State

Chỉ có đầu ra. Trạng thái của đích đến đã 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 Trạng thái chương trình khuyến mãi không xác định.
IN_REVIEW Chương trình khuyến mãi này đang được xem xét.
REJECTED Chương trình khuyến mãi 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 đã dừng chương trình khuyến mãi.
EXPIRED Chương trình khuyến mãi không còn hoạt động nữa.
PENDING Chương trình khuyến mãi không bị dừng và tất cả bài đánh giá đều được phê duyệt, nhưng ngày bắt đầu áp dụng là 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. Mức độ ảnh hưởng của vấn đề này đến việc phân phát chương trình khuyến mãi.
resolution

string

Chỉ có đầu ra. Liệu người bán có thể giải quyết vấn đề 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 gây ra.
reporting_context

ReportingContextEnum

Chỉ có đầu ra. Đích đến mà vấn đề áp dụng.
description

string

Chỉ có đầu ra. Nội dung mô tả ngắn gọ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 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) nơi vấn đề áp dụng cho 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 Đâ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ị hạ cấp và có nhiều khả năng sẽ bị giới hạn hiệu suất trong kết quả tìm kiếm
DISAPPROVED Vấn đề khiến chương trình khuyến mãi bị từ chố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 kênh đang trong cửa hàng. Điều này giống với kênh local dùng cho products.
ONLINE Cho biết kênh đang hoạt động.

StoreApplicability

Mã cửa hàng hoặc danh sách mã cửa hàng áp dụng cho 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 Không xác định được mã cửa hàng áp dụng cho chương trình khuyến mãi.
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 các cửa hàng được chỉ định.