Tổng quan về API phụ Khuyến mãi

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, trong đó 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 để được phê duyệt. Để biết thêm thông tin, hãy xem Tiêu chí khuyến mãi.

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 giá 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 Thông tin 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ó những thông tin sau:

Ngoài ra, bạn phải đăng ký tài khoản Merchant Center của mình trong chương trình Khuyến mãi. Nếu bạn không chắc mình đã đăng ký hay chưa, hãy kiểm tra 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 một nguồn dữ liệu khuyến mãi. Nếu có một nguồn dữ liệu 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 một nguồn dữ liệu để thêm chương trình khuyến mãi:

POST https://merchantapi.googleapis.com/datasources/v1/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 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ữ gồm 2 chữ cái theo tiêu chuẩn ISO 639-1 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 chương trình khuyến mãi 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 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. Nếu thành công, 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.

Để tạo một 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 Quy trình phê duyệt chương trình khuyến mãi.

Bạn nên xem kỹ 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 mang lại giá trị và tuân thủ chính sách của 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:

HTTP

POST https://merchantapi.googleapis.com/promotions/v1/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}"
}

cURL

  curl --request POST \
'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions:insert?key=[YOUR_API_KEY]' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"dataSource":"{DATASOURCE_ID}","promotion":{"name":"accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}y","promotionId":"abc","contentLanguage":"en","targetCountry":"US","redemptionChannel":["ONLINE"]}}' \
--compressed

Để biết thông tin về các quy tắc áp dụng cho việc thiết lập mã khuyến mãi, hãy xem 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. Một thông báo lỗi tương tự sẽ được trả về 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, thì yêu cầu sẽ không thành công với phản hồi HTTP 400 [genericRedemptionCode] No redemption code provided.

Giá trị của 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 những 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 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 cho chương trình khuyến mãi.

Để xem 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 để chương trình khuyến mãi có thể truy xuất bằng API hoặc xuất hiện trong Merchant Center.

Dưới đây là một mẫu mà bạn có thể dùng để chèn nhiều chương trình khuyến mãi không đồng bộ:

Java

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.Timestamp;
import com.google.shopping.merchant.promotions.v1.Attributes;
import com.google.shopping.merchant.promotions.v1.CouponValueType;
import com.google.shopping.merchant.promotions.v1.InsertPromotionRequest;
import com.google.shopping.merchant.promotions.v1.OfferType;
import com.google.shopping.merchant.promotions.v1.ProductApplicability;
import com.google.shopping.merchant.promotions.v1.Promotion;
import com.google.shopping.merchant.promotions.v1.PromotionsServiceClient;
import com.google.shopping.merchant.promotions.v1.PromotionsServiceSettings;
import com.google.shopping.merchant.promotions.v1.RedemptionChannel;
import com.google.shopping.type.CustomAttribute;
import com.google.shopping.type.Destination.DestinationEnum;
import com.google.type.Interval;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert multiple promotions asynchronously. */
public class InsertPromotionsAsyncSample {

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static Promotion createPromotion(String accountId) {
    String merchantPromotionId = generateRandomString();

    Attributes attributes =
        Attributes.newBuilder()
            .setProductApplicability(ProductApplicability.ALL_PRODUCTS)
            .setOfferType(OfferType.GENERIC_CODE)
            .setGenericRedemptionCode("ABCD1234")
            .setLongTitle("My promotion")
            .setCouponValueType(CouponValueType.PERCENT_OFF)
            .addPromotionDestinations(DestinationEnum.SHOPPING_ADS)
            .setPercentOff(10)
            // Note that promotions have a 6-month limit.
            // For more information, read here: https://support.google.com/merchants/answer/2906014
            // Also note that only promotions valid within the past 365 days are shown in the UI.
            .setPromotionEffectiveTimePeriod(
                Interval.newBuilder()
                    .setStartTime(Timestamp.newBuilder().setSeconds(1726842472))
                    .setEndTime(Timestamp.newBuilder().setSeconds(1726842473))
                    .build())
            .build();

    return Promotion.newBuilder()
        .setName(String.format("accounts/%s/merchantPromotions/%s", accountId, merchantPromotionId))
        .setPromotionId(merchantPromotionId)
        .setContentLanguage("fr")
        .setTargetCountry("CH")
        .addRedemptionChannel(RedemptionChannel.ONLINE)
        .setAttributes(attributes)
        // Custom attributes allow you to add additional information which is not available in
        // Attributes. For example, you might want to pilot experimental functionality.
        .addCustomAttributes(
            CustomAttribute.newBuilder()
                .setName("another example name")
                .setValue("another example value")
                .build())
        .build();
  }

  public static void asyncInsertPromotions(String accountId, String dataSourceId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    PromotionsServiceSettings merchantPromotionsServiceSettings =
        PromotionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    try (PromotionsServiceClient merchantPromotionsServiceClient =
        PromotionsServiceClient.create(merchantPromotionsServiceSettings)) {

      // Arbitrarily creates five merchant promotions with random IDs.
      List<InsertPromotionRequest> requests = new ArrayList<>();
      for (int i = 0; i < 5; i++) {
        InsertPromotionRequest request =
            InsertPromotionRequest.newBuilder()
                .setParent(String.format("accounts/%s", accountId))
                .setPromotion(createPromotion(accountId))
                .setDataSource(String.format("accounts/%s/dataSources/%s", accountId, dataSourceId))
                .build();
        requests.add(request);
      }

      // Inserts the merchant promotions.
      List<ApiFuture<Promotion>> futures =
          requests.stream()
              .map(
                  request ->
                      merchantPromotionsServiceClient.insertPromotionCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<Promotion>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<Promotion>>() {
            @Override
            public void onSuccess(List<Promotion> results) {
              System.out.println("Inserted merchant promotions below:");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());
    } catch (Exception e) {
      System.out.println(e);
    }
  }


  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    asyncInsertPromotions(config.getAccountId().toString(), "<YOUR_DATA_SOURCE_ID>");
  }
}
InsertPromotionsAsyncSample.java

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.

Một chương trình khuyến mãi tại đị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 đị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 bạn đã thêm vào tài khoản Trang doanh nghiệp được liên kết.

POST https://merchantapi.googleapis.com/promotions/v1/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}"
}

Bạn bắt buộc phải điền vào trường productApplicability. 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ụ thể. 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.

Bạn bắt buộc phải điền vào trường couponValueType. Thuộc tính này 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 Loại giá trị của phiếu giảm giá. Tuỳ thuộc vào loại giá trị của 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 phải mua để sử dụng ưu đãi khuyến mãi. Để biết thêm thông tin, hãy xem bài viết 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 Quy cách nguồn dữ liệu cho chương trình khuyến mãi tại địa phương.

Một chương trình khuyến mãi trực tuyến áp dụng cho các 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 một chương trình khuyến mãi trực tuyến áp dụng cho các sản phẩm được chọn bằng mã sử dụng.

POST https://merchantapi.googleapis.com/promotions/v1/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. Bạn cần có merchantId và mã nhận dạng của chương trình khuyến mãi. Phương thức GET trả về tài nguyên khuyến mãi tương ứng.

Ví dụ:

HTTP

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

cURL

  curl \
   'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}?key=[YOUR_API_KEY]' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --compressed

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 được 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ã nhận dạng chương trình khuyến mãi là in_store~en~US~buy_2_get_10_off.

GET https://merchantapi.googleapis.com/promotions/v1/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 áp dụng trong chương trình khuyến mãi. Để biết thêm thông tin, hãy xem Số tiền chiết khấu bằng tiền 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 của 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ã khuyến mãi là online~en~US~25_pct_off.

GET https://merchantapi.googleapis.com/promotions/v1/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 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 bài viết Mã nhận dạng sản phẩm để khuyến mãi.

Khuyến mãi trong danh sách

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

Sau đây là một yêu cầu mẫu:

HTTP

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

cURL

  curl \
   'https://merchantapi.googleapis.com/promotions/v1/accounts/{ACCOUNT_ID}/promotions?key=[YOUR_API_KEY]' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --compressed

Phản hồi này 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 các 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 chưa bị dừng và tất cả các bài đánh giá đều được phê duyệt, nhưng ngày hoạt động là trong tương lai.
  • STATE_UNSPECIFIED: Trạng thái khuyến mãi không xác định.

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

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

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

Thiếu thông tin liên kết sản phẩm

Phần nội dung phản hồi sau đây cho thấy một chương trình khuyến mãi trực tuyến bị từ chối do thiếu thông tin 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 các 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 các vấn đề liên quan đến chương trình khuyến mãi bị từ chối.

Nếu chương trình khuyến mãi 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 cách 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": []
  }

Một 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 khuyến mãi.

Xoá chương trình khuyến mãi

Bạn không thể xoá chương trình khuyến mãi bằng API. Để xoá một chương trình khuyến mãi, bạn cần truy cập vào giao diện người dùng Merchant Center. Để biết thêm thông tin, hãy xem bài viết Chỉnh sửa chương trình khuyến mãi hoặc thay đổi trạng thái của chương trình khuyến mãi.

Để kết thúc một chương trình khuyến mãi hiện có, bạn có thể sử dụng phương thức accounts.promotions.insert để cập nhật trường attributes.promotionEffectiveTimePeriod.endTime thành một thời điểm trong quá khứ.

Tìm hiểu thêm