此页面由 Cloud Translation API 翻译。

MerchantPromotion API 概览

利用促销活动来展示您在 Google 上销售的商品的特别优惠。促销活动会显示在 Google 搜索、Google 购物和 Chrome 等各种 Google 产品和服务中。

当您为商品添加促销活动时，买家会看到一个特别优惠链接，例如“八五折优惠”或“免运费”。优惠链接可以提高商品的吸引力，并鼓励买家进行购买。

如需了解详情，请参阅促销基础知识。

前提条件

Google 需要您提供有关您的商家和商品的具体信息，然后才能展示促销活动。必须具备以下条件：

此外，您还必须为自己的商家账号注册促销活动计划。如果您不确定自己是否已注册，请查看 Merchant Center。

如果您尚未注册，请填写申请表。当您可以开始实施时，推广团队会通知您。

如需了解详情，请参阅参与条件和政策。

创建数据源

使用 datasource.create API 创建促销信息 Feed。如果现有的促销信息 Feed 可用，请使用 datasource.get 提取 datasource.name

请求的形式如下所示：

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{account}/dataSources/{datasource}

示例

该示例显示了一个典型的请求和响应。

请求：

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/123/dataSources {"displayName": "test api feed", "promotionDataSource":{"targetCountry":"US", "contentLanguage":"en"}}

响应：

{
  "name": "accounts/123/dataSources/1000000573361824",
  "dataSourceId": "1000000573361824",
  "displayName": "test api feed",
  "promotionDataSource": {
    "targetCountry": "US",
    "contentLanguage": "en"
  },
  "input": "API"
}

创建促销活动

您可以使用 accounts.promotions.insert 方法创建或更新促销活动。accounts.promotions.insert 方法将 promotions 资源和数据源名称作为输入。如果成功，则返回新的或更新后的促销活动。

创建促销活动需要 datasource.name。

Google 会审核并批准您的促销活动，然后再进行分发。如需了解详情，请参阅促销活动审批流程。

请求的形式：

POST https://merchantapi.googleapis.com/promotions/v1beta/{parent=accounts/*/}promotions:insert

请参考以下示例促销活动。

示例 1：适用于所有商品和所有商店的本地促销活动

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/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"
      },
      "minimum_purchase_quantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/123/dataSources/1000000573361824"
}

示例 2：使用兑换码应用于选定商品的线上促销活动

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/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/123/dataSources/1000000573361824"
}

特别说明

创建促销活动后，可能需要几分钟时间才能创建完成。

如需查看与促销活动相关的属性的列表，请参阅添加结构化数据属性。

在创建和管理促销活动之前，请参阅促销活动最佳做法。

查看推广活动

如需查看促销活动，请使用 accounts.promotions.get。此 get 为只读。其中需要提供您的 merchantId 和促销活动的 ID。get 方法会返回相应的促销信息资源。

例如：

GET https://merchantapi.googleapis.com/promotions/v1beta/{name=accounts/*/promotions/*}

请研究这些示例。

示例 1：本地促销活动

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

{
 "name": "accounts/123/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"
   },
   "minimum_purchase_quantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/123/dataSources/1000000573361824"
}

示例 2. 线上促销活动

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/123/promotions/online~en~US~25_pct_off
{
 "name": "accounts/123/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}/dataSources/{dataSource}"
}

列出促销信息

您可以使用 promotions.list 方法查看所有已创建的促销活动。

GET https://merchantapi.googleapis.com/promotions/v1beta/{parent=accounts/*}/promotions

促销状态

如需查看促销活动的状态，您可以查看由 promotions.get 和 promotions.list 返回的 promotionStatus 属性。

如需了解审批流程，请参阅促销活动审批流程。

促销状态示例

以下示例展示了成功请求和失败请求之间的区别。

示例 1. 以下响应正文显示了因缺少商品映射而被拒的在线促销。

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

示例 2. 以下响应正文显示了已批准的促销。

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

示例 3. 已获批准的有效促销活动

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

了解详情

如需了解详情，请参阅促销活动帮助中心。

如需了解如何从 Content API for Shopping 迁移，请参阅迁移促销活动管理。