Offers API

Die Offers API ist derzeit noch Teil eines geschlossenen Betaprogramms, das nur für eingeladene Teilnehmer*innen verfügbar ist. Bitte deine*n Meta-Vertreter*in um Zugriff, falls du zum Programm eingeladen wurdest.

Mit dieser API kannst du Angebotsinformationen zu deinem Produktkatalog hinzufügen, um die Vermarktung deiner Angebote auf Facebook und Instagram zu ermöglichen. Bei Verkäufer*innen mit aktiviertem Facebook- oder Instagram-Checkout können Käufer*innen Angebote direkt in der Meta-App-Familie einlösen.

Angebote erstellen

Du kannst Angebote über einen Angebots-Feed oder manuell mit dem Commerce Manager erstellen.

Feed

Um einen neuen Angebots-Feed zu erstellen, sende eine POST-Anfrage an die /{product_catalog_id}/product_feeds-Edge und setze feed_type auf OFFER. Beim Posten an diese Edge wird ein Produkt-Feed für Angebote für den im Feld product_catalog_id angegebenen Katalog erstellt.

Nach der Erstellung des Angebots-Feeds kannst du deine Angebotsdaten über eine POST-Anfrage an die /{product_feed_id}/uploads-Edge hochladen.

Feed-Spalten

Du kannst die meisten der unten aufgeführten verfügbaren Felder in deiner Feed-Datei als Spalten festlegen. Lediglich die als schreibgeschützt markierten Felder können bei der Erstellung nicht festgelegt werden.

Glossar

Produktauswahl

Eine Produktauswahl ist eine Gruppe von verwandten Artikeln in einem Produktkatalog.

Angebotszielartikel

Für diese Produkte gilt das Angebot.

Angebotsvoraussetzungen

Diese Voraussetzungen müssen für das Angebot erfüllt sein. Du kannst beispielsweise festlegen, dass das Angebot nur gültig ist, wenn Personen eine bestimmte Mindestmenge kaufen oder mindestens eine bestimmte Zwischensumme in diesen Produkten erreichen. Derzeit werden die erforderlichen Produkte aus den Zielprodukten abgeleitet. Bei einem Angebot für 20 % Rabatt für alle Schuhe muss beispielsweise die Mindestzwischensumme/-menge mit den Schuhen im Einkaufswagen erreicht werden.

Anwendungstyp des Angebots

Damit wird angegeben, wie ein Angebot beim Kaufabschluss auf deiner eigenen Website oder beim Kaufvorgang auf Facebook angewendet wird. Mit dem Anwendungstyp kannst du beispielsweise festlegen, ob ein Angebot beim Kaufabschluss automatisch angewendet wird oder ein Gutscheincode dafür eingelöst werden muss. Der Anwendungstyp bestimmt auch die Kombinationsmöglichkeiten eines Angebots mit anderen Angeboten. Mehr dazu erfährst du unter Angebote kombinieren.

Grundlegende Felder

Die folgenden Felder können für alle Angebotsarten konfiguriert werden.

Feld Beschreibung

Feld	Beschreibung
`id` Typ: `numeric string`	Schreibgeschützt. Eine eindeutige ID (Facebook-ID) für diesen Artikel.
`offer_id` Typ: `string`	Erforderlich. Eine von den Verkäufer*innen angegebene ID für das Angebot. Mit diesem Feld wird ein Angebot in einem Katalog eindeutig identifiziert.
`title` Typ: `string`	Optional. Ein Titel für den Angebotsartikel. Dieser Titel wird momentan nur verwendet, um Angebote im Commerce Manager zu identifizieren. Er wird Käufer*innen nicht angezeigt.
`description` Typ: `string`	Schreibgeschützt. Die automatisch erstellte Beschreibung des Angebots.
`application_type` Typ: `enum{SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED}`	Erforderlich. Bestimmt, wie und wann ein Angebot angewendet wird. Verfügbare Optionen: `SALE`: Artikel werden direkt rabattiert und mit durchgestrichenen Originalpreisen angezeigt. Für diese Angebote müssen Käuferinnen keine Voraussetzungen erfüllen und sie werden nicht von anderen Artikeln beim Kaufabschluss beeinträchtigt. Es wird immer der niedrigste Verkaufspreis für einen Artikel ausgewählt, da Sales nie kombiniert werden. Sales können mit anderen Angebotstypen kombiniert werden, werden aber immer zuerst angewendet. Wenn das Feld `sale_price` für ein Produkt bereits festgelegt ist, wird der Endpreis mit `sale_price` als Basispreis berechnet. `AUTOMATIC_AT_CHECKOUT`: Das Angebot wird beim Kaufabschluss automatisch angewendet, sofern die erforderlichen Kriterien zum Einlösen erfüllt sind. Die Konfiguration dieses Angebots verhindert die Einstufung als Sale. Es kann nur mit Sale-Angeboten kombiniert werden. Es können jeweils bis zu 25 Angebote dieser Art aktiv sein. `BUYER_APPLIED`: Dieses Angebot wird beim Kaufabschluss angewendet, wenn die Käuferinnen eine bestimmte Handlung ausführen, wie die Eingabe eines Aktionscodes. Diese Angebot können derzeit nicht miteinander oder mit Angeboten kombiniert werden, die automatisch beim Kaufabschluss angewendet werden. Dafür muss eine der folgenden Optionen angegeben werden: [`public_coupon_code`, `coupon_codes`].
`coupon_codes` Typ: `Array<string>`	Liste mit Gutscheincodes, die Kund*innen beim Kaufabschluss verwenden, um das Angebot einzulösen (ohne Beachtung der Groß-/Kleinschreibung). Maximal 100 Gutscheincodes sind zulässig. Beispiel: `["10OFF", "HOLIDAY_SALE"]` Gutscheincodes können nur angegeben werden, wenn der `application_typeBUYER_APPLIED` lautet. Wenn du dieses Feld festlegst, muss `public_coupon_code` Null sein.
`public_coupon_code` Typ: `string`	Optional. Ein einzelner Gutscheincode (ohne Beachtung der Groß-/Kleinschreibung), der mit dem Angebot vermarktet und beim Kaufabschluss vorausgefüllt wird, wenn die Käuferinnen die Voraussetzungen erfüllen. Standardmäßig werden Angebote mit Gutscheincodes nicht sichtbar an Käuferinnen auf Facebook- oder Instagram-Einkaufsoberflächen wie Produktdetailseiten vermarktet. Damit soll verhindert werden, dass private oder geheime Codes unbeabsichtigt offengelegt werden. Du kannst dieses Verhalten ändern, indem du einen öffentlichen Gutscheincode für die Vermarktung deines Angebots angibst. Angebote mit öffentlichen Codes werden genauso wie Angebote mit dem `application_typeAUTOMATIC_AT_CHECKOUT` angezeigt, enthalten aber auch den Codetext. Ein öffentlicher Gutscheincode darf höchstens 20 Zeichen lang sein. Außerdem darf dein Katalog jeweils höchstens 10 aktive Angebote mit öffentlichen Gutscheincodes enthalten. Öffentliche Gutscheincodes können nur festgelegt werden, wenn der `application_typeBUYER_APPLIED` lautet. Wenn du dieses Feld festlegst, muss `coupon_codes` Null sein.
`start_date_time` Typ: `timestamp`	Erforderlich. Unix-Zeitstempel des Angebotsbeginns in Sekunden. Du kannst einen Unix-Zeitstempel in Sekunden oder einen Datums-String im ISO-8601-Format (z. B. 2021-09-25T12:34:56Z) eingeben.
`end_date_time` Typ: `timestamp`	Optional. Ist standardmäßig `null`. Unix-Zeitstempel des Angebotsendes in Sekunden. Wenn dieser Wert leer oder `null` ist, läuft das Angebot unbegrenzt. Du kannst einen Unix-Zeitstempel in Sekunden oder einen Datums-String im ISO-8601-Format (z. B. 2021-09-25T12:34:56Z) eingeben.
`min_quantity` Typ: `int64`	Optional. Ist standardmäßig 0. Verwende dieses Feld, wenn dein Angebot nur gültig ist, wenn Kund*innen eine bestimmte Mindestanzahl von Produkten kaufen. Dieses Feld enthält die Anzahl der Produkte, die gekauft werden müssen, damit das Angebot in Kraft tritt. Beispiel: „20 % Rabatt beim Kauf von 5 T-Shirts“. Du kannst entweder `min_quantity` oder `min_subtotal` festlegen, aber nicht beides.
`min_subtotal` Typ: `string`	Optional. Ist standardmäßig `null`. Verwende dieses Feld, wenn dein Angebot nur gültig ist, wenn die Bestellung einen bestimmten Zwischensummenwert erreicht. Die Zwischensumme der erforderlichen Produkte muss größer oder gleich diesem Wert sein, damit das Angebot in Kraft tritt. Wenn du keine expliziten erforderlichen Produkte festlegst, werden die Zielprodukte als erforderliche Produkte verwendet. Dieses Feld muss als Betrag und dreistelliger ISO-Währungscode mit einem Leerzeichen dazwischen formatiert werden. Beispiel: Der String „30,99 EUR“ gibt an, dass eine Zwischensumme von 30,99 € erfüllt sein muss, damit das Angebot angewendet wird. Du kannst entweder `min_quantity` oder `min_subtotal` festlegen, aber nicht beides.
`redeem_limit_per_user` Typ: `int64`	Optional. Ist standardmäßig 0 (unbegrenzt). Gibt an, wie oft das Angebot maximal von einzelnen Nutzer*innen verwendet werden kann. Setze dieses Feld auf 1, um festzulegen, dass ein Gutscheincode nur einmal eingelöst werden kann. Dieses Feld sollte nur festgelegt werden, wenn `application_typeBUYER_APPLIED` lautet.
`value_type` Typ: `enum {FIXED_AMOUNT, PERCENTAGE}`	Erforderlich. Der Typ des Rabatts durch das Angebot. Verfügbare Optionen: `FIXED_AMOUNT`: Wendet einen Rabatt an, dessen Wert von `fixed_amount_off` abgeleitet wird. `PERCENTAGE`: Wendet einen prozentualen Rabatt an, dessen Wert von `percent_off` abgeleitet wird.
`fixed_amount_off` Typ: `string`	Erforderlich, wenn `value_type` auf `FIXED_AMOUNT` gesetzt ist. Der Rabattbetrag des Angebots. Muss als Betrag und dreistelliger ISO-Währungscode mit einem Leerzeichen dazwischen formatiert werden. Beispiel: Der String „30,99 EUR“ gibt einen Rabatt von 30,99 € an. Dieses Feld sollte nur festgelegt werden, wenn `value_typeFIXED_AMOUNT` lautet.
`percent_off` Typ: `int64`	Erforderlich, wenn `value_type` auf `PERCENTAGE` gesetzt ist. Der prozentuale Rabatt des Angebots. Muss eine Ganzzahl zwischen 0 und 100 sein. „30“ gibt beispielsweise einen Rabatt von 30 % an. Das Feld sollte nur festgelegt werden, wenn `value_typePERCENTAGE` lautet.
`target_granularity` Typ: `enum {ITEM_LEVEL, ORDER_LEVEL}`	Erforderlich. Die Granularität, mit der der Angebotsrabatt angewendet wird. Verfügbare Optionen: `ITEM_LEVEL`: Gibt an, dass ein Rabatt auf jeden der Zielartikel im Einkaufswagen angewendet wird. `ORDER_LEVEL`: Gibt an, dass ein Rabatt auf alle Zielartikel im Einkaufswagen gesammelt angewendet wird. Angenommen, das Angebot lautet „30 € Rabatt auf Schuhe“ und es liegen 3 Paar Schuhe im Einkaufswagen. In diesem Fall ziehst du mit `ITEM_LEVEL` 30 € von jedem Paar ab (Wert von 90 €), während du mit `ORDER_LEVEL` 30 € von der Summe der drei Paare abziehst (maximal 30 €). Beachte, dass Angebote mit der Granularität `ORDER_LEVEL` zu einer Rabattzuteilung beim Kauf führen können, die sich nicht gleichmäßig auf Artikel in einer Bestellung aufteilen lässt. Diese ungleichmäßigen Rabattzuteilungen können mehr Komplexität bei der Abwicklung oder im Falle von Rückerstattungen zur Folge haben.
`offer_terms` Typ: `string`	Optional. Alle weiteren Nutzungsbedingungen, die für die Verwendung eines Angebots gelten. Maximal 2.500 Zeichen. Facebook generiert automatisch Bedingungen für das Angebot basierend auf der Angebotskonfiguration. Zusätzlich zu diesen Bedingungen kannst du `offer_terms` verwenden, um deine eigenen Bedingungen für das Angebot zu beschreiben. Diese Bedingungen werden unter den Angebotsbedingungen von Facebook angezeigt. Ihr Inhalt muss unsere Content-Richtlinie einhalten.

id

Typ: numeric string

Schreibgeschützt.

Eine eindeutige ID (Facebook-ID) für diesen Artikel.

offer_id

Typ: string

Erforderlich.

Eine von den Verkäufer*innen angegebene ID für das Angebot.

Mit diesem Feld wird ein Angebot in einem Katalog eindeutig identifiziert.

title

Typ: string

Optional.

Ein Titel für den Angebotsartikel.

Dieser Titel wird momentan nur verwendet, um Angebote im Commerce Manager zu identifizieren. Er wird Käufer*innen nicht angezeigt.

description

Typ: string

Schreibgeschützt.

Die automatisch erstellte Beschreibung des Angebots.

application_type

Typ: enum{SALE, AUTOMATIC_AT_CHECKOUT, BUYER_APPLIED}

Erforderlich.

Bestimmt, wie und wann ein Angebot angewendet wird. Verfügbare Optionen:

SALE: Artikel werden direkt rabattiert und mit durchgestrichenen Originalpreisen angezeigt. Für diese Angebote müssen Käufer*innen keine Voraussetzungen erfüllen und sie werden nicht von anderen Artikeln beim Kaufabschluss beeinträchtigt. Es wird immer der niedrigste Verkaufspreis für einen Artikel ausgewählt, da Sales nie kombiniert werden. Sales können mit anderen Angebotstypen kombiniert werden, werden aber immer zuerst angewendet. Wenn das Feld sale_price für ein Produkt bereits festgelegt ist, wird der Endpreis mit sale_price als Basispreis berechnet.
AUTOMATIC_AT_CHECKOUT: Das Angebot wird beim Kaufabschluss automatisch angewendet, sofern die erforderlichen Kriterien zum Einlösen erfüllt sind. Die Konfiguration dieses Angebots verhindert die Einstufung als Sale. Es kann nur mit Sale-Angeboten kombiniert werden. Es können jeweils bis zu 25 Angebote dieser Art aktiv sein.
BUYER_APPLIED: Dieses Angebot wird beim Kaufabschluss angewendet, wenn die Käufer*innen eine bestimmte Handlung ausführen, wie die Eingabe eines Aktionscodes. Diese Angebot können derzeit nicht miteinander oder mit Angeboten kombiniert werden, die automatisch beim Kaufabschluss angewendet werden. Dafür muss eine der folgenden Optionen angegeben werden: [public_coupon_code, coupon_codes].

coupon_codes

Typ: Array<string>

Liste mit Gutscheincodes, die Kund*innen beim Kaufabschluss verwenden, um das Angebot einzulösen (ohne Beachtung der Groß-/Kleinschreibung). Maximal 100 Gutscheincodes sind zulässig. Beispiel: ["10OFF", "HOLIDAY_SALE"]

Gutscheincodes können nur angegeben werden, wenn der application_typeBUYER_APPLIED lautet.

Wenn du dieses Feld festlegst, muss public_coupon_code Null sein.

public_coupon_code

Typ: string

Optional.

Ein einzelner Gutscheincode (ohne Beachtung der Groß-/Kleinschreibung), der mit dem Angebot vermarktet und beim Kaufabschluss vorausgefüllt wird, wenn die Käufer*innen die Voraussetzungen erfüllen.

Standardmäßig werden Angebote mit Gutscheincodes nicht sichtbar an Käufer*innen auf Facebook- oder Instagram-Einkaufsoberflächen wie Produktdetailseiten vermarktet. Damit soll verhindert werden, dass private oder geheime Codes unbeabsichtigt offengelegt werden. Du kannst dieses Verhalten ändern, indem du einen öffentlichen Gutscheincode für die Vermarktung deines Angebots angibst. Angebote mit öffentlichen Codes werden genauso wie Angebote mit dem application_typeAUTOMATIC_AT_CHECKOUT angezeigt, enthalten aber auch den Codetext.

Ein öffentlicher Gutscheincode darf höchstens 20 Zeichen lang sein. Außerdem darf dein Katalog jeweils höchstens 10 aktive Angebote mit öffentlichen Gutscheincodes enthalten.

Öffentliche Gutscheincodes können nur festgelegt werden, wenn der application_typeBUYER_APPLIED lautet.

Wenn du dieses Feld festlegst, muss coupon_codes Null sein.

start_date_time

Typ: timestamp

Erforderlich.

Unix-Zeitstempel des Angebotsbeginns in Sekunden.

Du kannst einen Unix-Zeitstempel in Sekunden oder einen Datums-String im ISO-8601-Format (z. B. 2021-09-25T12:34:56Z) eingeben.

end_date_time

Typ: timestamp

Optional. Ist standardmäßig null.

Unix-Zeitstempel des Angebotsendes in Sekunden. Wenn dieser Wert leer oder null ist, läuft das Angebot unbegrenzt.

Du kannst einen Unix-Zeitstempel in Sekunden oder einen Datums-String im ISO-8601-Format (z. B. 2021-09-25T12:34:56Z) eingeben.

min_quantity

Typ: int64

Optional. Ist standardmäßig 0.

Verwende dieses Feld, wenn dein Angebot nur gültig ist, wenn Kund*innen eine bestimmte Mindestanzahl von Produkten kaufen.

Dieses Feld enthält die Anzahl der Produkte, die gekauft werden müssen, damit das Angebot in Kraft tritt. Beispiel: „20 % Rabatt beim Kauf von 5 T-Shirts“.

Du kannst entweder min_quantity oder min_subtotal festlegen, aber nicht beides.

min_subtotal

Typ: string

Optional. Ist standardmäßig null.

Verwende dieses Feld, wenn dein Angebot nur gültig ist, wenn die Bestellung einen bestimmten Zwischensummenwert erreicht.

Die Zwischensumme der erforderlichen Produkte muss größer oder gleich diesem Wert sein, damit das Angebot in Kraft tritt. Wenn du keine expliziten erforderlichen Produkte festlegst, werden die Zielprodukte als erforderliche Produkte verwendet.

Dieses Feld muss als Betrag und dreistelliger ISO-Währungscode mit einem Leerzeichen dazwischen formatiert werden. Beispiel: Der String „30,99 EUR“ gibt an, dass eine Zwischensumme von 30,99 € erfüllt sein muss, damit das Angebot angewendet wird.

Du kannst entweder min_quantity oder min_subtotal festlegen, aber nicht beides.

redeem_limit_per_user

Typ: int64

Optional. Ist standardmäßig 0 (unbegrenzt).

Gibt an, wie oft das Angebot maximal von einzelnen Nutzer*innen verwendet werden kann.

Setze dieses Feld auf 1, um festzulegen, dass ein Gutscheincode nur einmal eingelöst werden kann.

Dieses Feld sollte nur festgelegt werden, wenn application_typeBUYER_APPLIED lautet.

value_type

Typ: enum {FIXED_AMOUNT, PERCENTAGE}

Erforderlich.

Der Typ des Rabatts durch das Angebot.

Verfügbare Optionen:

FIXED_AMOUNT: Wendet einen Rabatt an, dessen Wert von fixed_amount_off abgeleitet wird.
PERCENTAGE: Wendet einen prozentualen Rabatt an, dessen Wert von percent_off abgeleitet wird.

fixed_amount_off

Typ: string

Erforderlich, wenn value_type auf FIXED_AMOUNT gesetzt ist.

Der Rabattbetrag des Angebots. Muss als Betrag und dreistelliger ISO-Währungscode mit einem Leerzeichen dazwischen formatiert werden. Beispiel: Der String „30,99 EUR“ gibt einen Rabatt von 30,99 € an.

Dieses Feld sollte nur festgelegt werden, wenn value_typeFIXED_AMOUNT lautet.

percent_off

Typ: int64

Erforderlich, wenn value_type auf PERCENTAGE gesetzt ist.

Der prozentuale Rabatt des Angebots. Muss eine Ganzzahl zwischen 0 und 100 sein. „30“ gibt beispielsweise einen Rabatt von 30 % an.

Das Feld sollte nur festgelegt werden, wenn value_typePERCENTAGE lautet.

target_granularity

Typ: enum {ITEM_LEVEL, ORDER_LEVEL}

Erforderlich.

Die Granularität, mit der der Angebotsrabatt angewendet wird.

Verfügbare Optionen:

ITEM_LEVEL: Gibt an, dass ein Rabatt auf jeden der Zielartikel im Einkaufswagen angewendet wird.
ORDER_LEVEL: Gibt an, dass ein Rabatt auf alle Zielartikel im Einkaufswagen gesammelt angewendet wird. Angenommen, das Angebot lautet „30 € Rabatt auf Schuhe“ und es liegen 3 Paar Schuhe im Einkaufswagen. In diesem Fall ziehst du mit ITEM_LEVEL 30 € von jedem Paar ab (Wert von 90 €), während du mit ORDER_LEVEL 30 € von der Summe der drei Paare abziehst (maximal 30 €).

Beachte, dass Angebote mit der Granularität ORDER_LEVEL zu einer Rabattzuteilung beim Kauf führen können, die sich nicht gleichmäßig auf Artikel in einer Bestellung aufteilen lässt. Diese ungleichmäßigen Rabattzuteilungen können mehr Komplexität bei der Abwicklung oder im Falle von Rückerstattungen zur Folge haben.

offer_terms

Typ: string

Optional.

Alle weiteren Nutzungsbedingungen, die für die Verwendung eines Angebots gelten. Maximal 2.500 Zeichen.

Facebook generiert automatisch Bedingungen für das Angebot basierend auf der Angebotskonfiguration. Zusätzlich zu diesen Bedingungen kannst du offer_terms verwenden, um deine eigenen Bedingungen für das Angebot zu beschreiben. Diese Bedingungen werden unter den Angebotsbedingungen von Facebook angezeigt.

Ihr Inhalt muss unsere Content-Richtlinie einhalten.

Berechtigte Produkte angeben

Sowohl die Zielartikel, für die ein Angebot gilt, als auch die erforderlichen Artikel, die zum Einlösen des Angebots gekauft werden müssen, werden durch die Produktauswahl bestimmt. Die Offers API unterstützt mehrere Arten zur Angabe dieser Produktauswahl. Du kannst aber nur eine Methode pro Produktauswahltyp und Angebot verwenden.

Feld Beschreibung

Feld	Beschreibung
`target_selection` Typ: `enum{ALL_CATALOG_PRODUCTS, SPECIFIC_PRODUCTS}`	Erforderlich. Mit diesem Feld unterscheidest du zwischen Angeboten, die für einen ganzen Produktkatalog gelten, und Angeboten, die auf bestimmte Artikel eines Katalogs begrenzt sind. Verfügbare Optionen: `ALL_CATALOG_PRODUCTS`: Das Angebot kann auf alle Produkte im Katalog angewendet werden. `SPECIFIC_PRODUCTS`: Das Angebot kann nur auf die mit `target_filter`, `target_product_retailer_ids`, `target_product_group_retailer_ids` oder `target_product_set_retailer_ids` angegebenen Zielprodukte angewendet werden. Wenn `target_selectionSPECIFIC_PRODUCTS` lautet, ist genau eines der folgenden Felder erforderlich: `target_filter`, `target_product_retailer_ids`, `target_product_group_retailer_ids` oder `target_product_set_retailer_ids`.
`target_filter` Typ: `JSON-encoded string`	Optional. Filterregel zum Identifizieren von Produkten, auf die das Angebot angewendet werden kann. Verwendet dieselbe Filterregellogik wie beim Hinzufügen von Produkten zu einer Produktauswahl. Wenn die angegebene Filterregel mit dem Filter einer vorhandenen Produktauswahl übereinstimmt, gilt dieses Angebot für diese Produktauswahl. Andernfalls wird eine neue Produktauswahl erstellt. Dieses Feld darf nur festgelegt werden, wenn `target_selection` auf `SPECIFIC_PRODUCTS` gesetzt ist.
`target_product_retailer_ids` Typ: `Array<product_retailer_id>`	Optional. Liste der Produkthändler-IDs für Produkte, auf die das Angebot angewendet werden kann. Dieses Feld darf nur festgelegt werden, wenn `target_selection` auf `SPECIFIC_PRODUCTS` gesetzt ist.
`target_product_group_retailer_ids` Typ: `Array<product_group_retailer_id>`	Optional. Liste der Produktgruppenhändler-IDs für Produkte, auf die das Angebot angewendet werden kann. Alle Produktvarianten in der Produktgruppe sind für das Angebot berechtigt. Dieses Feld darf nur festgelegt werden, wenn `target_selection` auf `SPECIFIC_PRODUCTS` gesetzt ist.
`target_product_set_retailer_ids` Typ: `Array<product_set_retailer_id>`	Optional. Liste der Händler-IDs für Produktauswahlen mit Produkten, auf die das Angebot angewendet werden kann. Das Angebot gilt für alle Produkte, die sich durch die Bewertung der angegebenen Produktauswahlen ergeben.
`prerequisite_filter` Typ: `JSON-encoded string`	Optional. Filterregel zum Identifizieren von Produkten, die zum Einlösen des Angebots gekauft werden müssen. Verwendet dieselbe Filterregellogik wie beim Hinzufügen von Produkten zu einer Produktauswahl. Wird in der Regel bei Angeboten der Art „Kaufe X, erhalte Y“ verwendet. Wenn die angegebene Filterregel mit dem Filter einer vorhandenen Produktauswahl übereinstimmt, definiert das Angebot die erforderlichen Produkte anhand dieser Produktauswahl. Andernfalls wird eine neue Produktauswahl erstellt. Wenn dieses Feld festgelegt ist, müssen `prerequisite_product_retailer_ids`, `prerequisite_product_group_retailer_ids` und `prerequisite_product_set_retailer_idsnull` sein.
`prerequisite_product_retailer_ids` Typ: `Array<product_retailer_id>`	Optional. Händler-IDs für Produkte, die Käufer*innen kaufen müssen, um das Angebot einzulösen. Alle in der Liste enthaltenen Artikel können verwendet werden, um das Angebot einzulösen. Wird in der Regel bei Angeboten der Art „Kaufe X, erhalte Y“ verwendet. Wenn dieses Feld festgelegt ist, müssen `prerequisite_filter`, `prerequisite_product_group_retailer_ids` und `prerequisite_product_set_retailer_idsnull` sein.
`prerequisite_product_group_retailer_ids` Typ: `Array<product_group_retailer_id>`	Optional. Händler-IDs für Produktgruppen, die Käufer*innen kaufen müssen, um das Angebot einzulösen. Alle in den Gruppen enthaltenen Produktvarianten können verwendet werden, um das Angebot einzulösen. Wird in der Regel bei Angeboten der Art „Kaufe X, erhalte Y“ verwendet. Wenn dieses Feld festgelegt ist, müssen `prerequisite_filter`, `prerequisite_product_retailer_ids` und `prerequisite_product_set_retailer_idsnull` sein.
`prerequisite_product_set_retailer_ids` Typ: `Array<product_set_retailer_id>`	Optional. Händler-IDs für Produktauswahlen mit Artikeln, die Käufer*innen kaufen müssen, um das Angebot einzulösen. Alle Artikel, die sich aus der Bewertung der Produktauswahlen ergeben, können verwendet werden, um das Angebot einzulösen. Wird in der Regel bei Angeboten der Art „Kaufe X, erhalte Y“ verwendet. Wenn dieses Feld festgelegt ist, müssen `prerequisite_filter`, `prerequisite_product_retailer_ids` und `prerequisite_product_group_retailer_idsnull` sein.
`exclude_sale_priced_products` Typ: `bool enum {YES, NO}`	Optional. Gibt an, ob das Angebot für Produkte gilt, für die bereits ein reduzierter Preis im Katalog festgelegt ist, gemäß dem Feld `sale_price` des Produkts. Setze dieses Feld auf `YES`, um zu vermeiden, dass Produkte potenziell doppelt rabattiert werden. Lass dieses Feld weg oder setze es auf `NO`, um Produkte mit einem niedrigeren `sale_price` im Katalog einzuschließen. Wenn dieses Feld festgelegt ist, gilt es sowohl für die Zielprodukte als auch für die erforderlichen Produkte eines Angebots.

target_selection

Typ: enum{ALL_CATALOG_PRODUCTS, SPECIFIC_PRODUCTS}

Erforderlich.

Mit diesem Feld unterscheidest du zwischen Angeboten, die für einen ganzen Produktkatalog gelten, und Angeboten, die auf bestimmte Artikel eines Katalogs begrenzt sind.

Verfügbare Optionen:

ALL_CATALOG_PRODUCTS: Das Angebot kann auf alle Produkte im Katalog angewendet werden.
SPECIFIC_PRODUCTS: Das Angebot kann nur auf die mit target_filter, target_product_retailer_ids, target_product_group_retailer_ids oder target_product_set_retailer_ids angegebenen Zielprodukte angewendet werden.

Wenn target_selectionSPECIFIC_PRODUCTS lautet, ist genau eines der folgenden Felder erforderlich: target_filter, target_product_retailer_ids, target_product_group_retailer_ids oder target_product_set_retailer_ids.

target_filter

Typ: JSON-encoded string

Optional.

Filterregel zum Identifizieren von Produkten, auf die das Angebot angewendet werden kann. Verwendet dieselbe Filterregellogik wie beim Hinzufügen von Produkten zu einer Produktauswahl.

Wenn die angegebene Filterregel mit dem Filter einer vorhandenen Produktauswahl übereinstimmt, gilt dieses Angebot für diese Produktauswahl. Andernfalls wird eine neue Produktauswahl erstellt.

Dieses Feld darf nur festgelegt werden, wenn target_selection auf SPECIFIC_PRODUCTS gesetzt ist.

target_product_retailer_ids

Typ: Array<product_retailer_id>

Optional.

Liste der Produkthändler-IDs für Produkte, auf die das Angebot angewendet werden kann.

Dieses Feld darf nur festgelegt werden, wenn target_selection auf SPECIFIC_PRODUCTS gesetzt ist.

target_product_group_retailer_ids

Typ: Array<product_group_retailer_id>

Optional.

Liste der Produktgruppenhändler-IDs für Produkte, auf die das Angebot angewendet werden kann.

Alle Produktvarianten in der Produktgruppe sind für das Angebot berechtigt.

Dieses Feld darf nur festgelegt werden, wenn target_selection auf SPECIFIC_PRODUCTS gesetzt ist.

target_product_set_retailer_ids

Typ: Array<product_set_retailer_id>

Optional.

Liste der Händler-IDs für Produktauswahlen mit Produkten, auf die das Angebot angewendet werden kann. Das Angebot gilt für alle Produkte, die sich durch die Bewertung der angegebenen Produktauswahlen ergeben.

prerequisite_filter

Typ: JSON-encoded string

Optional.

Filterregel zum Identifizieren von Produkten, die zum Einlösen des Angebots gekauft werden müssen. Verwendet dieselbe Filterregellogik wie beim Hinzufügen von Produkten zu einer Produktauswahl. Wird in der Regel bei Angeboten der Art „Kaufe X, erhalte Y“ verwendet.

Wenn die angegebene Filterregel mit dem Filter einer vorhandenen Produktauswahl übereinstimmt, definiert das Angebot die erforderlichen Produkte anhand dieser Produktauswahl. Andernfalls wird eine neue Produktauswahl erstellt.

Wenn dieses Feld festgelegt ist, müssen prerequisite_product_retailer_ids, prerequisite_product_group_retailer_ids und prerequisite_product_set_retailer_idsnull sein.

prerequisite_product_retailer_ids

Typ: Array<product_retailer_id>

Optional.

Händler-IDs für Produkte, die Käufer*innen kaufen müssen, um das Angebot einzulösen. Alle in der Liste enthaltenen Artikel können verwendet werden, um das Angebot einzulösen. Wird in der Regel bei Angeboten der Art „Kaufe X, erhalte Y“ verwendet.

Wenn dieses Feld festgelegt ist, müssen prerequisite_filter, prerequisite_product_group_retailer_ids und prerequisite_product_set_retailer_idsnull sein.

prerequisite_product_group_retailer_ids

Typ: Array<product_group_retailer_id>

Optional.

Händler-IDs für Produktgruppen, die Käufer*innen kaufen müssen, um das Angebot einzulösen. Alle in den Gruppen enthaltenen Produktvarianten können verwendet werden, um das Angebot einzulösen. Wird in der Regel bei Angeboten der Art „Kaufe X, erhalte Y“ verwendet.

Wenn dieses Feld festgelegt ist, müssen prerequisite_filter, prerequisite_product_retailer_ids und prerequisite_product_set_retailer_idsnull sein.

prerequisite_product_set_retailer_ids

Typ: Array<product_set_retailer_id>

Optional.

Händler-IDs für Produktauswahlen mit Artikeln, die Käufer*innen kaufen müssen, um das Angebot einzulösen. Alle Artikel, die sich aus der Bewertung der Produktauswahlen ergeben, können verwendet werden, um das Angebot einzulösen. Wird in der Regel bei Angeboten der Art „Kaufe X, erhalte Y“ verwendet.

Wenn dieses Feld festgelegt ist, müssen prerequisite_filter, prerequisite_product_retailer_ids und prerequisite_product_group_retailer_idsnull sein.

exclude_sale_priced_products

Typ: bool enum {YES, NO}

Optional.

Gibt an, ob das Angebot für Produkte gilt, für die bereits ein reduzierter Preis im Katalog festgelegt ist, gemäß dem Feld sale_price des Produkts.

Setze dieses Feld auf YES, um zu vermeiden, dass Produkte potenziell doppelt rabattiert werden. Lass dieses Feld weg oder setze es auf NO, um Produkte mit einem niedrigeren sale_price im Katalog einzuschließen.

Wenn dieses Feld festgelegt ist, gilt es sowohl für die Zielprodukte als auch für die erforderlichen Produkte eines Angebots.

Versandangebote

Die Offers API unterstützt nicht nur Angebote, die den Preis von Produkten beim Kauf reduzieren, sondern auch Angebote für reduzierte Versandkosten für diese Produkte. Versandangebote können wie Angebote für Produkte auch über einen Gutscheincode oder automatisch mit oder ohne zusätzliche Voraussetzungen angewendet werden.

Zum Erstellen eines Versandangebots muss target_type auf SHIPPING gesetzt sein. Derzeit werden nur Angebote für kostenlosen Versand unterstützt. Daher muss value_type immer PERCENTAGE lauten und percent_off auf 100 gesetzt sein.

Feld Beschreibung

Feld	Beschreibung
`target_type` Typ: `enum{LINE_ITEM, SHIPPING}`	Erforderlich. Der Typ des Objekts, für das dieses Angebot gilt: `LINE_ITEM`: Das Angebot wird auf die Produkte selbst angewendet. `SHIPPING`: Das Angebot wird auf die Versandkosten angewendet. Diese Option ist nur gültig, wenn `target_granularity` auf `ITEM_LEVEL` gesetzt ist.
`target_shipping_option_types` Typ: `Array<shipping_service_tier>`	Erforderlich, wenn `target_typeSHIPPING` lautet. Eine Liste der Versanddienststufen (z. B. `STANDARD`, `RUSH`, `EXPEDITED`), für die das Angebot gilt. Um beispielsweise ein Versandangebot anzugeben, das für den Standard- und den Express-Versand, aber nicht für die Lieferung am nächsten Tag gilt, verwende: `target_type`: `SHIPPING` `target_shipping_option_types`: `["STANDARD", "RUSH"]` Für Verkäufer*innen mit aktiviertem Facebook- oder Instagram-Checkout kannst du die Shipping Profiles API verwenden, um die Versandprofile in deinem Commerce-Konto zu verwalten.

target_type

Typ: enum{LINE_ITEM, SHIPPING}

Erforderlich.

Der Typ des Objekts, für das dieses Angebot gilt:

LINE_ITEM: Das Angebot wird auf die Produkte selbst angewendet.
SHIPPING: Das Angebot wird auf die Versandkosten angewendet. Diese Option ist nur gültig, wenn target_granularity auf ITEM_LEVEL gesetzt ist.

target_shipping_option_types

Typ: Array<shipping_service_tier>

Erforderlich, wenn target_typeSHIPPING lautet.

Eine Liste der Versanddienststufen (z. B. STANDARD, RUSH, EXPEDITED), für die das Angebot gilt.

Um beispielsweise ein Versandangebot anzugeben, das für den Standard- und den Express-Versand, aber nicht für die Lieferung am nächsten Tag gilt, verwende:

target_type: SHIPPING
target_shipping_option_types: ["STANDARD", "RUSH"]

Für Verkäufer*innen mit aktiviertem Facebook- oder Instagram-Checkout kannst du die Shipping Profiles API verwenden, um die Versandprofile in deinem Commerce-Konto zu verwalten.

Angebote der Art „Kaufe X, erhalte Y“

Bei Angeboten der Art „Kaufe X, erhalte Y“ können Käufer*innen eine bestimmte Menge des Produkts X kaufen, um 1 oder mehr Y-Produkte zu einem reduzierten Preis oder kostenlos zu erhalten. Angebote der Art „Gib X aus, erhalte Y“ werden ebenfalls unterstützt. Dabei müssen die Käufer*innen einen bestimmten Mindestbetrag für Produkt X ausgeben, um einen Preisnachlass zu erhalten. Du erstellst ein Angebot der Art „Kaufe X, erhalte Y“, indem du das Feld target_quantity und entweder min_quantity oder min_subtotal festlegst.

In einigen Fällen, wie dem gängigen Angebot „2 zum Preis von 1“, können sich X und Y auf dieselbe Produktauswahl beziehen. Du kannst aber auch prerequisite_filter, prerequisite_product_retailer_ids, prerequisite_product_group_retailer_ids und prerequisite_product_set_retailer_ids verwenden, um eine Auswahl von X-Produkten anzugeben, die sich von den Y-Zielprodukten unterscheiden. Wie du diese Felder konfigurierst, erfährst du unter Berechtigte Produkte angeben.

Feld Beschreibung

Feld	Beschreibung
`target_quantity` Typ: `int64`	Optional. Ist standardmäßig 0 (unbegrenzt). Die Anzahl der Produkte, die bei jeder Einlösung des Angebots rabattiert werden. `target_quantity` > 0 entspricht einem Angebot der Art „Kaufe X, erhalte Y“. Gib über dieses Feld an, wie viele Produkte rabattiert werden, wenn Käufer*innen die Voraussetzungen zum Einlösen erfüllen. Beispiel: Beim Angebot „2 kaufen und 50 % Rabatt auf das 2. erhalten“ lautet die Zielmenge 1, während sie beim Angebot „5 kaufen und 2 gratis erhalten“ 2 beträgt.
`redemption_limit_per_order` Typ: `int64`	Optional. Ist standardmäßig 0 (unbegrenzt). Gibt an, wie oft dieses Angebot pro Bestellung eingelöst werden kann. Mit diesem Feld kannst du begrenzen, wie oft ein Angebot auf die Produkte in einem Kauf angewendet werden kann. Beispiel: Beim Angebot „2 T-Shirts zum Preis von 1“ erhalten Käuferinnen, die 6 T-Shirts kaufen, standardmäßig 3 zum vollen Preis und 3 kostenlos. Wenn du allerdings im gleichen Beispiel `redemption_limit_per_order` auf 2 setzt, erhalten Käuferinnen 2 T-Shirts gratis und 4 zum vollen Preis. Wenn dieses Feld festgelegt ist, muss `target_quantity` größer als 0 sein.

target_quantity

Typ: int64

Optional. Ist standardmäßig 0 (unbegrenzt).

Die Anzahl der Produkte, die bei jeder Einlösung des Angebots rabattiert werden. target_quantity > 0 entspricht einem Angebot der Art „Kaufe X, erhalte Y“.

Gib über dieses Feld an, wie viele Produkte rabattiert werden, wenn Käufer*innen die Voraussetzungen zum Einlösen erfüllen. Beispiel: Beim Angebot „2 kaufen und 50 % Rabatt auf das 2. erhalten“ lautet die Zielmenge 1, während sie beim Angebot „5 kaufen und 2 gratis erhalten“ 2 beträgt.

redemption_limit_per_order

Typ: int64

Optional. Ist standardmäßig 0 (unbegrenzt).

Gibt an, wie oft dieses Angebot pro Bestellung eingelöst werden kann.

Mit diesem Feld kannst du begrenzen, wie oft ein Angebot auf die Produkte in einem Kauf angewendet werden kann. Beispiel: Beim Angebot „2 T-Shirts zum Preis von 1“ erhalten Käufer*innen, die 6 T-Shirts kaufen, standardmäßig 3 zum vollen Preis und 3 kostenlos. Wenn du allerdings im gleichen Beispiel redemption_limit_per_order auf 2 setzt, erhalten Käufer*innen 2 T-Shirts gratis und 4 zum vollen Preis.

Wenn dieses Feld festgelegt ist, muss target_quantity größer als 0 sein.

Angebote kombinieren

Für Verkäufer*innen mit aktiviertem Checkout auf Facebook oder Instagram wird die Kombination mehrerer Angebote in einer Transaktion eingeschränkt unterstützt. Ob ein Angebot mit anderen Angeboten kombiniert werden kann, ist in der Regel von seinem Anwendungstyp und seinem Zieltyp abhängig. Dieses Verhalten kann momentan nicht von Verkäufer*innen konfiguriert werden. Die folgenden Regeln gelten für das Kombinieren von Angeboten:

Wenn es für ein Produkt Angebote mit durchgestrichenen Preisen gibt (application_type = SALE), wird das Angebot angewendet, das den niedrigsten Produktpreis ergibt. Diese Regel wird für alle Artikel im Einkaufswagen wiederholt. Der neue reduzierte Preis des Artikels wird bei allen zukünftigen Berechnungen von Angebotsvoraussetzungen verwendet.
In einer einzelnen Bestellung können Käufer*innen entweder 1 Angebot vom Typ BUYER_APPLIED oder 1 Angebot vom Typ AUTOMATIC_AT_CHECKOUT pro target_type (LINE_ITEM oder SHIPPING) einlösen. Beispiel: Eine Person kann einen Gutschein für kostenlosen Versand und einen Gutschein für „2 zum Preis von 1“ anwenden, aber nicht zwei Angebote für reduzierte Produktpreise einlösen.
Meta kann manchmal Angebote finanzieren, um neue und wiederkehrende Kund*innen anzusprechen, ohne dass Kosten für die Verkäufer*innen anfallen. Von Meta finanzierte Angebote können immer mit von Verkäufer*innen finanzierten Angeboten kombiniert werden.

Berechtigung für Angebote einschränken

Derzeit können über die Offers API erstellte Angebote nicht gezielt an bestimmte Nutzer*innen-Kohorten vermarktet werden. Im Commerce Manager erstellte Angebote können mit Einschränkungen der Berechtigung konfiguriert werden. Ein vermarktetes Angebot, das über die Offers API erstellt wurde, wird allen Käufer*innen angezeigt und alle Personen, die die jeweiligen Voraussetzungen (beispielsweise die Eingabe von Gutscheincodes) beim Kaufabschluss auf Facebook oder Instagram erfüllen, können das Angebot einlösen.

In Zukunft ermöglicht es die Offers API internationalen Verkäufer*innen eventuell, Angebote auf bestimmte Länder einzuschränken und Angebote nur für bestimmte Nutzungsgruppen anzubieten, wie erstmalige Käufer*innen oder Follower*innen der Facebook-Seite des*der Verkäufer*in.