Tổng quan về Merchant promotion API (API chương trình khuyến mãi của người bán)

Sử dụng chương trình khuyến mãi để giới thiệu ưu đãi đặc biệt cho các sản phẩm mà bạn bán trên Google. Chương trình khuyến mãi xuất hiện trên nhiều sản phẩm của Google, bao gồm cả Google Tìm kiếm, Mua sắm và Chrome. Chương trình khuyến mãi phải đáp ứng một số tiêu chí nhất định thì mới được phê duyệt. Để biết thêm thông tin, hãy xem phần Tiêu chí quảng bá.

Khi bạn thêm chương trình khuyến mãi cho sản phẩm, người mua sắm sẽ thấy một đường liên kết ưu đãi đặc biệt. Ví dụ: "Giảm 15%" hoặc "Miễn phí vận chuyển". Đường liên kết đến ưu đãi có thể tăng sức hấp dẫn của sản phẩm và khuyến khích người mua sắm mua hàng. Tất cả chương trình khuyến mãi sẽ áp dụng tại quy trình thanh toán hoặc điểm bán hàng.

Để biết thêm thông tin, hãy xem bài viết Kiến thức cơ bản về chương trình khuyến mãi.

Điều kiện tiên quyết

Trước khi hiển thị chương trình khuyến mãi của bạn, Google cần bạn cung cấp thông tin cụ thể về doanh nghiệp và sản phẩm. Bạn phải có:

Ngoài ra, bạn phải đăng ký tài khoản người bán của mình tham gia chương trình Khuyến mãi. Nếu bạn không chắc chắn liệu mình đã đăng ký hay chưa, hãy kiểm tra trong Merchant Center.

Nếu bạn chưa đăng ký, hãy hoàn tất biểu mẫu yêu cầu. Nhóm khuyến mãi sẽ thông báo cho bạn khi bạn đã chuẩn bị đầy đủ để bắt đầu triển khai.

Để biết thêm thông tin, hãy xem Chính sách và tiêu chí tham gia.

Tạo một nguồn dữ liệu

Bạn có thể sử dụng phương thức accounts.dataSources.create để tạo nguồn dữ liệu khuyến mãi. Nếu có nguồn dữ liệu chương trình khuyến mãi hiện có, hãy sử dụng phương thức accounts.dataSources.list để truy xuất tất cả các nguồn dữ liệu. Sau đó, bạn có thể sử dụng trường name của nguồn dữ liệu khuyến mãi để tạo chương trình khuyến mãi.

Yêu cầu sau đây cho biết cách tạo nguồn dữ liệu để thêm chương trình khuyến mãi:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

Thay thế nội dung sau:

  • {ACCOUNT_ID}: Giá trị nhận dạng duy nhất của tài khoản của bạn như xuất hiện trong giao diện người dùng Merchant Center.
  • {DISPLAY_NAME}: Tên hiển thị của nguồn dữ liệu.
  • {CONTENT_LANGUAGE}: Mã ngôn ngữ ISO 639-1 gồm hai chữ cái của các sản phẩm trong nguồn dữ liệu.
  • {TARGET_COUNTRY}: Mã lãnh thổ CLDR của quốc gia mục tiêu mà bạn muốn quảng cáo xuất hiện.

Sau khi yêu cầu chạy thành công, bạn sẽ thấy phản hồi sau đây chứa thông tin chi tiết về nguồn dữ liệu chương trình khuyến mãi mới tạo:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

Tạo quảng cáo

Bạn có thể sử dụng phương thức accounts.promotions.insert để tạo hoặc cập nhật chương trình khuyến mãi. Phương thức accounts.promotions.insert lấy tài nguyên promotions và tên nguồn dữ liệu làm dữ liệu đầu vào. Phương thức này sẽ trả về chương trình khuyến mãi mới hoặc đã cập nhật (nếu thành công).

Để tạo chương trình khuyến mãi, bạn cần có tên của nguồn dữ liệu. Bạn cũng phải cung cấp giá trị cho các trường sau trong yêu cầu:

  • contentLanguage
  • redemptionChannel
  • promotionId
  • targetCountry
  • attributes.offerType
  • attributes.genericRedemptionCode
  • attributes.couponValueType
  • attributes.productApplicability
  • attributes.promotionEffectiveTimePeriod.endTime
  • attributes.promotionEffectiveTimePeriod.startTime
  • attributes.longTitle

Google sẽ xem xét và phê duyệt chương trình khuyến mãi của bạn trước khi phân phối. Để biết thêm thông tin, hãy xem phần Quy trình phê duyệt chương trình khuyến mãi.

Bạn nên tham khảo Chính sách về chương trình khuyến mãi để đảm bảo rằng chương trình khuyến mãi mà bạn tạo sẽ mang lại giá trị và tuân thủ chính sách về quảng cáo Mua sắm.

Yêu cầu sau đây minh hoạ cách tạo một chương trình khuyến mãi trực tuyến:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Để biết thông tin về các quy tắc áp dụng khi đặt mã khuyến mãi, hãy xem phần Yêu cầu tối thiểu đối với thuộc tính mã khuyến mãi.

Các giá trị hợp lệ cho trường offerType bắt buộc là NO_CODE và GENERIC_CODE. Nếu bạn không cung cấp một trong các giá trị này, yêu cầu API sẽ không thành công với phản hồi HTTP 400 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type. Hệ thống sẽ trả về một thông báo lỗi tương tự nếu bạn không cung cấp bất kỳ trường bắt buộc nào.

Nếu bạn không cung cấp giá trị cho trường attributes.genericRedemptionCode, yêu cầu sẽ không thành công và phản hồi HTTP 400 [genericRedemptionCode] No redemption code provided sẽ được gửi.

Giá trị cho các trường promotion.attributes.promotionDisplayTimePeriod.startTime và promotion.attributes.promotionDisplayTimePeriod.endTime phải ở định dạng yyyy-mm-ddThh:mm:ssZ. Hãy nhớ thay thế các giá trị cho các trường này bằng ngày trong tương lai.

Để biết thêm thông tin, hãy xem Quy cách dữ liệu chương trình khuyến mãi.

Để biết các phương pháp hay nhất về cách tạo chương trình khuyến mãi, hãy xem bài viết Các phương pháp hay nhất về chương trình khuyến mãi.

Để biết danh sách các thuộc tính liên quan đến chương trình khuyến mãi, hãy xem bài viết Thêm thuộc tính dữ liệu có cấu trúc.

Sau khi yêu cầu tạo chương trình khuyến mãi chạy thành công, có thể mất vài phút để bạn có thể truy xuất chương trình khuyến mãi bằng API hoặc để chương trình khuyến mãi xuất hiện trong Merchant Center.

Sau đây là một số chương trình khuyến mãi mẫu mà bạn có thể sử dụng để bắt đầu.

Chương trình khuyến mãi tại cửa hàng địa phương áp dụng cho tất cả sản phẩm và tất cả cửa hàng

Yêu cầu mẫu sau đây cho biết cách tạo chương trình khuyến mãi tại cửa hàng địa phương áp dụng cho tất cả sản phẩm trong tài khoản Merchant Center và tất cả cửa hàng được thêm vào tài khoản Trang doanh nghiệp được liên kết.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Trường productApplicability là bắt buộc. Thuộc tính này cho biết chương trình khuyến mãi áp dụng cho tất cả sản phẩm hay chỉ một số sản phẩm. Các giá trị được hỗ trợ là ALL_PRODUCTS và SPECIFIC_PRODUCTS. Để biết thêm thông tin, hãy xem bài viết Chọn sản phẩm cho chương trình khuyến mãi.

Trường couponValueType là bắt buộc. Đây là tín hiệu cho biết loại chương trình khuyến mãi mà bạn đang chạy. Để biết danh sách các giá trị được hỗ trợ, hãy xem phần Loại giá trị của phiếu giảm giá. Tuỳ thuộc vào loại giá trị phiếu giảm giá mà bạn đã chọn, một số thuộc tính là bắt buộc.

Trường minimumPurchaseQuantity cho phép bạn đặt giá trị cho số lượng hàng tối thiểu cần mua để sử dụng ưu đãi khuyến mãi. Để biết thêm thông tin, hãy xem phần Số lượng hàng tối thiểu phải mua để được hưởng khuyến mãi.

Tương tự, bạn có thể sử dụng trường minimumPurchaseAmount để đặt số tiền mua hàng tối thiểu cần thiết để sử dụng chương trình khuyến mãi. Để biết thêm thông tin, hãy xem phần Số tiền mua tối thiểu.

Để biết thêm thông tin về các giá trị bạn cần cung cấp để tạo chương trình khuyến mãi tại địa phương, hãy xem bài viết Quy cách nguồn dữ liệu cho chương trình khuyến mãi tại địa phương.

Chương trình khuyến mãi trực tuyến áp dụng cho một số sản phẩm được chọn bằng mã sử dụng ưu đãi

Yêu cầu mẫu sau đây cho biết cách tạo chương trình khuyến mãi trực tuyến áp dụng cho các sản phẩm đã chọn bằng mã sử dụng.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Xem quảng cáo

Để xem một chương trình khuyến mãi, hãy sử dụng accounts.promotions.get. Yêu cầu GET này chỉ có thể đọc. Phương thức này yêu cầu merchantId và mã của chương trình khuyến mãi. Phương thức GET trả về tài nguyên chương trình khuyến mãi tương ứng.

Ví dụ:

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

Thay thế nội dung sau:

  • {ACCOUNT_ID}: Giá trị nhận dạng duy nhất của tài khoản Merchant Center.
  • {PROMOTION_ID}: Giá trị nhận dạng duy nhất của chương trình khuyến mãi mà bạn muốn truy xuất. Định dạng là {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

Xin lưu ý rằng bạn sẽ mất vài phút để truy xuất chương trình khuyến mãi mới tạo bằng API.

Xem chương trình khuyến mãi tại địa phương

Yêu cầu mẫu sau đây truy xuất một chương trình khuyến mãi tại địa phương có mã chương trình khuyến mãi là in_store~en~US~buy_2_get_10_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

Sau khi yêu cầu thành công, bạn sẽ thấy phản hồi sau:

{
 "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Trường moneyOffAmount trong mẫu này cung cấp mức chiết khấu được cung cấp trong chương trình khuyến mãi. Để biết thêm thông tin, hãy xem phần Số tiền chiết khấu của chương trình khuyến mãi.

Trường promotionUrl trong mẫu này cung cấp đường liên kết đến trang web của cửa hàng nơi người mua sắm có thể tìm thấy thêm thông tin về 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ẽ trả về lỗi nếu bạn không thêm trường promotionUrl.

Xem chương trình khuyến mãi trực tuyến

Yêu cầu mẫu sau đây truy xuất một chương trình khuyến mãi trực tuyến có mã chương trình khuyến mãi là online~en~US~25_pct_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
}

Trường itemIdInclusion được sử dụng trong mẫu này đề cập đến những sản phẩm đủ điều kiện tham gia chương trình khuyến mãi. Để biết thêm thông tin, hãy xem phần Mã sản phẩm cho chương trình khuyến mãi.

Liệt kê chương trình khuyến mãi

Bạn có thể sử dụng phương thức promotions.list để xem tất cả chương trình khuyến mãi đã tạo.

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

Nội dung phản hồi chứa danh sách tất cả chương trình khuyến mãi trong tài khoản của bạn. Đối với mỗi chương trình khuyến mãi, bạn có thể xem thông tin chi tiết như promotionId, redemptionChannel, dataSource, promotionStatus và nhiều thông tin khác.

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

Để xem trạng thái của chương trình khuyến mãi, hãy xem thuộc tính promotionStatus do phương thức promotions.get hoặc promotions.list trả về.

Trường promotionStatus có thể có các giá trị sau:

  • IN_REVIEW: Chương trình khuyến mãi vẫn đ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: Tài khoả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 hoạt động là trong tương lai.
  • STATE_UNSPECIFIED: Trạng thái chương trình khuyến mãi không xác định.

Để tìm hiểu quy trình phê duyệt chương trình khuyến mãi mà bạn đã tạo, hãy xem bài viết Quy trình phê duyệt chương trình khuyến mãi.

Trạng thái chương trình khuyến mãi mẫu

Các mẫu sau đây minh hoạ sự khác biệt giữa các yêu cầu thành công và không thành công.

Thiếu mối liên kết sản phẩm

Phần nội dung phản hồi sau đây cho thấy một nội dung quảng bá trực tuyến bị từ chối do thiếu liên kết sản phẩm.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

Để khắc phục sự cố về chương trình khuyến mãi bị từ chối và tìm hiểu cách tránh bị từ chối trong tương lai, hãy xem bài viết Khắc phục vấn đề về chương trình khuyến mãi bị từ chối.

Nếu chương trình khuyến mãi mà bạn tạo không được phê duyệt, bạn sẽ nhận được email nêu lý do từ chối và hướng dẫn khắc phục vấn đề.

Chương trình khuyến mãi đang được đánh giá

Nội dung phản hồi sau đây cho thấy một chương trình khuyến mãi vẫn đang được đánh giá.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

Chương trình khuyến mãi đã được phê duyệt và đang hoạt động

Nội dung phản hồi sau đây cho thấy một chương trình khuyến mãi mà người mua sắm có thể nhìn thấy.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

Để biết thêm thông tin, hãy xem Câu hỏi thường gặp về trạng thái chương trình khuyến mãi.

Tìm hiểu thêm