本頁面由 Cloud Translation API 翻譯而成。

MerchantPromotions API 總覽

使用促銷活動，宣傳你在 Google 上銷售的產品特價優惠。促銷活動會顯示在各項 Google 資源中，包括 Google 搜尋、購物和 Chrome。促銷活動必須符合特定條件才能獲得核准。詳情請參閱「宣傳條件」一文。

為產品新增促銷活動後，購物者就會看到特價優惠連結。例如「9 折」或「免運費」。優惠連結可提高產品吸引力，並鼓勵購物者購買。所有促銷活動只能在結帳時或銷售點使用。

詳情請參閱「宣傳活動基本資訊」。

必要條件

商家須提供與自身業務和產品相關的資訊，Google 才會顯示商家的促銷活動。您必須具備下列條件：

此外，你必須將商家帳戶加入促銷活動計畫。如果不確定是否已註冊，請前往 Merchant Center 查看。

如果您尚未註冊，請填寫申請表單。促銷活動團隊會通知你何時可以開始實施。

詳情請參閱「參加條件與政策」。

建立資料來源

您可以使用 accounts.dataSources.create 方法建立促銷活動資料來源。如果有現有的促銷活動資料來源，請使用 accounts.dataSources.list 方法擷取所有資料來源。接著，您可以使用促銷活動資料來源的 name 欄位建立促銷活動。

以下要求說明如何建立資料來源，以便新增促銷活動：

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

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

更改下列內容：

{ACCOUNT_ID}：帳戶的專屬 ID，會顯示在 Merchant Center 使用者介面中。
{DISPLAY_NAME}：資料來源的顯示名稱。
{CONTENT_LANGUAGE}：資料來源中產品的雙字母 ISO 639-1 語言代碼。
{TARGET_COUNTRY}：您希望顯示促銷活動的目標國家/地區的 CLDR 地域代碼。

要求執行成功後，您會看到以下回應，其中包含新建立的宣傳活動資料來源的詳細資料：

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

舉辦宣傳活動

您可以使用 accounts.promotions.insert 方法建立或更新促銷活動。accounts.promotions.insert 方法會將 promotions 資源和資料來源名稱做為輸入內容。如果成功，就會傳回新的或更新的促銷活動。

建立促銷活動時，需要提供資料來源的名稱。您也必須在要求中提供下列欄位的值：

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

Google 會先審查並核准促銷活動，才會予以發布。詳情請參閱「促銷活動核准程序」。

建議您詳閱促銷活動政策，確保您建立的促銷活動能為消費者帶來價值，並符合購物廣告政策。

以下要求示範如何建立線上促銷活動：

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}"
}

如要瞭解設定促銷 ID 時適用的規則，請參閱「促銷 ID 屬性的基本規定」。

強制規定的 offerType 欄位有效值為 NO_CODE 和 GENERIC_CODE。如果您未提供上述任一值，API 要求就會失敗，並傳回 HTTP 400 回應 [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type。如果您未提供任何必要欄位，系統也會傳回類似的錯誤訊息。

如果您未提供 attributes.genericRedemptionCode 欄位的值，要求就會失敗，並傳回 HTTP 400 回應 [genericRedemptionCode] No redemption code provided。

promotion.attributes.promotionDisplayTimePeriod.startTime 和 promotion.attributes.promotionDisplayTimePeriod.endTime 欄位的值必須採用 yyyy-mm-ddThh:mm:ssZ 格式。請務必將這些欄位的值替換為未來的日期。

詳情請參閱宣傳活動資料規格。

如要瞭解建立促銷活動的最佳做法，請參閱「促銷活動最佳做法」。

如需促銷活動相關屬性清單，請參閱「新增結構化資料屬性」。

促銷活動建立要求執行成功後，可能需要幾分鐘的時間，才能透過 API 擷取促銷活動，或在 Merchant Center 中顯示促銷活動。

以下是可用於非同步插入多個促銷活動的範例：

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.v1beta.Attributes;
import com.google.shopping.merchant.promotions.v1beta.CouponValueType;
import com.google.shopping.merchant.promotions.v1beta.InsertPromotionRequest;
import com.google.shopping.merchant.promotions.v1beta.OfferType;
import com.google.shopping.merchant.promotions.v1beta.ProductApplicability;
import com.google.shopping.merchant.promotions.v1beta.Promotion;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceClient;
import com.google.shopping.merchant.promotions.v1beta.PromotionsServiceSettings;
import com.google.shopping.merchant.promotions.v1beta.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

以下列舉一些可供你參考的促銷活動範例。

適用於所有產品和所有商店的店面促銷活動

以下範例要求說明如何建立店面促銷活動，適用於 Merchant Center 帳戶中的所有產品，以及已新增至連結商家檔案帳戶中的所有商店。

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}"
}

productApplicability 欄位為必填欄位。這項屬性可用來指明促銷活動是否適用於所有產品，或是僅限特定產品。支援的值為 ALL_PRODUCTS 和 SPECIFIC_PRODUCTS。詳情請參閱「選擇促銷活動的產品」一文。

couponValueType 欄位為必填欄位。這會指出你正在放送的促銷活動類型。如需支援的值清單，請參閱「優待券值類型」。視所選優待券值類型而定，部分屬性為必填屬性。

minimumPurchaseQuantity 欄位可讓您設定兌換促銷優惠所需的最低購買數量。詳情請參閱「促銷活動最低購買數量」。

同樣地，您也可以使用 minimumPurchaseAmount 欄位，設定兌換促銷活動所需的最低消費金額。詳情請參閱「最低購買金額」。

如要進一步瞭解建立店面促銷活動時需要提供的值，請參閱「店面促銷活動的資料來源規格」。

線上促銷活動，適用於特定產品，並提供兌換代碼

以下示例要求說明如何建立適用於特定兌換代碼產品的線上促銷活動。

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"
}

查看促銷優惠

如要查看促銷活動，請使用 accounts.promotions.get。這個 GET 要求是唯讀的。您需要提供 merchantId 和促銷活動 ID。GET 方法會傳回對應的促銷活動資源。

例如：

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

更改下列內容：

{ACCOUNT_ID}：商家中心帳戶的專屬 ID。
{PROMOTION_ID}：您要擷取的促銷活動專屬 ID。格式為 {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}。

請注意，使用 API 擷取新建立的促銷活動需要幾分鐘的時間。

查看店面促銷活動

以下範例要求會擷取促銷活動 ID 為 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

要求成功後，您會看到下列回應：

{
 "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"
}

這個範例中的 moneyOffAmount 欄位會提供促銷活動提供的折扣。詳情請參閱「促銷活動的金錢折扣金額」。

這個範例中的 promotionUrl 欄位提供商店網站的連結，購物者可在該網站上進一步瞭解促銷活動。如果未加入 promotionUrl 欄位，本地商品目錄廣告宣傳活動會傳回錯誤。

查看線上促銷活動

以下範例要求會擷取促銷活動 ID 為 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}"
}

這個範例中使用的 itemIdInclusion 欄位會提及符合促銷活動資格的產品。詳情請參閱「促銷活動的產品 ID」。

列出促銷活動

您可以使用 promotions.list 方法查看所有已建立的促銷活動。

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

回應內容包含帳戶中的所有促銷活動清單。您可以查看每項促銷活動的詳細資料，例如 promotionId、redemptionChannel、dataSource、promotionStatus 等。

查看促銷活動狀態

如要查看促銷活動的狀態，請查看 promotions.get 或 promotions.list 方法傳回的 promotionStatus 屬性。

promotionStatus 欄位可包含下列值：

IN_REVIEW：促銷活動仍在審查中。
REJECTED：促銷活動遭拒登。
LIVE：優惠活動已核准並生效。
STOPPED：帳戶已停止促銷活動。
EXPIRED：促銷活動已結束。
PENDING：促銷活動未停止，且所有審查都已核准，但生效日期在未來。
STATE_UNSPECIFIED：不明的促銷活動狀態。

如要瞭解所建立促銷活動的核准程序，請參閱「促銷活動核准程序」。

促銷活動狀態範例

以下範例說明成功和失敗的要求之間的差異。

缺少產品對應

以下回應主體顯示因缺少產品對應而遭拒的線上促銷活動。

  "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"
        ]
      }
    ]
  }

如要排解遭拒的促銷活動，並瞭解如何避免日後遭拒，請參閱「修正遭拒促銷活動的問題」。

如果您建立的促銷活動未獲核准，我們會傳送電子郵件通知您，信中會說明拒絕原因，並提供修正問題的指示。

正在評估的促銷活動

以下回應主體顯示仍在評估中的促銷活動。

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

已核准且正在進行的促銷活動

以下回應主體顯示購物者可見的促銷活動。

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

詳情請參閱「宣傳活動狀態常見問題」。

瞭解詳情

詳情請參閱促銷活動說明中心。
如要排解常見問題，請參閱「排解商家宣傳活動 API 相關問題」。
如要瞭解如何從 Content API for Shopping 遷移，請參閱遷移促銷活動管理功能。