MerchantPromotions API 總覽

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

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

詳情請參閱「促銷活動 基本概念。

必要條件

Google 會要求您提供商家的特定資訊，以及 產品。您必須具備以下要件：

此外，你必須為商家帳戶註冊促銷活動計畫。如果 如果您不確定自己是否已註冊，請查看 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 和 宣傳。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

促銷活動狀態

如要查看促銷活動狀態，請查看 promotionStatus 屬性 傳回者： promotions.get敬上 和 promotions.list。

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

促銷活動狀態範例

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

範例 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 遷移，請參閱「遷移促銷活動 管理