Epinium-API

Zugang: Einstellungen → API Keys

Epinium stellt deine Daten über eine REST-API bereit, damit du sie aus deinen eigenen Werkzeugen lesen kannst: einem eigenen Dashboard, einem Analyseskript oder einem KI-Assistenten. Es sind dieselben Informationen wie in der App, mit denselben Zahlen.

Die API liest deine Daten und schreibt auf Amazon und in deine Shops: Sie fragt Katalog, Kampagnen und Kennzahlen ab und liest, was in deinen Shopify- und WooCommerce-Shops steckt, legt Sponsored-Products-Kampagnen an und bearbeitet sie, bearbeitet Sponsored-Brands- und Display-Kampagnen, legt Portfolios an und bearbeitet sie, legt Workflows an, bearbeitet, klont und führt sie aus, legt Aufgaben an, entscheidet und wendet sie an, und sie legt in deinen verbundenen Shopify- und WooCommerce-Shops Produkte und Inhalte an, bearbeitet und löscht sie. Dein Amazon-Katalog ändert sich nur, wenn eine genehmigte Aufgabe angewendet wird; der deiner Shops ändert sich direkt, ohne Aufgabe. Jeder Bereich hat seine eigene Berechtigung, und die zum Schreiben vergibst du beim Anlegen des Schlüssels.

Willst du sie aus einem KI-Assistenten nutzen?

Du musst nichts programmieren. Der Epinium-MCP verbindet genau diese Daten mit Claude und anderen kompatiblen Assistenten.

Token erzeugen

1. Gehe zu Einstellungen → API Keys
2. Klicke auf API Key erstellen und gib ihm einen Namen, der an den Zweck erinnert
3. Wähle die benötigten Berechtigungen aus
4. Kopiere den Schlüssel und bewahre ihn sicher auf
5. Verwende ihn im Authorization-Header jeder Anfrage

Der Schlüssel wird nur einmal angezeigt

Der vollständige Wert erscheint bei der Erstellung genau einmal. Verlierst du ihn, ist er nicht wiederherstellbar: Du musst ihn widerrufen und einen neuen erstellen.

Berechtigungen

Jedes Token trägt die Berechtigungen, die du bei der Erstellung auswählst. Vergib nur die, die deine Integration braucht.

Berechtigung	Gibt Zugriff auf
catalog:read	Produkte, Marken, Länder und Cluster, mit ihren Kennzahlen: Umsatz, Amazon-Gebühren und Marge, Retouren, Bestand und bei Vendor Bewertungen
campaigns:read	Kampagnen, Portfolios, Ad Groups, Targets, Product Ads und Suchbegriffe
workflows:read	Deine Workflows, ihre Konfiguration und welche Kampagnen sie erreichen
connections:read	Die Verbindungen deines Kontos: Amazon, Shopify und WooCommerce
tasks:read	Epinium-Aufgaben und ihre Items
skills:read	Der Katalog validierter Marketing-Playbooks von Epinium
platform:read	Was in deinen Shopify- und WooCommerce-Shops steckt: Produkte, Bestand, Preise und alles Weitere, was jeder Shop bereitstellt, live aus seiner eigenen API gelesen. Dazu gehört das Protokoll der dort vorgenommenen Änderungen (/v1/platform-changes, 1 Credit pro zurückgegebener Zeile)
catalog:write	Keyword-Cluster anlegen, bearbeiten und löschen: ihren Namen, ihre positiven und negativen Keywords und die gruppierten Produkte. Nichts erreicht Amazon
campaigns:write	Kampagnen, Portfolios, Ad Groups, Targets und Product Ads bei Amazon anlegen und ändern, und konfigurieren, was der Optimierer für jede verfolgt
platform:write	Produkte und Inhalte in deinen verbundenen Shopify- und WooCommerce-Shops anlegen, bearbeiten und löschen, direkt und ohne vorherige Prüfung, über dieselbe Route, mit der sie abgefragt werden (POST /v1/platform-request): eine Mutation in Shopify oder eine andere Methode als GET in WooCommerce, mit dem Header Idempotency-Key. Außerdem ist platform:read nötig (die Stufe Bearbeiten im Bildschirm API Keys vergibt beide). Jede Änderung wird 12 Monate lang aufgezeichnet und kostet so viel wie eine Abfrage: 5 Credits pro Aufruf plus 1 pro KB Rückgabe
tasks:write	Aufgaben anlegen, ihre Vorschläge annehmen oder ablehnen, sie abschließen und das Angenommene anwenden
workflows:write	Workflows anlegen, kopieren, bearbeiten, einschalten, pausieren, löschen und wiederherstellen, und sie ausführen oder simulieren

Schreiben gibt es in den Plänen Business und Master. In Free und Guru lesen Tokens nur: Ein Schlüssel oder eine Assistenten-Freigabe mit Schreibberechtigungen lässt sich nicht anlegen, und wechselst du in einen dieser Pläne, lesen die bestehenden weiter, aber ihre Schreibzugriffe werden mit einem 403 abgelehnt.

Ein Token erreicht alle Verbindungen deines Kontos. Als Agentur erreicht es die Verbindungen, die jeder Kunde mit der Annahme deiner Einladung freigegeben hat.

Als Agentur: wähle das Konto bei jedem Aufruf

Ein Agentur-Token erreicht mehrere Konten, deshalb muss jede Anfrage sagen, auf welchem sie arbeitet. Über den Header Epinium-Account: <Konto-ID> oder über den Parameter account_id, wenn du über das MCP aufrufst.

/v1/me und /v1/accounts sind die Ausnahme: sie antworten ohne Kontoauswahl, und genau sie sagen dir, welche Konten du erreichst und wie sie heißen.

Ist das Konto gewählt, siehst du es vollständig: seine Produkte und Kampagnen sind auf die freigegebenen Verbindungen begrenzt, und seine Konto-Ressourcen — Workflows, Aufgaben und Cluster, die an keiner Verbindung hängen — sind auf das Konto begrenzt. Was außerhalb deiner Reichweite liegt, wird nicht still gefiltert: eine account_id, zu der du nicht eingeladen bist, gibt einen ausdrücklichen Fehler zurück, keine leere Liste.

Welche Endpoints sie abdeckt

Jede Ressource hat eine Liste, und die meisten erlauben zusätzlich das Abrufen eines Elements über seine id. Die Metrik-Ressourcen haben nur eine Liste: Eine über einen Zeitraum aggregierte Zeile hat keine eigene Kennung.

Katalog — catalog:read

Endpoint	Was er zurückgibt
/v1/products	Deine vereinheitlichten Produkte
/v1/amazon-seller-products	Die Seller-Central-Sicht jedes Produkts, und die Kategorie seines Rankings mit expand=salesRanks
/v1/amazon-vendor-products	Die Vendor-Central-Sicht, die Kategorie des Rankings mit expand=salesRanks und die Bewertungen mit expand=customerFeedback
/v1/amazon-advertising-products	Die Advertising-Sicht
/v1/seller-product-metrics	Umsatz, Sessions, Buy Box, Rank, Amazon-Gebühren, Marge, Retouren, Bestand, B2B und Reichweite in Tagen pro Produkt
/v1/vendor-product-metrics	Vendor-Umsatz pro Produkt, mit Manufacturing und Sourcing, Retouren, Sell-in mit Amazon, Inventar und Reichweite in Tagen
/v1/product-brands	Deine Marken
/v1/countries	Länder und Marketplaces
/v1/clusters	Deine Keyword-Cluster; mit catalog:write legst du sie auch an und bearbeitest sie

Advertising — campaigns:read

Endpoint	Was er zurückgibt
/v1/campaigns	Deine Amazon-Advertising-Kampagnen
/v1/campaign-metrics	Ausgaben, Umsatz, ACOS und ROAS pro Kampagne
/v1/portfolios	Deine Portfolios und das Budgetlimit, das jedes seinen Kampagnen setzt
/v1/adgroups	Die Ad Groups jeder Kampagne
/v1/adgroup-metrics	Performance pro Ad Group
/v1/targets	Keywords und Produkt-Targets
/v1/target-metrics	Performance pro Target, mit Keyword und Match-Typ
/v1/product-ads	Die Verbindung zwischen Ad Group und beworbenem Produkt
/v1/product-ad-metrics	Performance pro beworbenem Produkt, mit seiner ASIN
/v1/search-terms	Die tatsächlichen Suchanfragen der Käufer
/v1/search-term-metrics	Performance pro Suchanfrage, mit Text und passendem Target
/v1/campaigns/{id}/optimization-history	Was die Automatisierung an einer Kampagne geändert hat, mit dem Nettoeffekt
/v1/advertising-changes	Alles, was Epinium bei Amazon geändert hat, unabhängig von der Quelle

Automatisierung — workflows:read

Endpoint	Was er zurückgibt
/v1/workflows	Deine Workflows, mit ihrem Zeitplan und ob sie aktiv sind
/v1/workflows/{id}	Die vollständige Konfiguration eines Workflows: sein Diagramm und jede Variable mit ihrem effektiven Wert
/v1/workflows/{id}/campaigns	Welche Kampagnen er wirklich erreicht, und warum jede dabei ist
/v1/workflows/{id}/performance	Die Performance dieser Kampagnen, mit ihrem Ziel daneben, um sie beurteilen zu können

Ein Workflow kann jede Nacht geplant sein und dennoch keine einzige Kampagne anfassen: /campaigns bringt genau das zum Vorschein, und wenn die Menge leer zurückkommt, nennt sie den Grund.

Verbindungen, Aufgaben und Skills

Endpoint	Berechtigung	Was er zurückgibt
/v1/connections	connections:read	Deine Verbindungen: Amazon, Shopify und WooCommerce
POST /v1/platform-request	platform:read, und platform:write zum Schreiben	Eine Abfrage an einen deiner Shops oder, mit platform:write, eine Änderung daran: GraphQL bei Shopify, REST bei WooCommerce
/v1/platform-request/docs/{platform}	platform:read	Die API-Version dieser Plattform, ihre Referenz und die Felder, die dein Shop gerade hat
/v1/tasks	tasks:read	Epinium-Aufgaben
/v1/task-items	tasks:read	Die Items jeder Aufgabe
/v1/skills	skills:read	Der Katalog von Marketing-Playbooks von Epinium

Der Skills-Katalog ist von Epinium verfasster Inhalt, keine Daten deines Kontos: er ist für alle Kunden identisch. Welche Teile jedes Playbooks du erhältst, hängt von deinem Plan ab.

Abfragen an deine Shops liefern keine personenbezogenen Daten: Namen, E-Mails, Telefonnummern und Adressen werden abgelehnt, bevor die Anfrage den Shop erreicht. Abgerechnet wird nach der Größe der Antwort, bei Änderungen ebenso. Diese beiden Routen stehen nicht in der durchsuchbaren Referenz: Üblich ist, sie über den Epinium-MCP zu nutzen.

Zusätzlich gibt es /v1/me, das dir sagt, welche Berechtigungen und welche Konten dein Token erreicht. Das ist der erste sinnvolle Aufruf, um zu prüfen, ob der Schlüssel funktioniert.

Drei Regeln beim Lesen der Daten

Diese drei erklären fast alle Interpretationsfragen:

• Beträge sind Text, keine Zahlen. "cost": "8.22" kommt absichtlich als String, damit bei der Umwandlung in eine binäre Dezimalzahl keine Genauigkeit verloren geht.
• Verhältnisse kommen als Bruch, nicht als Prozent. Ein ACOS von 90,83 % kommt als 0.908287. Für die Anzeige mit 100 multiplizieren.
• null ist nicht 0. null heißt, dass Amazon den Wert nicht gemeldet hat; 0 heißt echte Null. Ein acos von null ist eine Kampagne, die ausgegeben und nichts verkauft hat, nicht kostenlose Werbung. Und new_to_brand_sales kommt bei Sponsored Products als null, weil Amazon es für dieses Format nicht misst.

Rentabilität, Bestand und Bewertungen deiner Produkte

Die Produktkennzahlen hören nicht beim Umsatz auf: Sie zeigen auch, wie viel Amazon einbehält, wie viel Bestand übrig ist und was Käufer denken. Vier Dinge, bevor du Schlüsse ziehst:

• Seller-Gebühren und -Marge sind ohne Mehrwertsteuer, während sales sie dort enthält, wo sie gilt: Ziehe das eine nicht vom anderen ab. margin_before_ads ist, was nach der Zahlung an Amazon bleibt, vor Werbung und Produktkosten: Für die Marge nach Werbung ziehst du die Ausgaben aus /v1/product-ad-metrics ab. Amazon bucht die Lagerkosten auf einen einzigen Tag des Monats und Erstattungen auf das Erstattungsdatum, deshalb liest man die Marge pro Monat, nicht pro Tag.
• days_of_coverage sind die Tage, die der Bestand im Tempo des Zeitraums reicht: der Bestand des letzten Tages geteilt durch die durchschnittlichen Einheiten pro Tag des angefragten Zeitraums. Der Wert ist null bei jeder Granularität außer total, wenn das Produkt nichts verkauft hat oder, beim Gruppieren, wenn group_by das Land nicht enthält. Mit order_by=days_of_coverage&order=asc kommen zuerst die Produkte, die bald ausverkauft sind.
• Bei Vendor gibt es außerdem den Sell-in: die Einheiten, die du Amazon bestätigt hast, die aus offenen Bestellungen, die Fill Rate und die Lieferzeit, dazu die Retouren getrennt nach Manufacturing und Sourcing und die Gesundheit des Inventars.
• Die Kategorie des Rankings und die Bewertungen fragst du beim Produkt ab, nicht bei den Kennzahlen. expand=salesRanks sagt, zu welcher Kategorie jede Position im Best Seller Rank gehört, und bei Vendor liefert expand=customerFeedback die positiven und negativen Bewertungsthemen und die Retourengründe der Kategorie. Es ist der Stand dieser Woche, mit dem Sechsmonatstrend, den Amazon berechnet, keine Historie.

Kontosummen, nach Zeitraum und nach Cluster

Um zu wissen, wie viel das Konto im September verkauft hat, musst du den Katalog nicht paginieren und aufsummieren: Die sieben Metrik-Ressourcen aggregieren selbst.

• group_by summiert über Entitäten hinweg. account liefert die Summe des Kontos; country und connection schlüsseln nach Land oder nach Verbindung auf und lassen sich kombinieren, indem du den Parameter wiederholst (group_by[]=connection&group_by[]=country). account lässt sich mit nichts kombinieren. Die Zeilen bleiben nach Währung getrennt — Beträge werden nie umgerechnet — und bei Advertising nach Ad Product (SP, SB, SD).
• granularity teilt den Zeitraum in Kalenderperioden. Neben total und daily akzeptiert es weekly, monthly, quarterly und yearly, und jede Zeile trägt in date den Beginn ihrer Periode: den Montag der Woche oder den 1. des Monats, des Quartals oder des Jahres. Die Perioden an den Rändern sind unvollständig: Vom 15. Januar bis zum 10. März liefert monthly den Januar vom 15. bis 31., den ganzen Februar und den März vom 1. bis 10.
• cluster grenzt auf eine Produktfamilie ein. Bei den Metriken für Seller, Vendor und beworbene Produkte lässt cluster=<id> nur die Produkte dieses Clusters übrig; bei mehreren IDs deren Vereinigung. Es lässt sich mit dem Vorigen kombinieren: group_by=account&granularity=monthly&cluster=<id> ist die Monatsreihe dieser Familie.
• group_by=cluster liefert eine Zeile pro Cluster. Bei denselben drei Metriken gibt group_by=cluster die Zahlen jedes deiner Cluster in einem einzigen Aufruf zurück, mit seiner ID in cluster und seinem Namen in cluster_name. Ein Produkt, das in mehreren Clustern steckt, zählt in jedem davon voll, daher ergeben die Zeilen zusammen nicht die Kontosumme, und Produkte ohne Cluster erscheinen nicht. Es lässt sich mit country und connection kombinieren und mit dem Filter cluster, um auszuwählen, welche Cluster zurückkommen; kommen deine Cluster auf mehr als 2.000 Produkt-Cluster-Zuordnungen, bittet die API dich, sie mit diesem Filter einzugrenzen.

In gruppierten Zeilen sind die Felder, die eine Entität identifizieren (product, asin, campaign…), null, ebenso wie alles, was sich nicht summieren lässt: der Rank, der Preis, der Kanal und die Vendor-Quoten. Der Seller-Bestand wird nur summiert, wenn du nach Land gruppierst: Beim paneuropäischen FBA-Inventar meldet Amazon denselben Bestand auf jedem Marktplatz, und ihn über Länder hinweg zu summieren, würde dieselben Einheiten mehrfach zählen. Deshalb sind stock und days_of_coverage bei group_by=account oder connection null.

Ein Cluster fasst Katalogprodukte zusammen, keine einzelnen ASINs: Dieselbe ASIN in einer anderen Verbindung bleibt außen vor, sofern ihr Produkt nicht ebenfalls im Cluster ist. Und Zeilen, die Amazon keinem Katalogprodukt zuordnen konnte, erfasst der Filter nicht: rund 5 % des Vendor-Umsatzes und 3 % der Ausgaben für beworbene Produkte.

Wie viele Credits das spart, steht unter Credits.

Was die Automatisierung an einer Kampagne geändert hat

/v1/campaigns/{id}/optimization-history beantwortet, was der Workflow an einer Kampagne geändert hat, nicht was er entschieden hat. Der Unterschied zählt: in einem Entscheidungsprotokoll kann dasselbe Target in derselben Nacht mit einer Erhöhung und einer Senkung auftauchen, und dort sieht man nicht, dass sie sich aufheben.

Deshalb kommt jede Zeile aggregiert zum Nettoeffekt der Entität: das Gebot von vor der ersten Änderung des Zeitraums gegen das nach der letzten, plus wie oft es sich unterwegs bewegt hat. Ein Target, das von 0,18 € auf 0,45 € erhöht und in derselben Nacht auf 0,18 € zurückgeschnitten wurde, kommt mit einem Netto von null und zwei Bewegungen zurück — das ist die nützliche Lesart, und genau die, die eine flache Liste verbirgt.

Drei Dinge begrenzen, was zurückkommt:

• Nur echte Änderungen. Simulationen werden hier unter keinem Parameter ausgeliefert: es sind Gebote, die Amazon nie erreicht haben.
• Nur das Angewendete, nicht das Vorgeschlagene. Der Optimizer berechnet ein Gebot, das eine Obergrenze danach kappen kann; berichtet wird nur, was gesendet wurde.
• Höchstens ein Fenster von 90 Tagen. So lange werden diese Einträge aufbewahrt. Ohne Datumsangaben kommen die letzten 90 Tage zurück.

Änderungen, die keine Gebote sind — geerntete Keywords, Negatives, Platzierungsanpassungen, Targets in Quarantäne oder blockiert — werden separat in other_changes gezählt, denn sie haben kein vorheriges Gebot zum Vergleich.

Alles, was Epinium bei Amazon geändert hat

/v1/advertising-changes beantwortet eine andere Frage als der vorige Endpoint: nicht warum die Automatisierung entschieden hat, sondern was angefasst wurde und ob Amazon es akzeptiert hat. Und nicht nur, was die Automatisierung tut: auch was eine Person in der Anwendung, ein interner Prozess oder diese API selbst getan hat.

Die Regel passt in eine Zeile: wurde es an Amazon gesendet, gibt es eine Zeile. Daraus folgen drei Dinge, die man klar haben sollte:

• Auch was Amazon abgelehnt hat, hinterlässt eine Zeile, mit result: "failed" und der Amazon-Meldung in error. Das ist die erste Stelle, an der man nachsieht, wenn eine Änderung nicht gewirkt hat.
• Was gar nicht erst versucht wurde, hinterlässt keine Zeile: ein Budget unter dem Landesminimum oder ein Gebot, das bereits dem gewünschten entsprach.
• Konfigurationsänderungen innerhalb von Epinium bleiben außen vor, denn sie gehen nicht an Amazon.

Jede Zeile sagt, woher sie kommt. source unterscheidet die Anwendung (front), den Optimierer (workflow), einen internen Prozess (system) und diesen Kanal (public-api, mcp), und actor benennt die Person oder die konkreten Zugangsdaten — hat jemand die Änderung in der Anwendung vorgenommen, steht dort seine E-Mail. Kam sie aus einem Workflow, ist correlation_id die Kennung dieses Laufs und damit der Schlüssel, um diese Antwort mit optimization-history zu verknüpfen.

Filtern kannst du nach campaign, adgroup, entity, entity_type, source, result, field und correlation_id, und das Fenster mit start_date und end_date eingrenzen (YYYY-MM-DD, beide inklusive). Die Einträge werden zwölf Monate aufbewahrt.

Bei Amazon schreiben

Mit der Berechtigung campaigns:write liest die API nicht mehr nur: sie legt Kampagnen, Ad Groups, Targets und Product Ads an und bewegt deren Status, Budgets und Gebote. Was du schreibst, geht wirklich zu Amazon und hinterlässt seine Zeile in /v1/advertising-changes.

Fünf Dinge, die du vor dem ersten Aufruf wissen solltest:

• Alles entsteht pausiert. Eine Kampagne oder eine Ad Group wird PAUSED angelegt, sofern du nicht ausdrücklich ENABLED verlangst, denn was aktiv ist, gibt Geld aus, sobald Amazon es annimmt.
• Archivieren hat ein eigenes Verb: DELETE /v1/<Ressource>/{id}. Es ist die einzige unumkehrbare Operation dieser API: Bei Amazon lässt sich Archivieren nicht rückgängig machen. Deshalb ist es kein state-Wert, den du versehentlich neben einer Gebotsänderung setzen könntest, sondern ein eigener Aufruf mit eigenem Verb. Willst du nur die Ausgaben stoppen, nutze state: "PAUSED" — das ist umkehrbar.
• Jeder Schreibvorgang verlangt einen Idempotency-Key-Header. Verwende denselben Wert wieder, wenn du dieselbe Absicht erneut sendest: ohne ihn wird aus einem Netzwerk-Timeout eine zweite Kampagne.
• Ein Stapel ist nicht alles-oder-nichts. POST /v1/<Ressource>/batch nimmt bis zu 1000 Entitäten und antwortet mit einer Zeile pro Entität, in der Reihenfolge, in der du sie gesendet hast. applied ist das, was bei Amazon ankam, und nur das wird abgerechnet. Ein Teilergebnis ist der Normalfall, kein Fehler: lies es, statt den ganzen Stapel zu wiederholen — eine Wiederholung würde verdoppeln, was bereits durchging.
• Eine Entität gilt nur dann als angewandt, wenn alles Angeforderte durchging. Ändert ein PATCH Status und Budget und Amazon nimmt das erste an und lehnt das zweite ab, kommt diese Entität als failed mit dem Grund zurück — sie als angewandt zu melden ist der Weg, zu glauben, ein Gebot habe sich bewegt, obwohl nicht.

Route	Was sie tut
POST /v1/campaigns	Eine Kampagne anlegen
POST /v1/campaigns/full	Kampagne + Ad Group + Targets + Product Ads in einem Aufruf
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batch	Status, Tagesbudget, Name und Portfolio (das Portfolio nur bei Sponsored Products)
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batch	Anlegen; Status, Standardgebot und Name
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batch	Targets anlegen (die Typen hängen vom Ad Product der Anzeigengruppe ab); Status und Gebot
POST /v1/product-ads · PATCH /v1/product-ads/{id} · POST /v1/product-ads/batch	Produkte bewerben; Status
POST /v1/portfolios · PATCH /v1/portfolios/{id}	Ein Portfolio anlegen; Name, Status und Budgetlimit
DELETE /v1/campaigns/{id} · DELETE /v1/adgroups/{id} · DELETE /v1/targets/{id} · DELETE /v1/product-ads/{id}	Archivieren - unumkehrbar

Was sich nicht ändern lässt, und warum: was ein Target ausmacht — sein Keyword, sein ASIN, seine Match-Art — ist bei Amazon nicht editierbar; um es zu ändern, legt man ein neues an und archiviert das alte. Eine Product Ad nimmt nur den Status: sie ist die Verbindung zwischen einem Produkt und einer Ad Group, ohne eigenes Gebot und ohne eigenen Namen. Und vom Optimierer verwaltete Entitäten werden abgelehnt, weil sein Lauf um 03:00 UTC darüber schreiben würde.

Das Budgetlimit eines Portfolios begrenzt, was alle seine Kampagnen zusammen ausgeben. MONTHLY_RECURRING beginnt jeden Monat neu, DATE_RANGE gilt zwischen startDate und endDate, und NO_CAP hebt es auf; die Währung ist die des Marktplatzes und wird nicht mitgeschickt. In einem PATCH wird budget komplett ersetzt: Schick das ganze Limit, das du willst, nicht nur den Betrag. Um eine Sponsored-Products-Kampagne in ein Portfolio oder aus ihm heraus zu verschieben, änderst du ihre portfolioId mit PATCH /v1/campaigns/{id}.

Zwei Codes, die man auseinanderhalten sollte. Eine Entität, die nicht existiert oder zu einem anderen Konto gehört, antwortet 404 — nie 403, was ihre Existenz bestätigen würde. Eine Ablehnung von Amazon antwortet 200 mit result: "failed" und dem Grund: der Aufruf kam an, gescheitert ist die Änderung.

Alle drei Ad Products lassen sich schreiben, aber nicht gleich:

• Sponsored Brands und Sponsored Display werden über dieselben Routen wie Sponsored Products geändert und archiviert: Status, Budget, Name und Gebote von Kampagnen, Anzeigengruppen, Targets und Product Ads. Was noch nicht geht, ist das Anlegen: POST /v1/campaigns, /v1/campaigns/full, /v1/adgroups und /v1/product-ads gelten nur für Sponsored Products.
• Anzeigengruppen von Sponsored Brands haben kein Standardgebot. Eine defaultBid-Änderung an einer davon wird mit einer erklärenden Meldung abgelehnt. Die von Sponsored Display haben eines.
• Targets und negative Targets lassen sich in SB- und SD-Anzeigengruppen anlegen, mit POST /v1/targets. Welcher targetType akzeptiert wird, hängt vom Ad Product der Anzeigengruppe ab (Tabelle unten). Nur auf Ebene der Anzeigengruppe: SB und SD haben keine negativen Targets auf Kampagnenebene.
• Epinium prüft die Gebots- und Budgetgrenzen des Marktplatzes nur bei Sponsored Products, vor dem Senden. Bei Brands und Display wendet es keine eigenen Grenzen an: Amazon validiert, und sein Grund kommt in der Antwort zurück, pro Entität mit result: "failed" oder, beim Anlegen von Targets, in failure_details, wo reference das Target identifiziert (Keyword, ASIN, SKU oder die Zielgruppen-, Kategorie- oder Standort-ID).

Ad Product	Akzeptierte targetType
Sponsored Products	KEYWORD, PRODUCT, PRODUCT_CATEGORY
Sponsored Brands	Die von Sponsored Products plus THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND oder KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES)
Sponsored Display	KEYWORD; PRODUCT per ASIN oder per sku, mit productMatchType PRODUCT_EXACT oder PRODUCT_SIMILAR; PRODUCT_CATEGORY mit Verfeinerungen (Marke, Preis, Bewertung, Altersgruppe, Prime-Berechtigung); THEME (INTERESTED_AUDIENCE); PRODUCT_AUDIENCE (ASIN + event PURCHASE oder VIEW + lookback von 7, 14, 30, 60, 90, 180 oder 365 Tagen); AUDIENCE (audienceId), CONTENT_CATEGORY (contentCategoryId) und LOCATION (locationId)

Die IDs für AUDIENCE, CONTENT_CATEGORY und LOCATION stammen aus der Amazon-Ads-Konsole: die API listet sie noch nicht auf.

Optimierungskonfiguration

Mit derselben Berechtigung campaigns:write kannst du neben dem Schreiben bei Amazon auch die Konfiguration lesen und ändern, die der Optimierer von Epinium nutzt: was er auf jeder Kampagne verfolgt. Das ist eine andere Oberfläche als die des vorigen Abschnitts, und man sollte sie nicht verwechseln.

Sie geht nie an Amazon. Es ist eine eigene Konfiguration von Epinium, die der Optimierer bei seinem nächtlichen Lauf konsumiert, keine Angabe des Amazon-Kontos. Deshalb gelten hier zwei Regeln aus „Bei Amazon schreiben" nicht: Es braucht keinen Idempotency-Key-Header - es gibt keinen Hin- und Rückweg zu Amazon, den ein erneuter Versuch verdoppeln könnte - und die Änderung hinterlässt keine Zeile in /v1/advertising-changes, das nur erfasst, was an Amazon gesendet wurde.

Sie wird mit expand gelesen, nicht standardmäßig. GET /v1/campaigns und GET /v1/campaigns/{id} geben optimizationConfig nur zurück, wenn du ?expand[]=optimizationConfig anfragst. Das ist Opt-in, weil nur sehr wenige Kampagnen diese Konfiguration gespeichert haben: ohne expand käme die Spalte fast immer als null zurück.

Was sich mit PATCH /v1/campaigns/{id}/optimization-config festlegen lässt, in Geschäftssprache:

• Das Ziel: ein Ziel-ACOS oder -ROAS, oder ein Volumenziel - Impressions oder Bestellungen - mit einer ACOS-Obergrenze daneben.
• Die Gebotslimits: die Unter- und Obergrenze, die es nicht überschreiten darf, die Obergrenze des Placement-Multiplikators, und die Mindestausgabe, bevor ein Target negativiert wird.
• Das monatliche Budget, das der Optimierer verfolgt - nicht das tägliche Amazon-Budget der Kampagne, das mit PATCH /v1/campaigns/{id} geändert wird und ein anderes Feld mit demselben Namen ist.
• Die Harvesting-Overrides der Kampagne: ihr Discovery-Level und ob sie das Targeting von Konkurrenz-ASINs erlaubt.
• Welche Workflows sie optimieren.

Der letzte Punkt ist der, der wirklich zählt: Workflows zuzuweisen ist es, was die Kampagne unter Optimierung stellt, kein anderes Feld dieses Blocks. linkedWorkflowDefinitionIds erzwingt die Aufnahme - der Workflow verarbeitet sie jede Nacht, auch wenn sein eigener Filter sie nicht ausgewählt hätte - und ist der Weg, auf dem ein Workflow echte Gebote bei Amazon bewegt; bestätige es mit der Person, bevor du es schreibst, genau wie beim Einschalten einer Automatisierung. Ein Workflow mit automatischer Auswahl kann sie auch von sich aus aufgreifen, und workflowsOptOut: true lehnt diese automatische Auswahl ab. Nur excludedWorkflowDefinitionIds nimmt sie mit Garantie heraus: es gewinnt immer, was auch immer der Rest sagt.

aiEnabled ist nicht der Schalter des Optimierers

Es ist das Einverständnis des Kontoinhabers und geht als Tag epinium:ai_enabled an Amazon. Es auf false zu setzen nimmt die Kampagne nicht aus der Optimierung heraus: dafür ist excludedWorkflowDefinitionIds da, oder sie aus linkedWorkflowDefinitionIds zu entfernen.

optimizeDate und optimizingSince sind nur lesbar - der Optimierer selbst stempelt sie - und einen der beiden zu schreiben, ergibt einen 400.

POST /v1/campaigns/optimization-config/batch wendet denselben Patch auf bis zu 1000 Kampagnen an, und es ist nicht alles-oder-nichts: es antwortet mit einer Zeile pro Kampagne, in der Reihenfolge, in der du sie gesendet hast, und jede wird gegen ihren eigenen gespeicherten Zustand geprüft - eine Obergrenze, die für ein Ziel Pflicht ist, kann für ein anderes optional sein - sodass eine Zeile scheitern kann, ohne die anderen zu beeinträchtigen.

Zwei Statuscodes, die man auseinanderhalten sollte, genau wie beim Schreiben bei Amazon: eine Validierungsablehnung - ein Ziel außerhalb des Bereichs, ein Workflow, der nicht deiner ist - antwortet 200 mit result: "failed" und dem Grund in reason. Eine Kampagne, die nicht existiert oder zu einem anderen Konto gehört, antwortet 404 beim einzelnen PATCH; im Stapel dagegen kommt dieselbe Kampagne als failed-Zeile mit reason: "not_found" zurück - genau damit eine schlechte Zeile nicht die übrigen 999 mit sich reißt.

Route	Was sie tut
PATCH /v1/campaigns/{id}/optimization-config	Die Optimierungskonfiguration einer Kampagne ändern
POST /v1/campaigns/optimization-config/batch	Dieselbe Konfiguration auf bis zu 1000 Kampagnen, eine Zeile pro Ergebnis

Aufgaben schreiben

Mit der Berechtigung tasks:write legt die API Aufgaben an und entscheidet über ihre Vorschläge, genau wie du es unter Prozesse → Aufgaben tust. Das ist der Baustein, mit dem ein Assistent oder eine Integration Änderungen vorschlagen kann und eine Person sie prüft, bevor sie bei Amazon ankommen.

Vier Dinge, die du vor dem ersten Aufruf wissen solltest:

• Annehmen heißt nicht anwenden. Es sind zwei Schritte: jeden Vorschlag annehmen oder ablehnen, und danach POST /v1/tasks/{id}/apply. Dann gehen Kampagnenänderungen — Tagesbudget, Status und Name — sofort an Amazon, und die Antwort sagt, welche durchgingen (applied) und welche abgelehnt wurden (failed). Produktänderungen werden in eine Warteschlange gestellt (enqueued) und im Hintergrund angewandt: um zu erfahren, ob sie durchgingen, lies die Vorschläge erneut und sieh dir appliedAt und applyError an.
• Ein Vorschlag, den nichts anwenden kann, ist eine Notiz. Heute werden Produktvorschläge und Kampagnenvorschläge mit fieldPath angewandt; die ohne, und die für Ad Groups, Targets, Product Ads und Suchbegriffe, bleiben Notizen. Sie anzunehmen hält die Entscheidung fest und ändert nichts, und die Antwort sagt das mit autoApplySkipped: true. Das ist kein Fehler. Beim Anlegen dagegen wird ein Kampagnenvorschlag mit einem anderen Feld als dailyBudget, state oder name, oder mit einem Wert, der sich nicht anwenden lässt, mit einem 400 abgelehnt: ihn zu speichern hieße, eine Änderung zu versprechen, die niemand vornehmen wird.
• Die Vorschläge kommen mit der Aufgabe. Bis zu 50 in items beim Anlegen, jeder auf eine Entität deines Kontos bezogen; nachträglich kommen keine hinzu. Eine Entität, die nicht existiert oder zu einem anderen Konto gehört, lässt die ganze Aufgabe scheitern, ohne dass etwas angelegt wird.
• Eine Aufgabe zu erledigen ist endgültig. Ihre offenen Vorschläge werden nicht mit ihr erledigt: sie bleiben eingefroren und lassen sich nicht mehr annehmen. Entscheide zuerst über die, die dir wichtig sind, und schließe die Aufgabe danach ab. Das Erledigen setzt auch keinen Workflow fort.

Route	Was sie tut
POST /v1/tasks	Eine Aufgabe anlegen, mit ihren Vorschlägen
PATCH /v1/tasks/{id}	Titel, Beschreibung, Priorität und Ablaufdatum
POST /v1/tasks/{id}/resolve	Sie erledigen oder verwerfen
PATCH /v1/task-items/{id} · POST /v1/task-items/batch	Vorschläge annehmen oder ablehnen, optional mit deinem eigenen Wert in appliedValue
POST /v1/tasks/{id}/apply	Das Angenommene anwenden

Wie bei Amazon verlangt jeder Schreibvorgang Idempotency-Key, und der Stapel von Vorschlägen ist nicht alles-oder-nichts: er antwortet mit einer Zeile pro Vorschlag, und applied zählt die, die festgehalten wurden. Eine Aufgabe anlegen, bearbeiten oder erledigen kostet einen festen Betrag pro Aufruf; Annehmen oder Ablehnen wird pro festgehaltenem Vorschlag abgerechnet. Anwenden wird nicht extra abgerechnet: jeder Vorschlag wurde schon beim Annehmen abgerechnet.

Keyword-Cluster schreiben

Mit der Berechtigung catalog:write legt die API deine Keyword-Cluster an und bearbeitet sie, dieselben, die du unter Segmentierung → Cluster verwaltest: eine benannte Gruppe von Produkten mit den positiven Keywords, für die sie ranken oder beworben werden sollen, und den negativen Keywords, von denen sie sich fernhalten sollen. So kann ein Assistent, der eine Keyword-Lücke gefunden hat, sie dort hinterlegen, wo die SEO-Prompts von Epinium, die Keyword-Entdeckung des Optimierers und der Cluster-Filter der Produktdiagramme sie aufgreifen.

Vier Dinge, die du vor dem ersten Aufruf wissen solltest:

• Nichts erreicht Amazon. Ein Cluster lebt in Epinium. Deshalb hinterlassen diese Schreibvorgänge keine Zeile in /v1/advertising-changes, und deshalb wird dein KI-Client dich nicht um Bestätigung bitten.
• Bearbeitet wird per Delta, nicht durch Ersetzen. PATCH /v1/clusters/{id} nimmt addPositiveKeywords, removePositiveKeywords, addNegativeKeywords, removeNegativeKeywords, addProducts, removeProducts und name; schicke nur, was sich ändert. Ein Keyword hinzuzufügen, das schon da ist, aktualisiert seine Sprache, seine Bewertung und seinen Zweck, abgeglichen über den Text; eines zu entfernen, das nicht da ist, tut nichts. Ein Cluster fasst bis zu 100 positive und 50 negative Keywords, gezählt nach der Änderung, und ein Keyword kann nicht zugleich positiv und negativ sein.
• Keywords folgen den Regeln der App. Kleingeschrieben, bis zu 80 Zeichen, der Zeichensatz von Amazon, kein - oder . am Anfang und kein -, + oder . am Ende; Duplikate werden zusammengeführt. language ist ein Code wie es-ES oder en-GB, epiniumScore geht von 1 bis 5 und purpose ist SEO, PPC oder beides (standardmäßig beides).
• Ein geschützter Cluster wird mit 409 abgelehnt. Einen Cluster in der App zu schützen ist die Entscheidung einer Person, und diese API kann sie nicht rückgängig machen: hebe den Schutz zuerst unter Segmentierung → Cluster auf. Das Feld protected in der Antwort sagt es dir, bevor du es versuchst.

Route	Was sie tut
POST /v1/clusters	Einen Cluster anlegen, mit seinen Keywords und Produkten, falls du sie schon hast
PATCH /v1/clusters/{id}	Keywords und Produkte hinzufügen oder entfernen, oder ihn umbenennen
DELETE /v1/clusters/{id}	Ihn löschen, ohne Weg zurück

Jedes Produkt, das du verknüpfst, muss zu deinem Konto gehören — für eine Agentur zu den Verbindungen, die das Konto mit dir geteilt hat — und ein Katalogprodukt sein (type seller oder vendor in /v1/products; Werbeprodukte werden abgelehnt), sonst wird der ganze Aufruf mit einem 400 abgelehnt, der die überzähligen Ids nennt, und nichts wird geschrieben. Der Cluster gehört der Person hinter der Zugangsdaten und erscheint deshalb in der Tabelle der App unter ihrem Namen. Löschen ist endgültig - es gibt keinen Papierkorb - und wird mit einem 409 abgelehnt, solange der Cluster geschützt ist oder eine Smart Campaign ihn als Basis-Cluster nutzt; der Fehler nennt diese Smart Campaigns, die zuerst geändert oder gelöscht werden müssen. Jeder Schreibvorgang kostet einen festen Betrag pro Aufruf, und das Cluster-Kontingent des Plans gilt hier wie in der App.

Grenzen

• Metriken brauchen einen Zeitraum. start_date und end_date sind bei allen Metrik-Ressourcen Pflicht.
• Der Zeitraum hat ein Maximum, und es hängt von der Granularität ab. Mit granularity=daily sind es 93 Tage, mit total oder mit den Kalenderperioden (weekly, monthly, quarterly, yearly) 366. Bei Targets und Suchbegriffen, den schwersten Ressourcen, sinkt das auf 31 und 93. Wer mehr anfragt, erhält einen Fehler mit dem exakten Limit. Beide Daten liegen im Zeitraum.
• Listen paginieren auf zwei Arten. Katalog- und Strukturressourcen nutzen einen Cursor (starting_after); Metrik-Ressourcen nutzen limit und offset. In beiden Fällen sagt has_more, ob eine weitere Seite folgt.
• Es gibt ein Anfragelimit pro Token. Bei Überschreitung kommt ein 429, und es genügt, langsamer erneut zu versuchen.
• Es gibt außerdem ein Limit für gleichzeitige Anfragen. Ein 429 kann „zu viele gleichzeitig“ bedeuten, nicht nur „zu viele pro Minute“; ein 503 bedeutet, dass der Server momentan ausgelastet ist. Beide bringen Retry-After mit und beide sind vorübergehend: erneut versuchen, mit weniger parallelen Anfragen.
• Eine Antwort kann nicht mehr als 5.000 Objekte expandieren. expand über Listen — die Produkte eines Clusters, die Länder einer Verbindung — multipliziert sich auf jeder Ebene. Darüber kommt ein 400, der nennt, wie viele Objekte zurückgekommen wären: limit senken, ein expand weglassen, oder diese Daten beim eigenen Endpoint anfragen.

Credits

Aufrufe dieser API verbrauchen Credits deines Kontos. Was jede Ressource kostet, siehst du in der Anwendung unter Einstellungen → Guthaben.

Jede Antwort sagt dir, was du verbraucht hast:

Header	Was es ist
X-Epinium-Credits-Cost	Was dieser Aufruf gekostet hat
X-Epinium-Credits-Remaining	Was dir bleibt. Der Wert ist ungefähr: wenn gleichzeitig anderes verbraucht, kann er abweichen
X-Epinium-Credits-Breakdown	Die Aufschlüsselung, pro Ressource und Einzelpreis: product=100x1,country=100x0
X-Epinium-Credits-Max	Das Maximum, das der Aufruf kosten konnte, vor der Ausführung berechnet

Drei Dinge, die man wissen sollte:

• Berechnet wird nur, was geliefert wird. Ein fehlgeschlagener Aufruf kostet nichts, und ein expand, das keine Daten liefert — weil dein Token diesen Scope nicht hat oder der Datensatz zu einem anderen Konto gehört — ebenfalls nicht.
• Bei Metriken kostet auch der Zeitraum, nicht nur die Zeilen. Ein Jahr mit limit=1 anzufragen ist nicht günstig: Neben jeder zurückgegebenen Zeile wird jeder Tag des Zeitraums berechnet, denn genau das muss gelesen werden, um zu antworten, mit mindestens 3 Tagen pro Aufruf. Wer weniger ausgeben will, verkürzt den Zeitraum.
• Für eine Summe group_by nutzen, nicht paginieren. Eine Kontosumme umfasst nur wenige Zeilen, eine pro Währung, während man beim Paginieren des Katalogs zum Aufsummieren jedes Produkt auf jeder Seite bezahlt. In einem echten Konto kostet die Umsatzsumme eines Monats 157 Credits mit group_by=account und rund 17.600 per Paginierung.

Reichen die Credits nicht, kommt ein 402 — vor der Ausführung: du bleibst nie mit einer halben Antwort zurück. Und er sagt nicht nur nein, sondern was zu ändern ist und auf welchen Wert:

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_credits",
    "message": "insufficient credits: needs up to 366 (campaignMetrics=1x1,campaignMetrics:window=365x1), 120 available. Shorten the date range to 119 days or less.",
    "param": "end_date"
  }
}

param ist dieselbe Abhilfe maschinenlesbar: limit, end_date oder include_total. Fehlt das Feld, bringt keine einzelne Parameteränderung den Aufruf durch und es muss aufgeladen werden.

Parameter und Antworten jedes Endpoints

Die Tabelle oben sagt, welche Ressourcen es gibt. Um die Eingabeparameter und die genaue Form jeder Antwort zu sehen, gibt es zwei Wege:

• Durchsuchbare Referenz — jeder Endpoint mit seinen Parametern, deren Typen und einer Beispielantwort. Wird aus der API selbst generiert und kann daher nicht veralten. Auf Englisch.
• OpenAPI-Schema — das rohe OpenAPI-3.0-Dokument, zum Import in Postman, Insomnia oder einen Client-Generator. Kein Token nötig.