Übersicht über die Merchant Promotions API

Mit Angeboten können Sie Sonderangebote für Produkte präsentieren, die Sie auf Google verkaufen. Angebote werden in verschiedenen Google-Produkten wie der Google Suche, Shopping und Chrome präsentiert.

Wenn Sie Ihren Produkten Angebote hinzufügen, sehen Käufer einen Link zu einem Sonderangebot, z. B. „15% Rabatt“ oder „Kostenloser Versand“. Angebotslinks können die Attraktivität Ihrer Produkte steigern und Nutzer zum Kauf bewegen.

Weitere Informationen finden Sie unter Grundlagen von Angeboten.

Vorbereitung

Google benötigt bestimmte Informationen zu Ihrem Unternehmen und zu Ihren Produkten, damit Ihre Angebote angezeigt werden können. Sie benötigen Folgendes:

Außerdem müssen Sie Ihr Händlerkonto für das Angebotsprogramm registrieren. Wenn Sie nicht sicher sind, ob Sie bereits registriert sind, sehen Sie im Merchant Center nach.

Wenn Sie noch nicht registriert sind, füllen Sie das Anfrageformular aus. Das Promotions-Team informiert Sie, sobald Sie mit der Implementierung beginnen können.

Weitere Informationen finden Sie unter Teilnahmekriterien und Richtlinien.

Datenquelle erstellen

Verwenden Sie die API datasource.create, um einen Angebotsfeed zu erstellen. Wenn ein vorhandener Angebotsfeed verfügbar ist, verwenden Sie die Methode accounts.dataSources.get, um den Namen der Datenquelle abzurufen.

Die Anfrage hat folgendes Format:

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

Beispiel

Das Beispiel zeigt eine typische Anfrage und Antwort.

Anfrage:

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

Response:

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

Werbeaktionen erstellen

Sie können die Methode accounts.promotions.insert verwenden, um ein Angebot zu erstellen oder zu aktualisieren. Die accounts.promotions.insert-Methode nimmt eine promotions-Ressource und einen Datenquellennamen als Eingabe an. Bei Erfolg wird das neue oder aktualisierte Angebot zurückgegeben.

Zum Erstellen eines Angebots ist der Name der Datenquelle erforderlich.

Google überprüft und genehmigt Ihre Angebote, bevor sie veröffentlicht werden. Weitere Informationen finden Sie im Hilfeartikel Freigabeprozess für Angebote.

Das Formular der Anfrage:

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

Sehen Sie sich die folgenden Beispielangebote als Referenz an.

Beispiel 1: Ein lokales Angebot, das für alle Produkte und alle Geschäfte gilt

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

Beispiel 2: Ein Onlineangebot für ausgewählte Produkte mit einem Gutscheincode

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

Besondere Hinweise

Nach dem Erstellen des Angebots kann es einige Minuten dauern, bis es in der Shopping-Datenbank angezeigt wird.

Eine Liste der angebotsbezogenen Attribute finden Sie unter Attribute für strukturierte Daten hinzufügen.

Bevor Sie Angebote erstellen und verwalten, sollten Sie sich die Best Practices für Angebote ansehen.

Werbeaktionen ansehen

Verwenden Sie accounts.promotions.get, um sich ein Angebot anzusehen. Dieser Get-Vorgang ist schreibgeschützt. Sie benötigen Ihre merchantId und die ID des Angebots. Die Methode get gibt die entsprechende Angebotsressource zurück.

Beispiel:

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

Sehen Sie sich diese Beispiele an.

Beispiel 1: Lokales Angebot

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

Beispiel 2 Onlineangebot

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

Angebote auflisten

Mit der Methode promotions.list können Sie sich alle erstellten Angebote ansehen.

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

Angebotsstatus

Den Status eines Angebots finden Sie im Attribut promotionStatus, das von promotions.get und promotions.list zurückgegeben wird.

Weitere Informationen zum Freigabeprozess finden Sie im Hilfeartikel Freigabeprozess für Angebote.

Beispiel für einen Angebotsstatus

Die folgenden Beispiele zeigen den Unterschied zwischen erfolgreichen und fehlgeschlagenen Anfragen.

Beispiel 1: Der folgende Antworttext zeigt ein Onlineangebot, das aufgrund fehlender Produktzuordnung abgelehnt würde.

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

Beispiel 2 Im folgenden Antworttext wird ein Angebot angezeigt, das noch geprüft wird.

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

Beispiel 3: Ein genehmigtes und aktives Angebot

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

Weitere Informationen

Weitere Informationen finden Sie in der Hilfe zu Angeboten.

Informationen zur Migration von der Content API for Shopping finden Sie unter Migration der Angebotsverwaltung.