REST Resource: accounts.promotions

Tài nguyên: 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 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 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 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ã chương trình khuyến mãi để nhận dạng duy nhấ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ữ 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ữ.
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 ưu đãi của 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 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ể 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.
promotionStatus

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

string (int64 format)

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 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 kênh đang trong cửa hàng. Kênh này giống với kênh local được dùng cho products.
ONLINE Cho biết kênh đang hoạt động.

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

enum (OfferType)

Bắt buộc. Loại chương trình 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 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ị 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.
promotionDestinations[]

enum (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 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 Đích đến của chương trình khuyến mãi
itemIdInclusion[]

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 productApplicability của sản phẩm đủ điều kiện được 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. 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. 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 [productApplicability] được đặt thành specific_products.
productTypeInclusion[]

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 productApplicability của sản phẩm đủ điều kiện được khuyến mãi thành specific_products.
itemIdExclusion[]

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 productApplicability của sản phẩm đủ điều kiện được 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. 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 productApplicability của sản phẩm đủ điều kiện được khuyến mãi thành 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 cho 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 khuyến mãi.
limitQuantity

string (int64 format)

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

object (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.
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 đượ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 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 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.
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 khoảng thời gian hiển thị chương trình khuyến mãi promotionDisplayTimePeriod, 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 promotionEffectiveTimePeriod 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.
storeApplicability

enum (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 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. Lỗi INVALID_ARGUMENT sẽ được gửi nếu storeApplicability được đặt 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. Lưu mã để thêm 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 bạn đặt thuộc tính storeApplicability 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. Hãy 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. 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 storeApplicability thành specific_stores.
promotionUrl

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ó promotionUrl. URL được 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 mà chương trình khuyến mãi áp dụng.

Enum
PRODUCT_APPLICABILITY_UNSPECIFIED Không xác định được 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.

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 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ó minimumPurchaseQuantity và getThisQuantityDiscounted. Bạn cũng phải có moneyOffAmount.
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á. 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á vận chuyển miễn phí tiêu chuẩn.
FREE_SHIPPING_OVERNIGHT Loại giá trị của phiếu giảm giá miễn phí vận chuyển qua đêm.
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.

DestinationEnum

Giá trị đích.

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.
YOUTUBE_SHOPPING_CHECKOUT Quy trình thanh toán trên YouTube Mua sắm.
YOUTUBE_AFFILIATE Chương trình liên kết của YouTube.
FREE_VEHICLE_LISTINGS Trang thông tin miễn phí về xe.
VEHICLE_ADS Quảng cáo xe.
CLOUD_RETAIL Bán lẻ trên đám mây.
LOCAL_CLOUD_RETAIL Bán lẻ trên đám mây tại địa phương.

StoreApplicability

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

string (Timestamp format)

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.

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 đích đến của chương trình khuyến mãi.
status

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

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

Phương thức

get

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

insert

 Chèn một chương trình khuyến mãi cho tài khoản Merchant Center của bạn.

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.