Skip to content

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 ​

  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.

BerechtigungGibt Zugriff auf
catalog:readProdukte, 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:readKampagnen, Portfolios, Ad Groups, Targets, Product Ads und Suchbegriffe
workflows:readDeine Workflows, ihre Konfiguration und welche Kampagnen sie erreichen
connections:readDie Verbindungen deines Kontos: Amazon, Shopify und WooCommerce
tasks:readEpinium-Aufgaben und ihre Items
skills:readDer Katalog validierter Marketing-Playbooks von Epinium
platform:readWas 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:writeKeyword-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:writeDen 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:writeKampagnen, Portfolios, Ad Groups, Targets und Product Ads bei Amazon anlegen und ändern, und konfigurieren, was der Optimierer für jede verfolgt
platform:writeProdukte 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:writeAufgaben 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:writeWorkflows anlegen, kopieren, bearbeiten, einschalten, pausieren, löschen und wiederherstellen, und sie ausführen oder simulieren
catalog:publishDie 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 ​

EndpointWas er zurückgibt
/v1/productsDeine vereinheitlichten Produkte
/v1/amazon-seller-productsDie Seller-Central-Sicht jedes Produkts, und die Kategorie seines Rankings mit expand=salesRanks
/v1/amazon-vendor-productsDie Vendor-Central-Sicht, die Kategorie des Rankings mit expand=salesRanks und die Bewertungen mit expand=customerFeedback
/v1/amazon-advertising-productsDie Advertising-Sicht
/v1/seller-product-metricsUmsatz, Sessions, Buy Box, Rank, Amazon-Gebühren, Marge, Retouren, Bestand, B2B und Reichweite in Tagen pro Produkt
/v1/vendor-product-metricsVendor-Umsatz pro Produkt, mit Manufacturing und Sourcing, Retouren, Sell-in mit Amazon, Inventar und Reichweite in Tagen
/v1/product-brandsDeine Marken
/v1/countriesLänder und Marketplaces
/v1/clustersDeine 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/promptsDeine benutzerdefinierten Prompts; mit catalog:write legst du sie auch an und bearbeitest sie
/v1/brand-identitiesDeine 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-filesDie 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-updatesDie Ä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-draftsDeine 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-imagesMit 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-changesWas auf Amazon zur Veröffentlichung aussteht, Änderungen und neue Angebote; mit catalog:write und catalog:publish es veröffentlichen
/v1/publicationsJede Veröffentlichung auf Amazon und wie sie pro Land läuft, wie der Bereich Veröffentlichungen der App

Advertising — campaigns:read ​

EndpointWas er zurückgibt
/v1/campaignsDeine Amazon-Advertising-Kampagnen
/v1/campaigns/budget-usageWie viel jede Kampagne heute von ihrem Tagesbudget ausgegeben hat, laut Amazon und höchstens eine halbe Stunde verzögert
/v1/campaign-metricsAusgaben, Umsatz, ACOS und ROAS pro Kampagne
/v1/portfoliosDeine Portfolios und das Budgetlimit, das jedes seinen Kampagnen setzt
/v1/portfolios/budget-usageWie 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/adgroupsDie Ad Groups jeder Kampagne
/v1/adgroup-metricsPerformance pro Ad Group
/v1/targetsKeywords und Produkt-Targets
/v1/target-metricsPerformance pro Target, mit Keyword und Match-Typ
/v1/product-adsDie Verbindung zwischen Ad Group und beworbenem Produkt
/v1/product-ad-metricsPerformance pro beworbenem Produkt, mit seiner ASIN
/v1/search-termsDie tatsächlichen Suchanfragen der Käufer
/v1/search-term-metricsPerformance pro Suchanfrage, mit Text und passendem Target
/v1/campaigns/{id}/optimization-historyWas die Automatisierung an einer Kampagne geändert hat, mit dem Nettoeffekt
/v1/advertising-changesAlles, was Epinium bei Amazon geändert hat, unabhängig von der Quelle

Automatisierung — workflows:read ​

EndpointWas er zurückgibt
/v1/workflowsDeine 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}/campaignsWelche Kampagnen er wirklich erreicht, und warum jede dabei ist
/v1/workflows/{id}/performanceDie 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 ​

EndpointBerechtigungWas er zurückgibt
/v1/connectionsconnections:readDeine Verbindungen: Amazon, Shopify und WooCommerce
POST /v1/platform-requestplatform:read, und platform:write zum SchreibenEine Abfrage an einen deiner Shops oder, mit platform:write, eine Änderung daran: GraphQL bei Shopify, REST bei WooCommerce
/v1/platform-request/docs/{platform}platform:readDie API-Version dieser Plattform, ihre Referenz und die Felder, die dein Shop gerade hat
/v1/taskstasks:readEpinium-Aufgaben
/v1/task-itemstasks:readDie Items jeder Aufgabe
/v1/skillsskills:readDer 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.

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.

EndpointWas er zurückgibt
/v1/pnl/cascadeDie 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/productsEine 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/clustersEine Zeile pro Cluster, mit Deckungsbeitrag, Kostenabdeckung und Anzahl der Produkte
/v1/pnl/channelsEine Zeile pro Vertriebskanal (Seller, Vendor…), mit seiner nach Plattform aufgeschlüsselten Werbung
/v1/pnl/ads-matrixDie kanalübergreifenden Werbeausgaben: auf welchem Vertriebskanal jede Plattform wirbt
/v1/pnl/freshnessDas Datum der letzten Daten jeder Quelle -Amazon, Werbung und Produktkosten-, um zu wissen, ob das Gelesene schon vollständig ist
/v1/pnl/margin-leaksDie 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-mediansDas Ü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/inventoryDas 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 currency an 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 Abschnitt variable_expenses abgezogen, vor dem Deckungsbeitrag, und own_expenses.periods[].variable schlüsselt sie nach Kategorie auf. Die festen (fixed) werden danach abgezogen, bis net_profit. Da sie für das ganze Konto gelten, kommen fixed und net_profit mit connection, country oder cluster, oder mit einem Token, das nicht alle Verkaufsverbindungen erreicht, als null zurück, und fixed_unavailable sagt warum: filtered oder partial_access. Hat das Konto keine festen Ausgaben, fehlt nichts, und net_profit kommt auch mit Filter oder mit einem Token zurück, das nicht alle Verbindungen erreicht. In der Tabelle pro Produkt ist die Spalte own_expenses der Anteil der variablen Ausgaben jedes Produkts.
  • coverage sagt, welcher Teil des Umsatzes einen echten Kostenwert hat. Ein Produkt ohne hinterlegte Kosten wird nicht still verworfen oder auf null gesetzt: coverage.covered_sales im Verhältnis zu coverage.total_sales sagt dir, welcher Anteil der Zahl verlässlich ist. In coverage ist estimated_sales der Teil von covered_sales mit 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 als null zurü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.
  • cluster grenzt /v1/pnl/cascade, /v1/pnl/products, /v1/pnl/clusters, /v1/pnl/freshness, /v1/pnl/margin-leaks, /v1/pnl/category-medians und /v1/pnl/inventory auf 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/clusters zählt ein Produkt, das in zwei Clustern ist, in beiden, und was in keinem Cluster ist, erscheint nicht.
  • /v1/pnl/margin-leaks liefert standardmäßig die Produkte in allen drei Zuständen, wie der Bildschirm; mit status behältst du die, die du wählst. Im selben Aufruf gibt summary an, 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ägt main_cause, die Kostenart mit dem größten Margenverlust, berechnet wie auf dem Bildschirm. Hat der Vorzeitraum keine Umsätze, ist has_previous_sales false: Die leere Liste heißt dann, dass es nichts zu vergleichen gibt, nicht, dass es keine Verluste gibt.
  • /v1/pnl/inventory ist der heutige Bestand, ohne Zeitraum: eine Zeile pro Bestand, und in der EU erscheint eine paneuropäische SKU nur einmal, mit allen ihren countries, also addiere keine Zeilen über Länder hinweg. summary liefert das gebundene Kapital des gesamten Umfangs und seine Aufteilung nach Rotation, ohne Paginierung und unabhängig von rotation und search. currency ist 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 Feld cost enthält cogs und shipping, jeweils mit dem Stückbetrag, seiner Währung, valid_from und source, oder null, wenn es keine hat. Mit cost_state behältst du die aktiven Produkte with (mit Kosten), missing (ohne Kosten) oder missing_with_sales (ohne Kosten und mit Verkäufen in den letzten 30 Tagen, die die Marge am stärksten aufblähen), und mit include_total erfährst du, wie viele es sind. Es ist dasselbe, was du unter Kosten und Ausgaben siehst. In Free und Guru ist cost null und cost_state antwortet mit 403.

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.
RouteWas sie tut
POST /v1/campaignsEine Kampagne anlegen
POST /v1/campaigns/fullKampagne + Ad Group + Targets + Product Ads in einem Aufruf
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batchStatus, Tagesbudget, Name und Portfolio (das Portfolio nur bei Sponsored Products)
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batchAnlegen; Status, Standardgebot und Name
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batchTargets 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/batchProdukte 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/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 ProductAkzeptierte targetType
Sponsored ProductsKEYWORD, PRODUCT, PRODUCT_CATEGORY
Sponsored BrandsDie von Sponsored Products plus THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND oder KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES)
Sponsored DisplayKEYWORD; 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.

RouteWas sie tut
PATCH /v1/campaigns/{id}/optimization-configDie Optimierungskonfiguration einer Kampagne ändern
POST /v1/campaigns/optimization-config/batchDieselbe 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.
RouteWas sie tut
POST /v1/tasksEine Aufgabe anlegen, mit ihren Vorschlägen
PATCH /v1/tasks/{id}Titel, Beschreibung, Priorität und Ablaufdatum
POST /v1/tasks/{id}/resolveSie erledigen oder verwerfen
PATCH /v1/task-items/{id} · POST /v1/task-items/batchVorschläge annehmen oder ablehnen, optional mit deinem eigenen Wert in appliedValue
POST /v1/tasks/{id}/applyDas Angenommene anwenden
POST /v1/tasks/listing-optimizationsDie 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 202 mit 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 nach task.
  • 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 mit POST /v1/pending-listing-changes/publish, das catalog:publish verlangt.
  • 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, dessen code listing_optimization_limit_reached ist, 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. products sind Ids von Katalogprodukten, Seller oder Vendor (/v1/products; Werbeprodukte gelten nicht). fields akzeptiert title, bullets, description und search_terms; ohne es werden alle vier umgeschrieben. title schreibt 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} nimmt addPositiveKeywords, removePositiveKeywords, addNegativeKeywords, removeNegativeKeywords, addProducts, removeProducts, addPrompts, removePrompts 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.
RouteWas sie tut
POST /v1/clustersEinen 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 (addPrompts in PATCH /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.
  • fields legt fest, für welche Felder des Listings er gilt: titleAndHighlights (Titel und Artikel-Highlights, die zusammen verfasst werden), product_description, bullet_point oder generic_keyword (die Suchbegriffe). Ohne fields oder mit [] gilt er für alle. Ein älterer Prompt kann noch item_name tragen, 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} nimmt name, instruction und fields, und fields ersetzt die ganze Liste.
RouteWas sie tut
POST /v1/promptsEinen 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:

FeldWas es ist
nameName der Marke oder des Verkäufers. Pflichtfeld
urlSeine Website oder sein Amazon-Shop
asinsDie ASINs seiner Produkte, die mit deinen konkurrieren, bis zu 20
threatWie 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_positionSein 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, aber competitors, competitor_urls, brand_urls und product_brand_ids werden ganz ersetzt: Um einen Wettbewerber hinzuzufügen, sende die bisherigen plus den neuen. Die vorherigen Werte werden nirgends aufbewahrt.
  • Die Profile ersetzen competitor_urls nicht. 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 leeres competitors.
  • 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.
RouteWas sie tut
POST /v1/brand-identitiesEine 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.

RouteBerechtigungWas sie tut
POST /v1/listing-filescatalog:readLädt die Datei hoch (.xlsx, .xls oder .csv) und gibt ihre file_id zurück. Sie wird 7 Tage aufbewahrt
POST /v1/listing-files/rowscatalog:writeSpeichert Kopfzeilen und Zeilen, die du schon hast, als Datei, ohne etwas hochzuladen
POST /v1/listing-updates/preparecatalog:readFindet die Produkte der Datei über SKU, ASIN oder EAN und sagt, welche Attribute sie zulassen
POST /v1/listing-updates/validatecatalog:readValidiert die Zeilen gegen die Amazon-Regeln jedes Produkttyps, ohne etwas zu speichern
POST /v1/listing-updates/applycatalog:writeSpeichert die gültigen Zeilen im Hintergrund als zur Veröffentlichung ausstehende Änderungen
GET /v1/listing-updates/apply/{file_id}catalog:readDer 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. apply lässt die Änderungen zur Veröffentlichung ausstehend, und sie gehen an Amazon, wenn jemand sie in Epinium über Änderungen veröffentlichen oder mit POST /v1/pending-listing-changes/publish verö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_id in confirmed_cascades mitkommt; 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_start oder sale_end); clear: true bewirkt, dass ihre leeren Zellen löschen, und date_order (dmy oder mdy) legt die Reihenfolge mehrdeutiger Daten fest. validate liefert in offer_clears die Preisspalten mit leeren Zellen bei Produkten, die diesen Wert haben, und die Preisregeln als blockierende offer_*-Probleme. Bei Vendor wird kein Preis bearbeitet: Diese Spalten kommen in not_applicable mit dem Grund vendor_price zurück. prepare bietet die Preisfelder in offer_fields an.
  • 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 er Idempotency-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.

RouteBerechtigungWas sie tut
GET /v1/amazon-catalog/searchcatalog:readSucht ein Produkt im Amazon-Katalog über ASIN, EAN, UPC oder GTIN, mit seinen Einschränkungen für dein Konto
GET /v1/amazon-product-types/searchcatalog:readEmpfiehlt Produkttypen ausgehend vom Namen eines neuen Produkts
GET /v1/amazon-shipping-templatescatalog:readDie Versandvorlagen deines Seller-Kontos, für ein Angebot, das du selbst versendest
POST /v1/listing-drafts/validatecatalog:readValidiert das neue Angebot mit den Amazon-Regeln und mit einer Amazon-Vorschau, ohne etwas zu speichern
POST /v1/listing-draftscatalog:writeSpeichert das neue Angebot als zur Veröffentlichung ausstehend
GET /v1/listing-draftscatalog:readDeine neuen Angebote und ihr Stand, mit dem, was Amazon geantwortet hat
DELETE /v1/listing-drafts/{id}catalog:writeVerwirft ein ausstehendes neues Angebot
GET /v1/pending-listing-changescatalog:readWas zur Veröffentlichung aussteht, wie unter Änderungen veröffentlichen
POST /v1/pending-listing-changes/publishcatalog:write und catalog:publishVerö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 publish veröffentlicht wird, das zusätzlich catalog:publish verlangt 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 400 und 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.

RouteWas sie tut
POST /v1/products/{id}/costsLegt 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. Eine 0 setzt sie wirklich auf null -das ist nicht dasselbe, wie das Feld nicht zu senden. Mindestens eines von price oder shipping_cost ist Pflicht.
  • Ein vergangenes Datum berechnet die Historie neu. date ist 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 in recalculation, was passiert ist: not_needed beim heutigen Datum, queued, wenn die Neuberechnung eingereiht wurde, oder failed, 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 sie Idempotency-Key.
  • Ein Produkt mit Einkäufen akzeptiert kein price. Seine Produktkosten werden aus den erfassten Einkäufen berechnet, daher antwortet sie mit 409 und dem Code COST_FROM_PURCHASES. Um nur seinen Versand zu ändern, sende shipping_cost allein, ohne price: 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.

RouteWas sie tut
GET /v1/products/{id}/purchasesDie Einkäufe des Produkts, mit den Durchschnittskosten, die jeder hinterlassen hat
GET /v1/products/{id}/stock-groupMit welchen Produkten es den Bestand teilt, oder mit welchen es bei seinem ersten Einkauf zusammengefasst würde
GET /v1/purchasesDeine Einkäufe, nach Konto und Zeitraum
GET /v1/purchases/{id}Ein Einkauf
POST /v1/products/{id}/purchasesErfasst 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 mit 400 und PRIOR_STOCK_VALUE_REQUIRED.
  • Der Bestand vor dem Einkauf. Ohne stock_on_hand wird 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 reference antwortet derselbe Einkauf ein zweites Mal mit 409 und DUPLICATE_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: 400 mit STOCK_GROUP_OUT_OF_SCOPE beim Erfassen, 404 beim 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.

RouteWas sie tut
POST /v1/cost-imports/filesLä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/previewPrü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-importsImportiert 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_ids die Dateien, die du mit POST /v1/cost-imports/files hochgeladen hast (.xlsx, .xls oder .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 mit headers und rows, bis zu 5.000 Zeilen, wenn du keine Datei hochgeladen hast.
  • Die Spalten sind die der Vorlage (sellerSku, marketplace, date, cogs, cogsCurrency, shippingCost und shippingCostCurrency) und werden wie in der App erkannt, auch mit gängigen Namen wie „sku", „cost" oder „date". Wird eine nicht erkannt, gib mit columns an, 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/preview nimmt 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 date den 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 202 mit status: "processing". Frag GET /v1/cost-imports/{id} ab, bis finished, finished_with_errors oder error erscheint; das Abfragen kostet nichts. Zeilen mit einer Zelle, die länger ist, als die Vorlage erlaubt, kommen in not_sent zurü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 verlangt Idempotency-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.

RouteWas sie tut
GET /v1/expensesDeine 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/expensesLegt eine Ausgabe an
POST /v1/expenses/batchLegt 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/filesLä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-categoriesDie Standardkategorien und deine eigenen
POST, PATCH und DELETE /v1/expense-categoriesLegt 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/batch legt bis zu 100 auf einmal an. dry_run ist Pflicht: Schick ihn zuerst mit true, das nichts schreibt und keine Credits verbraucht, und danach mit false. Es gilt alles oder nichts: Schlägt eine Ausgabe fehl, wird keine angelegt, und failure_details sagt welche und warum. possible_duplicates warnt 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/files hoch (.xlsx, .xls oder .csv, bis 8 MB und 1.000 Zeilen) und schick ihre file_id an den Batch: Sie wird mit denselben Regeln gelesen wie der Import in der App. Heißen ihre Spalten nicht wie in der Vorlage, gib mit columns an, aus welcher jeder Wert kommt, und übergib in type und currency Typ und Währung der Zeilen ohne sie. Eine Zeile, die sich nicht lesen lässt, kommt in failure_details als row N zurü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 mit 403, und im Batch kommt diese Zeile in failure_details zurück. Eine Ausgabe, die es nicht sehen kann, antwortet mit 404.
  • 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 verlangt Idempotency-Key.

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:

HeaderWas es ist
X-Epinium-Credits-CostWas dieser Aufruf gekostet hat
X-Epinium-Credits-RemainingWas dir bleibt. Der Wert ist ungefähr: wenn gleichzeitig anderes verbraucht, kann er abweichen
X-Epinium-Credits-BreakdownDie Aufschlüsselung, pro Ressource und Einzelpreis: product=100x1,country=100x0
X-Epinium-Credits-MaxDas 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:

json
{
  "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.

Epinium Documentation