此页面由 Cloud Translation API 翻译。

MerchantPromotion API 概览

使用促销信息展示您在 Google 上销售的商品的特别优惠。促销活动会在各种 Google 产品和服务中展示，包括 Google 搜索、Google 购物和 Chrome。促销活动必须符合特定条件才能获得批准。如需了解详情，请参阅促销活动条件。

当您为商品添加促销信息后，买家会看到一个“特别优惠”链接。例如，“八五折”或“免运费”。商品链接可以提高商品的吸引力，并鼓励买家购买。所有促销优惠均在结账时或在销售终端应用。

如需了解详情，请参阅推广活动基础知识。

前提条件

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}：您的账号的唯一标识符（如 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}：您的 Merchant Center 账号的唯一标识符。
{PROMOTION_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": []
  }

如需了解详情，请参阅推广活动状态常见问题解答。

了解详情

如需了解详情，请访问促销活动帮助中心。
如需排查常见问题，请参阅排查与 Merchant Promotions API 相关的问题。
如需了解如何从 Content API for Shopping 迁移，请参阅迁移促销活动管理。