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

MerchantPromotions API 總覽

您可以運用促銷活動，在 Google 上販售產品特價優惠。促銷活動會顯示在不同 Google 資源中，包括 Google 搜尋、購物和 Chrome。

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

詳情請參閱促銷活動基本資訊。

先備知識

請在顯示促銷活動之前，向 Google 提供貴商家和產品的特定資訊。您必須具備以下要件：

在 Google Merchant Center 中使用有效的產品動態饋給。
在 Google Merchant Center 中提供有效的促銷活動動態饋給。
Google Ads 帳戶用於購物廣告活動。

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

如果您尚未註冊，請填寫要求表單。促銷活動團隊會通知您何時可以開始導入作業。

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

建立資料來源

使用 datasource.create API 建立促銷活動動態饋給。如果有現有的促銷活動動態饋給，請使用 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。取得此項目為唯讀狀態。這需要您的 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 遷移，請參閱「遷移促銷活動管理」。