Ü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. Angebote müssen bestimmte Kriterien erfüllen, um genehmigt zu werden. Weitere Informationen finden Sie unter Kriterien für Werbung.

Wenn Sie Ihren Produkten ein Angebot hinzufügen, sehen Käufer einen Link zu einem Sonderangebot. Beispiel: „15% Rabatt“ oder „Kostenloser Versand“. Angebotslinks können die Attraktivität Ihrer Produkte steigern und Nutzer zum Kauf bewegen. Alle Angebote werden an der Kasse angewendet.

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

Mit der Methode accounts.dataSources.create können Sie eine Angebotsdatenquelle erstellen. Wenn eine vorhandene Angebotsdatenquelle verfügbar ist, verwenden Sie die Methode accounts.dataSources.list, um alle Datenquellen abzurufen. Anschließend können Sie mit dem Feld name der Angebotsdatenquelle Angebote erstellen.

In der folgenden Anfrage wird gezeigt, wie Sie eine Datenquelle zum Hinzufügen von Angeboten erstellen:

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

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

Ersetzen Sie Folgendes:

  • {ACCOUNT_ID}: Die eindeutige Kennung Ihres Kontos, wie sie in der Merchant Center-Benutzeroberfläche angezeigt wird.
  • {DISPLAY_NAME}: Der Anzeigename der Datenquelle.
  • {CONTENT_LANGUAGE}: Der aus zwei Buchstaben bestehende ISO 639-1-Sprachcode der Produkte in der Datenquelle.
  • {TARGET_COUNTRY}: Der CLDR-Territorialcode des Ziellandes, in dem die Angebote sichtbar sein sollen.

Nach Abschluss der Anfrage wird die folgende Antwort mit Details zur neu erstellten Angebotsdatenquelle angezeigt:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

Werbeaktionen erstellen

Mit der Methode accounts.promotions.insert können Sie ein Angebot erstellen oder aktualisieren. Die Methode accounts.promotions.insert 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. Außerdem müssen Sie in Ihrer Anfrage Werte für die folgenden Felder angeben:

  • contentLanguage
  • redemptionChannel
  • promotionId
  • targetCountry
  • attributes.offerType
  • attributes.genericRedemptionCode
  • attributes.couponValueType
  • attributes.productApplicability
  • attributes.promotionEffectiveTimePeriod.endTime
  • attributes.promotionEffectiveTimePeriod.startTime
  • attributes.longTitle

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

Wir empfehlen Ihnen, die Richtlinien für Angebote zu lesen, damit Sie sicher sein können, dass die von Ihnen erstellten Angebote einen Mehrwert bieten und den Richtlinien für Shopping-Anzeigen entsprechen.

In der folgenden Anfrage wird gezeigt, wie ein Onlineangebot erstellt wird:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

Informationen zu den Regeln für die Festlegung der Angebots-ID finden Sie unter Mindestanforderungen für das Angebots-ID-Attribut.

Gültige Werte für das obligatorische Feld offerType sind NO_CODE und GENERIC_CODE. Wenn Sie keinen dieser Werte angeben, schlägt die API-Anfrage mit der HTTP-400-Antwort [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type fehl. Eine ähnliche Fehlermeldung wird zurückgegeben, wenn Sie keines der Pflichtfelder ausfüllen.

Wenn Sie keinen Wert für das Feld attributes.genericRedemptionCode angeben, schlägt die Anfrage mit der HTTP-Antwort 400 [genericRedemptionCode] No redemption code provided fehl.

Die Werte für die Felder promotion.attributes.promotionDisplayTimePeriod.startTime und promotion.attributes.promotionDisplayTimePeriod.endTime müssen im Format yyyy-mm-ddThh:mm:ssZ angegeben werden. Achten Sie darauf, die Werte für diese Felder durch Datumsangaben in der Zukunft zu ersetzen.

Weitere Informationen finden Sie in der Spezifikation für Angebotsdaten.

Best Practices zum Erstellen von Angeboten finden Sie unter Best Practices für Angebote.

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

Nachdem die Anfrage zum Erstellen des Angebots erfolgreich ausgeführt wurde, kann es einige Minuten dauern, bis das Angebot über die API abgerufen oder im Merchant Center angezeigt wird.

Im Folgenden finden Sie einige Beispielangebote, die Sie als Ausgangspunkt verwenden können.

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

In der folgenden Beispielanfrage wird gezeigt, wie Sie ein lokales Angebot erstellen, das für alle Produkte in Ihrem Merchant Center-Konto und alle Geschäfte gilt, die in Ihrem verknüpften Unternehmensprofil-Konto hinzugefügt wurden.

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

productApplicability ist ein Pflichtfeld. Damit wird angegeben, ob das Angebot für alle Produkte oder nur für bestimmte Produkte gilt. Die unterstützten Werte sind ALL_PRODUCTS und SPECIFIC_PRODUCTS. Weitere Informationen finden Sie unter Produkte für Ihr Angebot auswählen.

couponValueType ist ein Pflichtfeld. Sie gibt an, welche Art von Angebot Sie schalten. Eine Liste der unterstützten Werte finden Sie unter Gutschein-Werttyp. Je nach ausgewähltem Gutscheinwert sind einige Attribute erforderlich.

Im Feld minimumPurchaseQuantity können Sie den Wert für die Mindestbestellmenge festlegen, die zum Einlösen des Angebots erforderlich ist. Weitere Informationen finden Sie unter Mindestbestellmenge für Angebot.

Ebenso können Sie mit dem Feld minimumPurchaseAmount den Mindestbestellwert festlegen, der für die Inanspruchnahme des Angebots erforderlich ist. Weitere Informationen finden Sie unter Mindestbestellwert.

Weitere Informationen zu den Werten, die Sie zum Erstellen eines lokalen Angebots angeben müssen, finden Sie unter Datenquellenspezifikationen für lokale Angebote.

Ein Onlineangebot, das für ausgewählte Produkte mit einem Gutscheincode gilt

In der folgenden Beispielanfrage wird gezeigt, wie Sie ein Onlineangebot erstellen, das für ausgewählte Produkte mit einem Gutscheincode gilt.

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

Werbeaktionen ansehen

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

Beispiel:

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

Ersetzen Sie Folgendes:

  • {ACCOUNT_ID}: Die eindeutige Kennung Ihres Merchant Center-Kontos.
  • {PROMOTION_ID}: Die eindeutige Kennung des Angebots, das Sie abrufen möchten. Das Format ist {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

Es kann einige Minuten dauern, bis ein neu erstelltes Angebot über die API abgerufen werden kann.

Lokales Angebot ansehen

In der folgenden Beispielanfrage wird ein lokales Angebot mit der Angebots-ID in_store~en~US~buy_2_get_10_off abgerufen.

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

Nach der erfolgreichen Anfrage wird die folgende Antwort angezeigt:

{
 "name": "accounts/{ACCOUNT_ID}/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/{ACCOUNT_ID}/dataSources/1000000573361824"
}

Das Feld moneyOffAmount in diesem Beispiel enthält den Rabatt, der im Angebot angeboten wird. Weitere Informationen finden Sie unter Der monetäre Rabattbetrag eines Angebots.

Das Feld promotionUrl in diesem Beispiel enthält den Link zur Website des Geschäfts, auf der Käufer weitere Informationen zur Werbeaktion finden. Bei Angeboten für Anzeigen mit lokalem Inventar wird ein Fehler zurückgegeben, wenn Sie das Feld promotionUrl nicht angeben.

Sie sehen sich ein Onlineangebot an.

In der folgenden Beispielanfrage wird ein Onlineangebot mit der Angebots-ID online~en~US~25_pct_off abgerufen.

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

Im Feld itemIdInclusion in diesem Beispiel werden die Produkte aufgeführt, die für das Angebot infrage kommen. Weitere Informationen finden Sie unter Produkt-ID für Werbung.

Angebote auflisten

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

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

Die Antwort enthält eine Liste aller Angebote in Ihrem Konto. Für jede Werbeaktion sehen Sie unter anderem Details wie promotionId, redemptionChannel, dataSource und promotionStatus.

Status einer Werbeaktion ansehen

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

Das Feld promotionStatus kann die folgenden Werte haben:

  • IN_REVIEW: Das Angebot wird noch geprüft.
  • REJECTED: Das Angebot wurde abgelehnt.
  • LIVE: Das Angebot ist genehmigt und aktiv.
  • STOPPED: Das Angebot wird vom Konto beendet.
  • EXPIRED: Das Angebot ist nicht mehr aktiv.
  • PENDING: Das Angebot ist nicht beendet und alle Überprüfungen wurden genehmigt, das Aktivierungsdatum liegt jedoch in der Zukunft.
  • STATE_UNSPECIFIED: Unbekannter Angebotsstatus.

Informationen zum Freigabeprozess für von Ihnen erstellte Angebote finden Sie unter Freigabeprozess für Angebote.

Beispiel für einen Angebotsstatus

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

Fehlende Produktzuordnung

Im folgenden Antworttext wird eine Onlinewerbung angezeigt, die aufgrund fehlender Produktzuordnung abgelehnt wurde.

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

Informationen zur Fehlerbehebung bei abgelehnten Angeboten und dazu, wie Sie zukünftige Ablehnungen vermeiden können, finden Sie unter Probleme mit abgelehnten Angeboten beheben.

Wenn ein von Ihnen erstelltes Angebot nicht genehmigt wird, erhalten Sie eine E-Mail mit dem Grund für die Ablehnung und einer Anleitung zur Behebung der Probleme.

Angebot wird geprüft

Der folgende Antworttext zeigt ein Angebot, das noch bewertet wird.

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

Eine genehmigte und aktive Werbeaktion

Der folgende Antworttext zeigt ein Angebot, das für Käufer sichtbar ist.

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

Weitere Informationen finden Sie in den häufig gestellten Fragen zum Angebotsstatus.

Weitere Informationen