MerchantPromotions API 總覽

使用促銷活動，宣傳你在 Google 上銷售的產品特價優惠。促銷活動會顯示在各項 Google 資源中，包括 Google 搜尋、購物和 Chrome。

只要為產品新增促銷活動，購物者就會看到特價優惠連結，例如「85 折」或「免運費」。優惠連結可提高產品吸引力，並鼓勵購物者購買。

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

必要條件

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

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

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

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

建立資料來源

使用 datasource.create API 建立促銷動態饋給。如果有現有的促銷動態饋給，請使用 accounts.dataSources.get 方法擷取資料來源的名稱。

要求的格式如下：

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

範例

這個範例顯示一般要求和回應。

要求：

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 資源和資料來源名稱做為輸入內容。如果成功，就會傳回新的或更新的促銷活動。

建立促銷活動時，需要提供資料來源的名稱。

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"
      },
      "minimumPurchaseQuantity": 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"
   },
   "minimumPurchaseQuantity": 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 遷移，請參閱遷移促銷活動管理功能。