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, deine GuV mit Produktkosten, 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, legt den Kostenpreis deiner Produkte an oder aktualisiert ihn, erfasst ihre Einkäufe bei Lieferanten, speichert Änderungen an jedem Attribut deiner Amazon-Listings und legt auf Amazon Angebote, neue Produkte und Variantenfamilien neu an, und sie legt in deinen verbundenen Shopify- und WooCommerce-Shops Produkte und Inhalte an, bearbeitet und löscht sie. In deinem Amazon-Katalog bleibt, was du speicherst, ausstehend und erreicht Amazon erst, wenn es veröffentlicht wird, in der App oder über die API mit ihrer eigenen Berechtigung; der Katalog deiner Shops ändert sich direkt, ohne ausstehend zu bleiben. 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
- Gehe zu Einstellungen → API Keys
- Klicke auf API Key erstellen und gib ihm einen Namen, der an den Zweck erinnert
- Wähle die benötigten Berechtigungen aus
- Kopiere den Schlüssel und bewahre ihn sicher auf
- 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, Cluster, benutzerdefinierte Prompts und Markenidentität, mit ihren Kennzahlen: Umsatz, Amazon-Gebühren und Marge, Retouren, Bestand und bei Vendor Bewertungen; sowie deine GuV, mit Produktkosten und deinen eigenen Ausgaben, wenn dein Plan sie einschließt |
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, die gruppierten Produkte und die verwendeten Prompts. Benutzerdefinierte Prompts anlegen und bearbeiten. Deine Markenidentität anlegen und bearbeiten, mit einem Profil pro Wettbewerber. Änderungen an den Attributen deiner Amazon-Listings aus einer Datei speichern, als zur Veröffentlichung ausstehende Änderungen. Neue Angebote auf Amazon speichern und verwerfen (Angebote zu Produkten, die es schon gibt, neue Produkte und Familien) und Produktbilder hochladen. Nichts erreicht Amazon, bis du es veröffentlichst |
costs:write | Den Stückkostenpreis und die Versandkosten deiner Produkte anlegen oder aktualisieren und ihre Einkäufe erfassen, korrigieren und löschen, einzeln oder per Import aus einer Datei, sowie deine eigenen Ausgaben und ihre Kategorien anlegen, ändern und löschen |
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. Die KI von Epinium Listings als Vorschläge einer Aufgabe umschreiben lassen |
workflows:write | Workflows anlegen, kopieren, bearbeiten, einschalten, pausieren, löschen und wiederherstellen, und sie ausführen oder simulieren |
catalog:publish | Die ausstehenden Listing-Änderungen und neuen Angebote, die du auswählst, auf Amazon veröffentlichen (POST /v1/pending-listing-changes/publish), auf demselben Weg wie die Schaltfläche Veröffentlichen der App. Lässt sich nicht rückgängig machen. Braucht auch catalog:write |
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 |
/v1/pnl/* | Deine GuV: Kaskade, Tabelle pro Produkt, pro Cluster, pro Vertriebskanal, kanalübergreifende Werbung, Aktualität, Margenverluste und Bestand - erklärt unter Die GuV mit Produktkosten |
/v1/prompts | Deine benutzerdefinierten Prompts; mit catalog:write legst du sie auch an und bearbeitest sie |
/v1/brand-identities | Deine Markenidentität, mit einem Profil pro Wettbewerber; mit catalog:write legst du sie auch an und bearbeitest sie - erklärt unter Deine Markenidentität schreiben |
/v1/listing-files | Die Dateien mit Listing-Änderungen, die du in den letzten 7 Tagen hochgeladen hast; zum Hochladen reicht catalog:read, um von Hand geschriebene Zeilen als Datei zu speichern, braucht es catalog:write |
/v1/listing-updates | Die Änderungen einer Datei vorbereiten und validieren, ohne etwas zu speichern; mit catalog:write sie als zur Veröffentlichung ausstehend speichern - erklärt unter Listings aus einer Datei ändern |
/v1/listing-drafts | Deine neuen Angebote auf Amazon und ihr Stand; mit catalog:write sie speichern und verwerfen. Um das Produkt zu suchen und sie zu validieren, /v1/amazon-catalog/search, /v1/amazon-product-types/search, /v1/amazon-shipping-templates und /v1/listing-drafts/validate - erklärt unter Neue Angebote auf Amazon anlegen |
/v1/listing-images | Mit catalog:write ein Produktbild für ein Listing oder ein neues Angebot hochladen: JPG, PNG, GIF oder TIFF, bis 8 MB, 30 Tage aufbewahrt |
/v1/pending-listing-changes | Was auf Amazon zur Veröffentlichung aussteht, Änderungen und neue Angebote; mit catalog:write und catalog:publish es veröffentlichen |
/v1/publications | Jede Veröffentlichung auf Amazon und wie sie pro Land läuft, wie der Bereich Veröffentlichungen der App |
Advertising — campaigns:read
| Endpoint | Was er zurückgibt |
|---|---|
/v1/campaigns | Deine Amazon-Advertising-Kampagnen |
/v1/campaigns/budget-usage | Wie viel jede Kampagne heute von ihrem Tagesbudget ausgegeben hat, laut Amazon und höchstens eine halbe Stunde verzögert |
/v1/campaign-metrics | Ausgaben, Umsatz, ACOS und ROAS pro Kampagne |
/v1/portfolios | Deine Portfolios und das Budgetlimit, das jedes seinen Kampagnen setzt |
/v1/portfolios/budget-usage | Wie viel jedes Portfolio in diesem Zeitraum von seinem Limit ausgegeben hat, sein Tempo und was es pro Tag ausgeben kann, um genau beim Limit zu landen |
/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. nullist nicht0.nullheißt, dass Amazon den Wert nicht gemeldet hat;0heißt echte Null. Einacosvonnullist eine Kampagne, die ausgegeben und nichts verkauft hat, nicht kostenlose Werbung. Undnew_to_brand_saleskommt bei Sponsored Products alsnull, 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
salessie dort enthält, wo sie gilt: Ziehe das eine nicht vom anderen ab.margin_before_adsist, 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-metricsab. 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_coveragesind 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 istnullbei jeder Granularität außertotal, wenn das Produkt nichts verkauft hat oder, beim Gruppieren, wenngroup_bydas Land nicht enthält. Mitorder_by=days_of_coverage&order=asckommen 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=salesRankssagt, zu welcher Kategorie jede Position im Best Seller Rank gehört, und bei Vendor liefertexpand=customerFeedbackdie 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_bysummiert über Entitäten hinweg.accountliefert die Summe des Kontos;countryundconnectionschlüsseln nach Land oder nach Verbindung auf und lassen sich kombinieren, indem du den Parameter wiederholst (group_by[]=connection&group_by[]=country).accountlä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).granularityteilt den Zeitraum in Kalenderperioden. Nebentotalunddailyakzeptiert esweekly,monthly,quarterlyundyearly, und jede Zeile trägt indateden 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 liefertmonthlyden Januar vom 15. bis 31., den ganzen Februar und den März vom 1. bis 10.clustergrenzt auf eine Produktfamilie ein. Bei den Metriken für Seller, Vendor und beworbene Produkte lässtcluster=<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=clusterliefert eine Zeile pro Cluster. Bei denselben drei Metriken gibtgroup_by=clusterdie Zahlen jedes deiner Cluster in einem einzigen Aufruf zurück, mit seiner ID inclusterund seinem Namen incluster_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 mitcountryundconnectionkombinieren und mit dem Filtercluster, 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.
Die GuV mit Produktkosten
Das ist dieselbe Gewinn- und Verlustrechnung, die du unter Rentabilität → P&L siehst: Umsatz, Amazon-Gebühren und Logistik, Werbung und, wenn dein Plan es einschließt, deine Produktkosten und deine eigenen Ausgaben, mit derselben Berechnung und denselben Zahlen.
Was du siehst, hängt von deinem Plan ab. In Free und Guru reicht die GuV bis margin_before_ads: was nach Amazon bleibt, vor Werbung und vor Produktkosten - nenne das nicht „Gewinn", denn das ist es nicht. In Business und Master geht sie bis zum Ende: Deckungsbeitrag, jede Produktkosten-Zeile und ihre Abdeckung, und deine eigenen Ausgaben bis zum Nettogewinn. includes_product_cost in jeder Antwort sagt dir, welche der beiden du gerade siehst, du musst also nicht raten, ob die Zahlen zu deinen Erwartungen passen. Margenverluste (/v1/pnl/margin-leaks und /v1/pnl/category-medians) gibt es nur in Business und Master: In Free und Guru antwortet es mit 403 und code: "plan_feature_not_allowed", und seine Antworten enthalten kein includes_product_cost, weil sie die Kosten immer enthalten. Dasselbe gilt für den Bestand (/v1/pnl/inventory), der mit den Produktkosten bewertet wird.
| Endpoint | Was er zurückgibt |
|---|---|
/v1/pnl/cascade | Die Kaskade des Zeitraums: Umsatz, Erstattungen, Gebühren, Logistik, Werbung, Produktkosten und eigene Ausgaben bis zum Nettogewinn, Monat für Monat oder Tag für Tag |
/v1/pnl/products | Eine Zeile pro Produkt, mit ihrem Deckungsbeitrag und ihrer Kostenabdeckung |
/v1/pnl/products/{id} | Das Detail eines Produkts: seine eigene Kaskade, Monat für Monat |
/v1/pnl/clusters | Eine Zeile pro Cluster, mit Deckungsbeitrag, Kostenabdeckung und Anzahl der Produkte |
/v1/pnl/channels | Eine Zeile pro Vertriebskanal (Seller, Vendor…), mit seiner nach Plattform aufgeschlüsselten Werbung |
/v1/pnl/ads-matrix | Die kanalübergreifenden Werbeausgaben: auf welchem Vertriebskanal jede Plattform wirbt |
/v1/pnl/freshness | Das Datum der letzten Daten jeder Quelle -Amazon, Werbung und Produktkosten-, um zu wissen, ob das Gelesene schon vollständig ist |
/v1/pnl/margin-leaks | Die Produkte, die gegenüber dem Vorzeitraum Marge verloren haben, sortiert nach gefährdetem Betrag, mit Status, Hauptursache und den Summen der ganzen Rangliste: dasselbe wie Margenverluste |
/v1/pnl/category-medians | Das Übliche in deinem Konto: der Median des Anteils jeder Kostenart am Nettoumsatz, um zu sehen, ob die Kosten eines Produkts aus dem Rahmen fallen |
/v1/pnl/inventory | Das gebundene Kapital in den Lagern von Amazon: der heutige FBA-Bestand zu Kosten bewertet, mit seinen Tagen Bestand, seiner Rotation und der Lagerung bis zum Verkauf: dasselbe wie Bestand |
Neun Dinge, die du vor dem ersten Aufruf wissen solltest:
- Das ist der einzige Teil der API, der die Währung umrechnet. Alle anderen Ressourcen geben jeden Betrag in der Währung zurück, in der er entstanden ist; hier fragst du eine
currencyan und alles wird darin umgerechnet, zum Wechselkurs des Tages, an dem jeder Betrag entstand. Ein Tag ohne Wechselkurs fällt auf einen ungefähren zurück, nie auf einen Fehler. - Die eigenen Ausgaben kommen in
own_expenses. Die variablen sind bereits im Abschnittvariable_expensesabgezogen, vor dem Deckungsbeitrag, undown_expenses.periods[].variableschlüsselt sie nach Kategorie auf. Die festen (fixed) werden danach abgezogen, bisnet_profit. Da sie für das ganze Konto gelten, kommenfixedundnet_profitmitconnection,countryodercluster, oder mit einem Token, das nicht alle Verkaufsverbindungen erreicht, alsnullzurück, undfixed_unavailablesagt warum:filteredoderpartial_access. Hat das Konto keine festen Ausgaben, fehlt nichts, undnet_profitkommt auch mit Filter oder mit einem Token zurück, das nicht alle Verbindungen erreicht. In der Tabelle pro Produkt ist die Spalteown_expensesder Anteil der variablen Ausgaben jedes Produkts. coveragesagt, welcher Teil des Umsatzes einen echten Kostenwert hat. Ein Produkt ohne hinterlegte Kosten wird nicht still verworfen oder auf null gesetzt:coverage.covered_salesim Verhältnis zucoverage.total_salessagt dir, welcher Anteil der Zahl verlässlich ist. Incoverageistestimated_salesder Teil voncovered_salesmit geschätzten Kosten: Der Bestand hat mehr Einheiten verkauft, als die erfassten Einkäufe hinterlassen haben, und diese Verkäufe tragen die letzten Durchschnittskosten.breakeven_acos, unter/v1/seller-product-metrics, ist der ACOS, den du dir bei diesem Produkt in der Werbung leisten kannst, bevor du Geld verlierst, berechnet mit deiner echten Marge und deinen echten Kosten -nie mit einem angenommenen Gebührenprozentsatz. Er kommt alsnullzurück -nie als erfundene Zahl-, wenn das Produkt keine vollständigen Kosten hat, im Zeitraum nichts verkauft hat, die Kosten in einer anderen Währung als der des eigenen Marktplatzes erfasst sind (diese Ressource rechnet Währungen nicht um, anders als/v1/pnl/*), oder wenn dein Plan keine Produktkosten einschließt (Free und Guru).- Produktkosten bleiben bei einem Downgrade erhalten, sie werden nicht gelöscht. Wechselst du zu Guru, bleiben die bereits hinterlegten Kosten erhalten: Sie werden nur nicht mehr ausgeliefert. Sie kommen zurück, sobald du wieder hochstufst.
clustergrenzt/v1/pnl/cascade,/v1/pnl/products,/v1/pnl/clusters,/v1/pnl/freshness,/v1/pnl/margin-leaks,/v1/pnl/category-mediansund/v1/pnl/inventoryauf die Produkte eines oder mehrerer Cluster ein, wie bei den Metriken: bei mehreren IDs deren Vereinigung, und ein Cluster ohne Produkte liefert ein leeres Ergebnis, keinen Fehler. Die Werbung zählt nur die Ausgaben dieser Produkte: Sponsored Brands und Kampagnenausgaben, die keinem bestimmten Produkt zugeordnet sind, bleiben außen vor, weil sie zu keinem Cluster gehören. In/v1/pnl/clusterszählt ein Produkt, das in zwei Clustern ist, in beiden, und was in keinem Cluster ist, erscheint nicht./v1/pnl/margin-leaksliefert standardmäßig die Produkte in allen drei Zuständen, wie der Bildschirm; mitstatusbehältst du die, die du wählst. Im selben Aufruf gibtsummaryan, wie viele es je Zustand gibt, und den gefährdeten Gesamtbetrag der Produkte mit Verlust und Beobachten der ganzen Rangliste, ohne zu blättern, und jede Zeile trägtmain_cause, die Kostenart mit dem größten Margenverlust, berechnet wie auf dem Bildschirm. Hat der Vorzeitraum keine Umsätze, isthas_previous_salesfalse: Die leere Liste heißt dann, dass es nichts zu vergleichen gibt, nicht, dass es keine Verluste gibt./v1/pnl/inventoryist der heutige Bestand, ohne Zeitraum: eine Zeile pro Bestand, und in der EU erscheint eine paneuropäische SKU nur einmal, mit allen ihrencountries, also addiere keine Zeilen über Länder hinweg.summaryliefert das gebundene Kapital des gesamten Umfangs und seine Aufteilung nach Rotation, ohne Paginierung und unabhängig vonrotationundsearch.currencyist Pflicht: Die Kosten werden zum letzten Wechselkurs umgerechnet, die Lagerung zum Kurs des jeweiligen Tages. Es zählt nur der FBA-Bestand deiner Seller-Verbindungen.- Die heute gültigen Kosten jedes Produkts kommen in
/v1/products. Das Feldcostenthältcogsundshipping, jeweils mit dem Stückbetrag, seiner Währung,valid_fromundsource, odernull, wenn es keine hat. Mitcost_statebehältst du die aktiven Produktewith(mit Kosten),missing(ohne Kosten) odermissing_with_sales(ohne Kosten und mit Verkäufen in den letzten 30 Tagen, die die Marge am stärksten aufblähen), und mitinclude_totalerfährst du, wie viele es sind. Es ist dasselbe, was du unter Kosten und Ausgaben siehst. In Free und Guru istcostnullundcost_stateantwortet mit403.
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 inerror. 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
PAUSEDangelegt, sofern du nicht ausdrücklichENABLEDverlangst, 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 keinstate-Wert, den du versehentlich neben einer Gebotsänderung setzen könntest, sondern ein eigener Aufruf mit eigenem Verb. Willst du nur die Ausgaben stoppen, nutzestate: "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>/batchnimmt bis zu 1000 Entitäten und antwortet mit einer Zeile pro Entität, in der Reihenfolge, in der du sie gesendet hast.appliedist 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
PATCHStatus und Budget und Amazon nimmt das erste an und lehnt das zweite ab, kommt diese Entität alsfailedmit 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.
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/adgroupsund/v1/product-adsgelten 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. WelchertargetTypeakzeptiert 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, infailure_details, woreferencedas 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 dirappliedAtundapplyErroran. - Ein Vorschlag, den nichts anwenden kann, ist eine Notiz. Heute werden Produktvorschläge und Kampagnenvorschläge mit
fieldPathangewandt; 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 mitautoApplySkipped: true. Das ist kein Fehler. Beim Anlegen dagegen wird ein Kampagnenvorschlag mit einem anderen Feld alsdailyBudget,stateodername, oder mit einem Wert, der sich nicht anwenden lässt, mit einem400abgelehnt: ihn zu speichern hieße, eine Änderung zu versprechen, die niemand vornehmen wird. - Die Vorschläge kommen mit der Aufgabe. Bis zu 50 in
itemsbeim 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 |
POST /v1/tasks/listing-optimizations | Die KI von Epinium Listings umschreiben lassen, als Vorschläge einer Aufgabe - erklärt unter Listings mit der KI von Epinium umschreiben |
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.
Listings mit der KI von Epinium umschreiben
Mit der Berechtigung tasks:write lässt POST /v1/tasks/listing-optimizations die KI von Epinium den Titel (mit seinen Highlights, den Item Highlights), die Bullet Points, die Beschreibung und die Suchbegriffe von 1 bis 20 Produkten deines Katalogs umschreiben. Es ist dieselbe Generierung wie in der App: Sie folgt den Keyword-Clustern jedes Produkts, den damit verknüpften Prompts und deiner Markenidentität. Das Ergebnis ändert kein Listing: Es bleibt als Vorschläge in einer Aufgabe, der des Onboardings, damit eine Person sie prüft.
Fünf Dinge, die du vor dem ersten Aufruf wissen solltest:
- Sie antwortet sofort und generiert danach. Die Antwort ist ein
202mit der Id der Aufgabe (task) und dem, was vom Limit übrig ist (limit). Jeder Vorschlag erscheint in der Aufgabe, sobald er fertig ist: Lies sie unter/v1/task-items, gefiltert nachtask. - Nichts erreicht Amazon, ohne dass du es siehst. Du nimmst jeden Vorschlag an oder lehnst ihn ab und wendest die Aufgabe an (
POST /v1/tasks/{id}/apply), wie jede andere. Anwenden lässt die Änderungen zur Veröffentlichung ausstehend: Sie erreichen Amazon, wenn du sie veröffentlichst, aus der App oder mitPOST /v1/pending-listing-changes/publish, dascatalog:publishverlangt. - Sie verbraucht keine Credits von dir, hat aber ein Limit. Epinium bezahlt das Umschreiben, bis zu 20 Produkte pro Konto insgesamt. Jedes Produkt jedes Aufrufs zählt, auch wenn du eines erneut startest oder seine Generierung fehlschlägt. Ein Aufruf, der mehr Produkte verlangt, als dir bleiben, wird ganz abgelehnt, mit einem
403, dessencodelisting_optimization_limit_reachedist, und es wird nichts generiert;limit(cap,used,remaining) sagt dir in jeder Antwort, wie viele dir bleiben. Das Annehmen oder Ablehnen der Vorschläge wird wie bei jeder Aufgabe abgerechnet. - Du wählst Produkte und Felder.
productssind Ids von Katalogprodukten, Seller oder Vendor (/v1/products; Werbeprodukte gelten nicht).fieldsakzeptierttitle,bullets,descriptionundsearch_terms; ohne es werden alle vier umgeschrieben.titleschreibt auch die Highlights um. - Sie verlangt
Idempotency-Key. Verwende beim erneuten Versuch denselben Schlüssel, sonst verbrauchst du erneut Produkte vom Limit.
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}nimmtaddPositiveKeywords,removePositiveKeywords,addNegativeKeywords,removeNegativeKeywords,addProducts,removeProducts,addPrompts,removePromptsundname; 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.languageist ein Code wiees-ESoderen-GB,epiniumScoregeht von 1 bis 5 undpurposeistSEO,PPCoder beides (standardmäßig beides). - Ein geschützter Cluster wird mit
409abgelehnt. 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 Feldprotectedin der Antwort sagt es dir, bevor du es versuchst.
| Route | Was sie tut |
|---|---|
POST /v1/clusters | Einen Cluster anlegen, mit seinen Keywords, Produkten und Prompts, falls du sie schon hast |
PATCH /v1/clusters/{id} | Keywords, Produkte und Prompts hinzufügen oder entfernen, oder ihn umbenennen |
DELETE /v1/clusters/{id} | Ihn löschen, ohne Weg zurück |
Jeder Prompt, den du verknüpfst, muss zu deinem Konto gehören, sonst wird der Aufruf mit einem 400 abgelehnt, der die überzähligen Ids nennt. 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.
Benutzerdefinierte Prompts schreiben
Mit der Berechtigung catalog:write legt die API deine benutzerdefinierten Prompts an und bearbeitet sie, die aus deiner Prompt-Bibliothek: benannte Anweisungen, denen die KI von Epinium folgt, wenn sie die Inhalte deiner Listings verfasst -Ton, Struktur, Wörter, die verwendet oder vermieden werden sollen-. Zum Lesen reicht catalog:read, unter /v1/prompts, und jeder Cluster liefert in prompts die Ids seiner Prompts; mit expand[]=prompts kommen sie vollständig.
Vier Dinge, die du vor dem ersten Aufruf wissen solltest:
- Ein Prompt ändert für sich allein nichts. Er berührt Amazon nicht und schreibt beim Speichern kein Listing um: er wird angewendet, wenn die Inhalte der Produkte der Cluster generiert werden, mit denen du ihn verknüpfst (
addPromptsinPATCH /v1/clusters/{id}). Wenn mehrere Prompts aus den Clustern eines Produkts für dasselbe Feld gelten, wird nur einer verwendet, also belasse es bei einem Prompt pro Feld. fieldslegt fest, für welche Felder des Listings er gilt:titleAndHighlights(Titel und Artikel-Highlights, die zusammen verfasst werden),product_description,bullet_pointodergeneric_keyword(die Suchbegriffe). Ohnefieldsoder mit[]gilt er für alle. Ein älterer Prompt kann nochitem_nametragen, den Titel allein, der gelesen, beim Schreiben aber nicht mehr akzeptiert wird.- Die Anweisung hat eine Obergrenze: bis zu 2.000 Zeichen, so viele wie in der App. Der Name braucht mindestens 3.
- Beim Bearbeiten ersetzt, was du schickst, das Bisherige:
PATCH /v1/prompts/{id}nimmtname,instructionundfields, undfieldsersetzt die ganze Liste.
| Route | Was sie tut |
|---|---|
POST /v1/prompts | Einen Prompt anlegen |
PATCH /v1/prompts/{id} | Ihn umbenennen oder seine Anweisung oder seine Felder ändern |
Der Prompt gehört der Person hinter den Zugangsdaten. Prompts lassen sich über die API nicht löschen. Jeder Schreibvorgang kostet einen festen Betrag pro Aufruf, und das Prompt-Kontingent des Plans gilt hier wie in der App: hast du es schon erreicht, antwortet das Anlegen mit 403.
Deine Markenidentität schreiben
Mit der Berechtigung catalog:write legt die API deine Markenidentität an und bearbeitet sie, die aus Einstellungen → Marke: den Namen der Marke, ihre Branche, ihre Websites, die deiner Wettbewerber, deine Anmerkungen (Tonfall, Zielgruppe, Wörter, die zu verwenden oder zu meiden sind) und die Marken deines Katalogs, die sie abdeckt. Sie ist der Kontext, den die KI von Epinium beim Verfassen deiner Listings nutzt. Zum Lesen genügt catalog:read, unter /v1/brand-identities. Das sind nicht die Marken deines Katalogs, die unter /v1/product-brands stehen.
Neben den einzelnen Websites in competitor_urls kann jeder Wettbewerber ein eigenes Profil in competitors haben, bis zu 50:
| Feld | Was es ist |
|---|---|
name | Name der Marke oder des Verkäufers. Pflichtfeld |
url | Seine Website oder sein Amazon-Shop |
asins | Die ASINs seiner Produkte, die mit deinen konkurrieren, bis zu 20 |
threat | Wie gefährlich er ist: level (low, medium oder high) und reason, der in den Daten gesehene Grund. Die Stufe kommt nie ohne ihren Grund; gibt es noch keine Belege, lässt man sie weg |
price_position | Sein Preis im Vergleich zu deinem: below, similar oder above |
Vier Dinge, die du vor dem ersten Aufruf wissen solltest:
- Wettbewerberprofile sind in der App noch nicht zu sehen. Sie werden über die API und den MCP gespeichert und gelesen; Einstellungen → Marke zeigt sie noch nicht an.
- Beim Bearbeiten ersetzt eine Liste die bisherige.
PATCH /v1/brand-identities/{id}ändert nur die Felder, die du sendest, abercompetitors,competitor_urls,brand_urlsundproduct_brand_idswerden ganz ersetzt: Um einen Wettbewerber hinzuzufügen, sende die bisherigen plus den neuen. Die vorherigen Werte werden nirgends aufbewahrt. - Die Profile ersetzen
competitor_urlsnicht. Es sind zwei unabhängige Listen, und die Websites, die du schon hattest, bleiben erhalten. Eine Markenidentität, die vor den Profilen gespeichert wurde, hat ein leerescompetitors. - Nichts erreicht Amazon. Die Markenidentität lebt in Epinium: Sie zu speichern berührt deine Listings nicht und schreibt sie nicht um. Über die API lässt sie sich weder löschen noch ihr Logo hochladen.
| Route | Was sie tut |
|---|---|
POST /v1/brand-identities | Eine Markenidentität anlegen |
PATCH /v1/brand-identities/{id} | Ihre Felder oder Listen ändern |
Wie jeder Schreibvorgang verlangt sie Idempotency-Key.
Listings aus einer Datei ändern
Mit der Berechtigung catalog:write speichert die API Änderungen an den Attributen vieler Amazon-Listings auf einmal, ausgehend von einer Excel- oder CSV-Datei: jedes Attribut, das Amazon im Produkttyp des jeweiligen Listings bearbeiten lässt, bei Seller und bei Vendor. Darauf baut der Epinium-MCP auf, wo der ganze Ablauf aus Sicht der Person erklärt ist, die ihn anstößt.
| Route | Berechtigung | Was sie tut |
|---|---|---|
POST /v1/listing-files | catalog:read | Lädt die Datei hoch (.xlsx, .xls oder .csv) und gibt ihre file_id zurück. Sie wird 7 Tage aufbewahrt |
POST /v1/listing-files/rows | catalog:write | Speichert Kopfzeilen und Zeilen, die du schon hast, als Datei, ohne etwas hochzuladen |
POST /v1/listing-updates/prepare | catalog:read | Findet die Produkte der Datei über SKU, ASIN oder EAN und sagt, welche Attribute sie zulassen |
POST /v1/listing-updates/validate | catalog:read | Validiert die Zeilen gegen die Amazon-Regeln jedes Produkttyps, ohne etwas zu speichern |
POST /v1/listing-updates/apply | catalog:write | Speichert die gültigen Zeilen im Hintergrund als zur Veröffentlichung ausstehende Änderungen |
GET /v1/listing-updates/apply/{file_id} | catalog:read | Der Stand dieses Speichervorgangs, was gesendet wurde und was es gekostet hat |
Fünf Dinge, die du vor dem ersten Aufruf wissen solltest:
- Beim Speichern erreicht nichts Amazon.
applylässt die Änderungen zur Veröffentlichung ausstehend, und sie gehen an Amazon, wenn jemand sie in Epinium über Änderungen veröffentlichen oder mitPOST /v1/pending-listing-changes/publishveröffentlicht (siehe Neue Angebote auf Amazon anlegen). - Zusammengehörige Daten verlangen eine Person. Ein Wert, der weitere Angaben zur Pflicht macht, wie bei Batterien, wird nur gespeichert, wenn seine
cascade_idinconfirmed_cascadesmitkommt; sonst geht er zur Prüfung in eine Aufgabe. Der Rest der Zeile wird trotzdem gespeichert. - Abgerechnet werden 5 Credits pro Zeile. Wird die Datei angenommen, werden 5 Credits pro Zeile reserviert, mit einem
402, wenn das Guthaben nicht reicht. Am Ende werden nur die gesendeten Zeilen berechnet und der Rest wird erstattet, bei einem Fehlschlag vollständig. Hochladen, Vorbereiten, Prüfen und das Abfragen des Status werden nicht berechnet. - Preise gehen nach Zielgruppe. Eine Spalte wird mit
offer: { audience, field }deklariert (field:price,min,max,sale_price,sale_startodersale_end);clear: truebewirkt, dass ihre leeren Zellen löschen, unddate_order(dmyodermdy) legt die Reihenfolge mehrdeutiger Daten fest.validateliefert inoffer_clearsdie Preisspalten mit leeren Zellen bei Produkten, die diesen Wert haben, und die Preisregeln als blockierendeoffer_*-Probleme. Bei Vendor wird kein Preis bearbeitet: Diese Spalten kommen innot_applicablemit dem Grundvendor_pricezurück.preparebietet die Preisfelder inoffer_fieldsan. - Eine Datei wird einmal angewendet. Derselbe Aufruf mit denselben Einstellungen gibt den Stand zurück; mit anderen Einstellungen oder bei einer Datei, die nur noch weniger als 24 Stunden aufbewahrt wird, antwortet er mit
409. Wie jeder Schreibvorgang verlangt erIdempotency-Key.
Die Parameter jeder Route stehen in der Katalog-Referenz.
Neue Angebote auf Amazon anlegen
Mit der Berechtigung catalog:write speichert die API neue Angebote: Produkte, die noch nicht in deinem Amazon-Konto sind. Das kann ein Angebot zu einer ASIN sein, die es schon gibt (nur bei Seller), ein neues Produkt oder eine Variantenfamilie, bei Seller und bei Vendor. Was jedes davon ist, was Amazon verlangt und wie eine Familie veröffentlicht wird, steht unter Neue Angebote auf Amazon.
| Route | Berechtigung | Was sie tut |
|---|---|---|
GET /v1/amazon-catalog/search | catalog:read | Sucht ein Produkt im Amazon-Katalog über ASIN, EAN, UPC oder GTIN, mit seinen Einschränkungen für dein Konto |
GET /v1/amazon-product-types/search | catalog:read | Empfiehlt Produkttypen ausgehend vom Namen eines neuen Produkts |
GET /v1/amazon-shipping-templates | catalog:read | Die Versandvorlagen deines Seller-Kontos, für ein Angebot, das du selbst versendest |
POST /v1/listing-drafts/validate | catalog:read | Validiert das neue Angebot mit den Amazon-Regeln und mit einer Amazon-Vorschau, ohne etwas zu speichern |
POST /v1/listing-drafts | catalog:write | Speichert das neue Angebot als zur Veröffentlichung ausstehend |
GET /v1/listing-drafts | catalog:read | Deine neuen Angebote und ihr Stand, mit dem, was Amazon geantwortet hat |
DELETE /v1/listing-drafts/{id} | catalog:write | Verwirft ein ausstehendes neues Angebot |
GET /v1/pending-listing-changes | catalog:read | Was zur Veröffentlichung aussteht, wie unter Änderungen veröffentlichen |
POST /v1/pending-listing-changes/publish | catalog:write und catalog:publish | Veröffentlicht die gewählten Änderungen und neuen Angebote auf Amazon, auf demselben Weg wie die Schaltfläche Veröffentlichen der App |
Vier Dinge, die du vor dem ersten Aufruf wissen solltest:
- Speichern ist nicht Veröffentlichen. Das neue Angebot bleibt ausstehend, bis es in der App oder mit
publishveröffentlicht wird, das zusätzlichcatalog:publishverlangt und sich nicht rückgängig machen lässt. - Die SKU muss neu sein auf diesem Marktplatz (bei Vendor unter diesem Vendor-Code): Eine, die es schon gibt, in Epinium oder bei Amazon, antwortet mit
409. - Beim Speichern wird Amazon erneut gefragt, und es antwortet mit
400und dem, was fehlt, wenn Amazon das neue Angebot ablehnen würde: Validiere zuerst. - Berechnet werden Validieren (1 Credit) und Speichern (5). Suchen, Versandvorlagen, Auflisten, Verwerfen und Veröffentlichen werden nicht berechnet. Wie jeder Schreibvorgang verlangen Speichern und Veröffentlichen
Idempotency-Key.
Die Parameter jeder Route stehen in der Katalog-Referenz.
Die Kosten eines Produkts schreiben
Mit der eigenen Berechtigung costs:write -nicht catalog:write, die für Cluster, Prompts und Listings gilt- legt die API den Stückkostenpreis und die Versandkosten eines Produkts an oder aktualisiert sie: dieselbe Aktion, die du auf der Produktseite oder beim Hochladen der CSV-Kostenvorlage ausführst, mit derselben Semantik. Für viele Produkte auf einmal nutze den Import.
| Route | Was sie tut |
|---|---|
POST /v1/products/{id}/costs | Legt den Stückkostenpreis (price) und die Versandkosten (shipping_cost) eines Produkts an oder aktualisiert sie |
Vier Dinge, die du vor dem ersten Aufruf wissen solltest:
- Die Semantik entspricht der des CSV. Ein leeres Feld rührt den Wert nicht an: Schickst du nur
price, bleiben vorhandene Versandkosten unverändert. Eine0setzt sie wirklich auf null -das ist nicht dasselbe, wie das Feld nicht zu senden. Mindestens eines vonpriceodershipping_costist Pflicht. - Ein vergangenes Datum berechnet die Historie neu.
dateist standardmäßig heute; schickst du ein früheres Datum, gilt der neue Kostenwert ab dort, und die GuV der danach bereits abgeschlossenen Zeiträume berechnet sich von selbst neu. Die Antwort sagt inrecalculation, was passiert ist:not_neededbeim heutigen Datum,queued, wenn die Neuberechnung eingereiht wurde, oderfailed, wenn sie nicht eingereiht werden konnte -die Kosten werden trotzdem gespeichert, nur die GuV braucht dann etwas Zeit, bis sie es widerspiegelt. - Nur in den Plänen, die Produktkosten einschließen. In Free und Guru antwortet diese Route mit einem
403, genau wie jede andere Schreibaktion in diesen Plänen. Wie jeder Schreibvorgang verlangt sieIdempotency-Key. - Ein Produkt mit Einkäufen akzeptiert kein
price. Seine Produktkosten werden aus den erfassten Einkäufen berechnet, daher antwortet sie mit409und dem CodeCOST_FROM_PURCHASES. Um nur seinen Versand zu ändern, sendeshipping_costallein, ohneprice: Mit beiden wird alles abgelehnt und der Versand nicht gespeichert. Um seine Produktkosten zu ändern, erfasse oder korrigiere einen Einkauf (Die Einkäufe eines Produkts erfassen).
Die Einkäufe eines Produkts erfassen
Hat ein Produkt Einkäufe, sind seine Produktkosten die Durchschnittskosten seines Bestands: Jeder Einkauf berechnet sie neu, mit den Einheiten, die du hattest, und denen, die du kaufst. Das ist dasselbe wie Einkäufe erfassen in der Detailansicht des Produkts, mit derselben Berechnung. Lesen verlangt catalog:read; Erfassen, Korrigieren und Löschen costs:write. Beides nur in den Plänen, die Produktkosten einschließen.
| Route | Was sie tut |
|---|---|
GET /v1/products/{id}/purchases | Die Einkäufe des Produkts, mit den Durchschnittskosten, die jeder hinterlassen hat |
GET /v1/products/{id}/stock-group | Mit welchen Produkten es den Bestand teilt, oder mit welchen es bei seinem ersten Einkauf zusammengefasst würde |
GET /v1/purchases | Deine Einkäufe, nach Konto und Zeitraum |
GET /v1/purchases/{id} | Ein Einkauf |
POST /v1/products/{id}/purchases | Erfasst einen Einkauf |
PATCH /v1/purchases/{id} | Korrigiert einen Einkauf: Sende nur, was sich ändert |
DELETE /v1/purchases/{id} | Löscht einen Einkauf |
- Geteilter Bestand hat nur einen Kostenwert. Im Paneuropäischen Versand ist dieselbe SKU in den EU-Ländern derselbe Bestand, daher ändert ein Einkauf die Kosten in allen diesen Ländern (UK und Vendor laufen getrennt). Die Gruppe entsteht mit dem ersten Einkauf; haben diese Länder heute unterschiedliche Kosten, verlangt dieser Einkauf
prior_stock_unit_cost, also was der vorhandene Bestand wert war, sonst antwortet er mit400undPRIOR_STOCK_VALUE_REQUIRED. - Der Bestand vor dem Einkauf. Ohne
stock_on_handwird der letzte Amazon-FBA-Bestand der vorangegangenen 7 Tage genommen, plus die seitdem erfassten Einkäufe. Bei FBM ist er Pflicht. - Die Bestellnummer wiederholt sich nicht. Mit
referenceantwortet derselbe Einkauf ein zweites Mal mit409undDUPLICATE_PURCHASE_EXTERNAL_ID, statt doppelt angelegt zu werden. - Korrigieren oder Löschen berechnet neu. Es ändert die Durchschnittskosten dieses Einkaufs und der späteren sowie die GuV der bereits abgeschlossenen Zeiträume, wie ein Kostenwert mit vergangenem Datum. Löschen lässt sich nicht rückgängig machen; war es der letzte Einkauf der Gruppe, gelten wieder die Kosten von vorher.
- Bei mehreren Konten verlangt Lesen eines und Schreiben alle. Teilen Konten den Bestand, die der Schlüssel nicht erreicht, kannst du ihre Einkäufe lesen, aber nicht ändern:
400mitSTOCK_GROUP_OUT_OF_SCOPEbeim Erfassen,404beim Korrigieren oder Löschen. - Jeder Schreibvorgang kostet so viel wie das Schreiben eines Kostenwerts, und wie jeder Schreibvorgang verlangt er
Idempotency-Key.
Die Kosten vieler Produkte importieren
Um die Kosten deines Katalogs zu laden, nutze den Import: Er ist derselbe wie Kosten aus einer Datei importieren in der App, mit derselben Vorlage und denselben Regeln, und er berechnet die GuV nur einmal neu, am Ende. Mit derselben Berechtigung costs:write.
Mach es nicht Produkt für Produkt mit POST /v1/products/{id}/costs: Jeder Kostenwert mit vergangenem Datum berechnet die GuV des ganzen Kontos neu, und solange das läuft, lehnt die API die nächsten mit einem 409 ab.
| Route | Was sie tut |
|---|---|
POST /v1/cost-imports/files | Lädt die Kostendatei hoch und gibt ihre file_id zurück, ohne etwas zu importieren. Sie wird 7 Tage aufbewahrt. GET listet die hochgeladenen auf |
POST /v1/cost-imports/preview | Prüft den Import, ohne etwas zu speichern: welche Zeilen angewendet würden, welche nicht und warum, wie viele ohne Datum sind, wie viele nur bis zu späteren Kosten zählen, die das Produkt schon hat, und was er kosten würde |
POST /v1/cost-imports | Importiert die Kosten der Produkte eines Kontos, aus hochgeladenen Dateien oder aus Zeilen |
GET /v1/cost-imports/{id} | Der Stand des Imports: wie viele Zeilen angewendet wurden, wie viele nichts änderten und wie viele abgelehnt wurden, jeweils mit dem Grund |
Was du wissen solltest:
- Die Zeilen kommen auf zwei Wegen. Mit
file_idsdie Dateien, die du mitPOST /v1/cost-imports/fileshochgeladen hast (.xlsx,.xlsoder.csv, bis zu 8 MB und 200.000 Zeilen pro Import: ein ganzer Katalog passt in eine Datei; eine Excel-Datei mit vielen Spalten passt eventuell nicht, dann die überflüssigen Spalten entfernen oder sie als CSV hochladen). Für Listing-Änderungen hochgeladene Dateien werden hier nicht angenommen. Oder mitheadersundrows, bis zu 5.000 Zeilen, wenn du keine Datei hochgeladen hast. - Die Spalten sind die der Vorlage (
sellerSku,marketplace,date,cogs,cogsCurrency,shippingCostundshippingCostCurrency) und werden wie in der App erkannt, auch mit gängigen Namen wie „sku", „cost" oder „date". Wird eine nicht erkannt, gib mitcolumnsan, aus welcher Kopfzeile jeder Wert kommt. Jede Zeile folgt den Regeln für die Datei der App. - Prüf ihn vorher, kostenlos.
POST /v1/cost-imports/previewnimmt denselben Body und wendet dieselben Regeln Zeile für Zeile an, einschließlich des Abgleichs mit deinem Katalog, speichert aber nichts und verbraucht keine Credits. Er sagt dir, wie viele Zeilen angewendet, übersprungen (leer, oder mit denselben Kosten, die das Produkt an ihrem Datum schon hatte:unchanged) und abgelehnt würden, mit Grund und Beispielen, wie viele ohne Datum wären und wie viele Credits es kosten würde. Erst beim Anwenden kann eine Zeile noch abgelehnt werden, wenn es für ihre Währung an ihrem Datum keinen Wechselkurs gibt. - Eine Zeile ohne Datum gilt ab heute. Haben deine Zeilen kein Datum, übergib in
dateden Tag, ab dem die Kosten gelten: Er gilt für die Zeilen ohne Datum, die mit Datum behalten ihres. - Variantenelternprodukte werden abgelehnt mit
parent_product: Sie werden nicht verkauft, ihre Kosten würden also keinen Verkauf abdecken. Die Kosten gehören zu ihren Varianten. - Er läuft asynchron. Die Antwort ist
202mitstatus: "processing". FragGET /v1/cost-imports/{id}ab, bisfinished,finished_with_errorsodererrorerscheint; das Abfragen kostet nichts. Zeilen mit einer Zelle, die länger ist, als die Vorlage erlaubt, kommen innot_sentzurück und werden nicht importiert. - Er bleibt im Verlauf der App, im Verlauf des Kostenimports dieses Kontos, als hättest du ihn in der App hochgeladen.
- Ein Konto pro Import. Solange die GuV dieses Kontos wegen einer früheren Kostenänderung neu berechnet wird, antwortet sie mit
409, ohne etwas zu importieren: Warte, bis sie fertig ist, und starte ihn erneut. - Jede angewendete Zeile kostet so viel wie das Schreiben der Kosten eines Produkts. Beim Anlegen werden die Zeilen reserviert, die angewendet werden können, und reicht dein Guthaben nicht, antwortet er mit
402, ohne etwas zu importieren. Am Ende werden nur die angewendeten Zeilen berechnet und der Rest wird zurückgegeben: Abgelehnte Zeilen und solche, die nichts änderten, kosten nichts. Nur in den Plänen, die Produktkosten einschließen, und er verlangtIdempotency-Key. - Auch Einkäufe. Mit
kind: "purchases"importiert er Einkäufe mit der Einkaufsvorlage der App (sellerSku,marketplace,date,units,currency,productCost,inboundShippingCost,tariffCost,otherCost,stockOnHand,reference), nur in Seller-Konten. Die Prüfung von Einkäufen kontrolliert nur das Format jeder Zeile (checks: "format") und lehnt falsch formatierte Zeilen schon dabei ab: SKU, Bestandsgruppe und Bestand werden erst beim Anwenden geprüft, daher können dann noch einige Zeilen abgelehnt werden. Jeder angewendete Einkauf kostet so viel, wie ihn einzeln zu erfassen.
Eigene Ausgaben schreiben
Deine eigenen Ausgaben (Personal, Agentur, 3PL, Software…) liest du mit catalog:read und schreibst sie mit derselben Berechtigung costs:write wie die Produktkosten. Es sind dieselben, die du unter Kosten und Ausgaben → Eigene Ausgaben erfasst, und die GuV zieht sie bis zum Nettogewinn ab.
| Route | Was sie tut |
|---|---|
GET /v1/expenses | Deine Ausgaben, filterbar nach basis, status (active, upcoming oder ended) und category |
GET /v1/expenses/{id} | Eine Ausgabe, mit dem Verlauf ihrer Beträge pro Monat |
POST /v1/expenses | Legt eine Ausgabe an |
POST /v1/expenses/batch | Legt bis zu 100 Ausgaben auf einmal an, aus einer Liste oder einer hochgeladenen Tabelle (file_id), oder prüft sie, ohne etwas anzulegen |
POST /v1/expenses/files | Lädt eine Tabelle mit Ausgaben hoch und gibt ihre file_id zurück, ohne etwas anzulegen. Wird 7 Tage aufbewahrt. GET listet die hochgeladenen auf |
PATCH /v1/expenses/{id} | Ändert die Bezeichnung oder die Kategorie oder beendet sie mit valid_to (null öffnet sie wieder). Beim Beenden werden die danach geplanten Betragsänderungen gelöscht, und das Wiederöffnen stellt sie nicht wieder her |
POST /v1/expenses/{id}/amounts | Ändert den Betrag ab einem Monat; die vorherigen behalten ihren |
DELETE /v1/expenses/{id} | Löscht sie aus dem gesamten Verlauf |
GET /v1/expense-categories | Die Standardkategorien und deine eigenen |
POST, PATCH und DELETE /v1/expense-categories | Legt eine eigene Kategorie an, benennt sie um oder löscht sie. Eine Kategorie, die eine Ausgabe nutzt, lässt sich nicht löschen |
basis sagt, wie jede Ausgabe berechnet wird: fixed (ein fester Betrag, mit frequency monthly, quarterly, yearly oder once und bei letzterem spread_months 1, 3, 6 oder 12), per_unit (pro verkaufter Nettoeinheit), pct_net_sales oder pct_ad_spend (in Punkten: 5 sind 5 %). Die drei variablen akzeptieren scope, um nur für einige Verbindungen oder Länder zu gelten.
Fünf Dinge, die du vor dem ersten Aufruf wissen solltest:
- Für mehr als eine Ausgabe der Batch.
POST /v1/expenses/batchlegt bis zu 100 auf einmal an.dry_runist Pflicht: Schick ihn zuerst mittrue, das nichts schreibt und keine Credits verbraucht, und danach mitfalse. Es gilt alles oder nichts: Schlägt eine Ausgabe fehl, wird keine angelegt, undfailure_detailssagt welche und warum.possible_duplicateswarnt vor denen, die einer bestehenden oder einer anderen aus demselben Batch ähneln, ohne sie zu blockieren. Berechnet werden nur die angelegten Ausgaben. - Eine Tabelle mit Ausgaben, als Datei. Lade sie mit
POST /v1/expenses/fileshoch (.xlsx,.xlsoder.csv, bis 8 MB und 1.000 Zeilen) und schick ihrefile_idan den Batch: Sie wird mit denselben Regeln gelesen wie der Import in der App. Heißen ihre Spalten nicht wie in der Vorlage, gib mitcolumnsan, aus welcher jeder Wert kommt, und übergib intypeundcurrencyTyp und Währung der Zeilen ohne sie. Eine Zeile, die sich nicht lesen lässt, kommt infailure_detailsalsrow Nzurück, und dann wird nichts angelegt. - Die GuV zieht sie sofort ab. Ausgaben werden beim Lesen der GuV berechnet: Anlegen, Ändern oder Löschen zeigt sich bei der nächsten Abfrage, auch in bereits vergangenen Monaten.
- Jedes Token berührt die Ausgaben seiner Verbindungen. Ein Token, das nicht alle Verkaufsverbindungen des Kontos erreicht, sieht und ändert nur die Ausgaben seiner eigenen und kann keine kontoweiten Ausgaben anlegen (die festen und die variablen ohne Verbindungen in
scope) und keine Kategorien umbenennen oder löschen: Es antwortet mit403, und im Batch kommt diese Zeile infailure_detailszurück. Eine Ausgabe, die es nicht sehen kann, antwortet mit404. - Nur in den Plänen, die Produktkosten einschließen. In Free und Guru antworten diese Routen mit
403, auch das Hochladen der Datei. Jeder Schreibvorgang außer dem Hochladen der Datei verlangtIdempotency-Key.
Grenzen
- Metriken brauchen einen Zeitraum.
start_dateundend_datesind bei allen Metrik-Ressourcen Pflicht. - Der Zeitraum hat ein Maximum, und es hängt von der Granularität ab. Mit
granularity=dailysind es 93 Tage, mittotaloder 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 nutzenlimitundoffset. In beiden Fällen sagthas_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
429kann „zu viele gleichzeitig“ bedeuten, nicht nur „zu viele pro Minute“; ein503bedeutet, dass der Server momentan ausgelastet ist. Beide bringenRetry-Aftermit 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 ein400, der nennt, wie viele Objekte zurückgekommen wären:limitsenken, einexpandweglassen, 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=1anzufragen 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_bynutzen, 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 mitgroup_by=accountund 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.