REST Resource: accounts.promotions

Tài nguyên: Chương trình 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.

Biểu diễn dưới dạng 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
}
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}
promotionId

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.
contentLanguage

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.
targetCountry

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
redemptionChannel[]

enum (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.
dataSource

string

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

object (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.
customAttributes[]

object (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õ.
promotionStatus

object (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ộ.
versionNumber

string (int64 format)

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 versionNumber 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.

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.

Thuộc tính

Thuộc tính.

Biểu diễn dưới dạng 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
}
Trường
productApplicability

enum (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.
offerType

enum (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.
genericRedemptionCode

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.
longTitle

string

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

enum (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.
promotionDestinations[]

enum (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
itemIdInclusion[]

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 productApplicability 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.
brandInclusion[]

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 productApplicability 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.
itemGroupIdInclusion[]

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 áp dụng khuyến mãi cho sản phẩm [productApplicability] được đặt thành specific_products.
productTypeInclusion[]

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 productApplicability 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.
itemIdExclusion[]

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 productApplicability 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.
brandExclusion[]

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 productApplicability 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.
itemGroupIdExclusion[]

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 productApplicability 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.
productTypeExclusion[]

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 productApplicability 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.
minimumPurchaseAmount

object (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.
minimumPurchaseQuantity

string (int64 format)

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.
limitQuantity

string (int64 format)

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.
limitValue

object (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.
percentOff

string (int64 format)

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.
moneyOffAmount

object (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.
getThisQuantityDiscounted

string (int64 format)

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.
freeGiftValue

object (Price)

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

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.
freeGiftItemId

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.
promotionEffectiveTimePeriod

object (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.
promotionDisplayTimePeriod

object (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 promotionDisplayTimePeriod, thì khoảng thời gian có hiệu lực của chương trình khuyến mãi promotionEffectiveTimePeriod 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.
storeApplicability

enum (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 storeApplicability thành ALL_STORES và storeCodesInclusion hoặc score_code_exclusion được đặt thành một giá trị.
storeCodesInclusion[]

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 storeApplicability đượ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.
storeCodesExclusion[]

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 storeApplicability được đặt thành specific_stores.
promotionUrl

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ó promotionUrl. 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.

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.

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.

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ó minimumPurchaseQuantity và getThisQuantityDiscounted. Bạn cũng phải có moneyOffAmount.
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ó minimumPurchaseQuantity và getThisQuantityDiscounted. 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ó minimumPurchaseQuantity và moneyOffAmount.
BUY_M_GET_PERCENT_OFF Mua số lượng M, được giảm tiền. Phải có minimumPurchaseQuantity 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.

DestinationEnum

Giá trị đích đến.

Enum
DESTINATION_ENUM_UNSPECIFIED Chưa chỉ định.
SHOPPING_ADS Quảng cáo Mua sắm.
DISPLAY_ADS Quảng cáo hiển thị.
LOCAL_INVENTORY_ADS Quảng cáo hàng lưu kho tại cửa hàng gần nhất.
FREE_LISTINGS Trang thông tin miễn phí.
FREE_LOCAL_LISTINGS Trang thông tin miễn phí về sản phẩm tại địa phương.
YOUTUBE_SHOPPING YouTube Mua sắm.

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.

PromotionStatus

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

Biểu diễn dưới dạng JSON 
{
  "destinationStatuses": [
    {
      object (DestinationStatus)
    }
  ],
  "itemLevelIssues": [
    {
      object (ItemLevelIssue)
    }
  ],
  "creationDate": string,
  "lastUpdateDate": string
}
Trường
destinationStatuses[]

object (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.
itemLevelIssues[]

object (ItemLevelIssue)

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

string (Timestamp format)

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
lastUpdateDate

string (Timestamp format)

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.

Biểu diễn dưới dạng JSON 
{
  "reportingContext": enum (ReportingContextEnum),
  "status": enum (State)
}
Trường
reportingContext

enum (ReportingContextEnum)

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

enum (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.

Biểu diễn dưới dạng JSON 
{
  "code": string,
  "severity": enum (Severity),
  "resolution": string,
  "attribute": string,
  "reportingContext": enum (ReportingContextEnum),
  "description": string,
  "detail": string,
  "documentation": string,
  "applicableCountries": [
    string
  ]
}
Trường
code

string

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

enum (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.
reportingContext

enum (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.
applicableCountries[]

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.

Phương thức

get

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

insert

 Chèn chương trình khuyến mãi cho tài khoản Merchant Center.

list

 Liệt kê các chương trình khuyến mãi trong tài khoản Merchant Center của bạn.