API di Epinium
Accesso: Impostazioni → API Keys
Epinium espone i tuoi dati tramite un'API REST così puoi leggerli dai tuoi strumenti: una dashboard tua, uno script di analisi o un assistente IA. Sono le stesse informazioni che vedi nell'app, con gli stessi numeri.
L'API legge i tuoi dati e scrive su Amazon e nei tuoi negozi: consulta catalogo, campagne e metriche, il tuo P&L con costo prodotto, e ciò che c'è dentro i tuoi negozi Shopify e WooCommerce; crea e modifica campagne Sponsored Products e modifica quelle Sponsored Brands e Display; crea e modifica portafogli; crea, modifica, clona ed esegue workflow; crea, risolve e applica attività; crea o aggiorna il costo dei tuoi prodotti e registra i loro acquisti dai fornitori; salva modifiche a qualsiasi attributo dei tuoi listing Amazon e crea nuove offerte, prodotti nuovi e famiglie di varianti; e crea, modifica ed elimina prodotti e contenuti nei tuoi negozi Shopify e WooCommerce collegati. Nel tuo catalogo Amazon, ciò che salvi resta in sospeso e arriva su Amazon solo quando viene pubblicato, dall'app o dall'API con il suo permesso; quello dei tuoi negozi cambia direttamente, senza restare in sospeso. Ogni area ha il suo permesso, e quelli di scrittura li concedi tu quando crei la chiave.
Vuoi usarla da un assistente IA?
Non serve programmare nulla. L'MCP di Epinium collega questi stessi dati a Claude e ad altri assistenti compatibili.
Generare un token
- Vai su Impostazioni → API Keys
- Clicca su Crea API key e dalle un nome che ti ricordi a cosa serve
- Seleziona i permessi necessari
- Copia la chiave e conservala in un posto sicuro
- Usala nell'header
Authorizationdi ogni richiesta
La chiave si mostra una sola volta
Il valore completo appare una volta sola alla creazione. Se la perdi non è recuperabile: bisogna revocarla e crearne un'altra.
Permessi
Ogni token porta i permessi che selezioni alla creazione. Concedi solo quelli che serve all'integrazione.
| Permesso | Dà accesso a |
|---|---|
catalog:read | Prodotti, brand, paesi, cluster, prompt personalizzati e identità di marca, con le relative metriche: vendite, commissioni Amazon e margine, resi, stock e, per Vendor, recensioni; e il tuo P&L, con il costo prodotto e le tue spese proprie se il tuo piano lo include |
campaigns:read | Campagne, portafogli, ad group, target, product ads e termini di ricerca |
workflows:read | I tuoi workflow, la loro configurazione e quali campagne raggiungono |
connections:read | Le connessioni del tuo account: Amazon, Shopify e WooCommerce |
tasks:read | Task di Epinium e i loro item |
skills:read | Il catalogo di playbook di marketing validati di Epinium |
platform:read | Ciò che c'è dentro i tuoi negozi Shopify e WooCommerce: prodotti, scorte, prezzi e il resto di ciò che espone ogni negozio, letto in diretta dalla sua API. Include il registro delle modifiche fatte in essi (/v1/platform-changes, 1 credito per riga restituita) |
catalog:write | Creare, modificare ed eliminare cluster di keyword: il nome, le keyword positive e negative, i prodotti che raggruppano e i prompt che usano. Creare e modificare prompt personalizzati. Creare e modificare la tua identità di marca, con una scheda per concorrente. Salvare modifiche agli attributi dei tuoi listing Amazon da un file, come modifiche in attesa di pubblicazione. Salvare e scartare nuove offerte su Amazon (offerte su prodotti che esistono già, prodotti nuovi e famiglie) e caricare immagini di prodotto. Niente arriva su Amazon finché non lo pubblichi |
costs:write | Creare o aggiornare il costo unitario e il costo di spedizione dei tuoi prodotti, e registrare, correggere ed eliminare i loro acquisti, uno alla volta o importandoli da un file; e creare, modificare ed eliminare le tue spese proprie e le loro categorie |
campaigns:write | Creare e modificare campagne, portafogli, ad group, target e product ad su Amazon, e configurare cosa persegue l'ottimizzatore su ciascuna |
platform:write | Creare, modificare ed eliminare prodotti e contenuti nei tuoi negozi Shopify e WooCommerce collegati, direttamente e senza revisione preventiva, per la stessa route con cui si consultano (POST /v1/platform-request): una mutation in Shopify, o un metodo diverso da GET in WooCommerce, con l'intestazione Idempotency-Key. Serve anche platform:read (il livello Modificare della schermata API Keys concede entrambi). Ogni modifica viene registrata per 12 mesi e costa quanto una consultazione: 5 crediti per chiamata più 1 per KB restituito |
tasks:write | Creare task, approvare o rifiutare i loro suggerimenti, chiuderli e applicare ciò che è stato approvato. Chiedere all'IA di Epinium di riscrivere schede come suggerimenti di un task |
workflows:write | Creare, copiare, modificare, attivare, mettere in pausa, eliminare e ripristinare workflow, e lanciarli o simularli |
catalog:publish | Pubblicare su Amazon le modifiche ai listing e le nuove offerte in sospeso che scegli (POST /v1/pending-listing-changes/publish), per la stessa strada del pulsante Pubblicare dell'app. Non si può annullare. Serve anche catalog:write |
Scrivere è dei piani Business e Master. In Free e Guru i token leggono: non si può creare una chiave né autorizzare un assistente con permessi di scrittura, e se passi a uno di questi piani, quelli che avevi già continuano a leggere ma le loro scritture vengono rifiutate con un 403.
Un token raggiunge tutte le connessioni del tuo account. Se sei un'agenzia, raggiunge le connessioni che ogni cliente ti ha condiviso accettando il tuo invito.
Se sei un'agenzia: scegli l'account a ogni chiamata
Un token di agenzia raggiunge più account, quindi ogni richiesta deve dire su quale opera. Con l'header Epinium-Account: <id dell'account>, oppure con il parametro account_id se chiami dal MCP.
/v1/me e /v1/accounts sono l'eccezione: rispondono senza scegliere un account, e sono proprio quelli che ti dicono quali account raggiungi e come si chiamano.
Scelto l'account, lo vedi per intero: i suoi prodotti e le sue campagne sono limitati alle connessioni che ti ha condiviso, e le sue risorse di account — workflow, task e cluster, che non dipendono da nessuna connessione — sono limitate all'account. Quello che è fuori dalla tua portata non viene filtrato in silenzio: un account_id a cui non sei stato invitato restituisce un errore esplicito, non una lista vuota.
Quali endpoint copre
Ogni risorsa ha un elenco, e la maggior parte permette anche di recuperare un elemento tramite il suo id. Le risorse di metriche hanno solo l'elenco: una riga aggregata su un intervallo di date non ha un identificatore proprio.
Catalogo — catalog:read
| Endpoint | Cosa restituisce |
|---|---|
/v1/products | I tuoi prodotti unificati |
/v1/amazon-seller-products | La vista Seller Central di ogni prodotto, e la categoria del suo ranking con expand=salesRanks |
/v1/amazon-vendor-products | La vista Vendor Central, la categoria del ranking con expand=salesRanks e le recensioni con expand=customerFeedback |
/v1/amazon-advertising-products | La vista Advertising |
/v1/seller-product-metrics | Vendite, sessioni, Buy Box, rank, commissioni Amazon, margine, resi, stock, B2B e giorni di copertura per prodotto |
/v1/vendor-product-metrics | Vendite Vendor per prodotto, con manufacturing e sourcing, resi, sell-in con Amazon, inventario e giorni di copertura |
/v1/product-brands | I tuoi brand |
/v1/countries | Paesi e marketplace |
/v1/clusters | I tuoi cluster di keyword; con catalog:write li crei e li modifichi anche |
/v1/pnl/* | Il tuo P&L: cascata, tabella per prodotto, per cluster, per canale di vendita, pubblicità incrociata, freschezza, perdite di margine e inventario - spiegato in Il P&L con costo prodotto |
/v1/prompts | I tuoi prompt personalizzati; con catalog:write li crei e li modifichi anche |
/v1/brand-identities | La tua identità di marca, con una scheda per concorrente; con catalog:write la crei e la modifichi anche - spiegato in Scrivere la tua identità di marca |
/v1/listing-files | I file di modifiche ai listing che hai caricato negli ultimi 7 giorni; caricarne uno richiede catalog:read, e salvare come file delle righe scritte a mano, catalog:write |
/v1/listing-updates | Preparare e convalidare le modifiche di un file senza salvare nulla; con catalog:write, salvarle in attesa di pubblicazione - spiegato in Modificare i listing da un file |
/v1/listing-drafts | Le tue nuove offerte su Amazon e il loro stato; con catalog:write, salvarle e scartarle. Per cercare il prodotto e convalidarle, /v1/amazon-catalog/search, /v1/amazon-product-types/search, /v1/amazon-shipping-templates e /v1/listing-drafts/validate - spiegato in Creare nuove offerte su Amazon |
/v1/listing-images | Con catalog:write, caricare un'immagine di prodotto per un listing o una nuova offerta: JPG, PNG, GIF o TIFF, fino a 8 MB, conservata 30 giorni |
/v1/pending-listing-changes | Ciò che è in attesa di pubblicazione su Amazon, modifiche e nuove offerte; con catalog:write e catalog:publish, pubblicarlo |
/v1/publications | Ogni pubblicazione su Amazon e come va per paese, come il pannello Pubblicazioni dell'app |
Advertising — campaigns:read
| Endpoint | Cosa restituisce |
|---|---|
/v1/campaigns | Le tue campagne Amazon Advertising |
/v1/campaigns/budget-usage | Quanto ha speso oggi ogni campagna del suo budget giornaliero, secondo Amazon, con al massimo mezz'ora di ritardo |
/v1/campaign-metrics | Spesa, vendite, ACOS e ROAS per campagna |
/v1/portfolios | I tuoi portafogli e il tetto di budget che ciascuno impone alle sue campagne |
/v1/portfolios/budget-usage | Quanto ha speso ogni portafoglio del suo tetto nel periodo, a che ritmo va e quanto può spendere al giorno per chiudere esattamente sul tetto |
/v1/adgroups | Gli ad group di ogni campagna |
/v1/adgroup-metrics | Performance per ad group |
/v1/targets | Keyword e target di prodotto |
/v1/target-metrics | Performance per target, con la sua keyword e il tipo di corrispondenza |
/v1/product-ads | Il collegamento tra un ad group e il prodotto che pubblicizza |
/v1/product-ad-metrics | Performance per prodotto pubblicizzato, con il suo ASIN |
/v1/search-terms | Le ricerche reali degli acquirenti |
/v1/search-term-metrics | Performance per ricerca, con il testo e il target che l'ha intercettata |
/v1/campaigns/{id}/optimization-history | Cosa ha cambiato l'automazione su una campagna, con l'effetto netto |
/v1/advertising-changes | Tutto ciò che Epinium ha modificato su Amazon, da qualunque origine |
Automazione — workflows:read
| Endpoint | Cosa restituisce |
|---|---|
/v1/workflows | I tuoi workflow, con la loro pianificazione e se sono attivi |
/v1/workflows/{id} | La configurazione completa di uno: il suo diagramma e ogni variabile con il valore effettivo |
/v1/workflows/{id}/campaigns | Quali campagne raggiunge davvero, e perché ognuna ci rientra |
/v1/workflows/{id}/performance | La performance di quelle campagne, con il loro obiettivo accanto per poterla giudicare |
Un workflow può essere pianificato ogni notte e non toccare nessuna campagna: /campaigns è ciò che lo rivela, e quando l'insieme torna vuoto ne dice il motivo.
Connessioni, task e skills
| Endpoint | Permesso | Cosa restituisce |
|---|---|---|
/v1/connections | connections:read | Le tue connessioni: Amazon, Shopify e WooCommerce |
POST /v1/platform-request | platform:read, e platform:write per scrivere | Una query a uno dei tuoi negozi o, con platform:write, una modifica: GraphQL su Shopify, REST su WooCommerce |
/v1/platform-request/docs/{platform} | platform:read | La versione dell'API di quella piattaforma, la sua documentazione di riferimento e i campi che ha il tuo negozio in questo momento |
/v1/tasks | tasks:read | Task di Epinium |
/v1/task-items | tasks:read | Gli item di ogni task |
/v1/skills | skills:read | Il catalogo di playbook di marketing di Epinium |
Il catalogo di skills è contenuto scritto da Epinium, non dati del tuo account: è lo stesso per tutti i clienti. Quali parti di ogni playbook ricevi dipende dal tuo piano.
Le query ai tuoi negozi non restituiscono dati personali: nomi, email, telefoni e indirizzi vengono rifiutati prima che la richiesta arrivi al negozio. Si pagano in base alla dimensione della risposta, come le modifiche. Queste due rotte non sono nel riferimento navigabile: di solito si usano dall'MCP di Epinium.
Esiste anche /v1/me, che indica quali permessi e quali account raggiunge il tuo token. È la prima chiamata utile per verificare che la chiave funzioni.
Tre regole per leggere i dati
Queste tre spiegano quasi tutti i dubbi di interpretazione:
- Gli importi sono testo, non numeri.
"cost": "8.22"arriva come stringa di proposito, per non perdere precisione nella conversione a decimale binario. - I rapporti sono in frazione, non in percentuale. Un ACOS del 90,83 % arriva come
0.908287. Moltiplica per 100 per mostrarlo. nullnon è0.nullsignifica che Amazon non ha riportato quel dato;0significa uno zero reale. Unacosanullè una campagna che ha speso senza vendere, non pubblicità gratis. Enew_to_brand_salesarriva anullsu Sponsored Products perché Amazon non lo misura per quel formato.
Redditività, stock e recensioni dei tuoi prodotti
Le metriche di prodotto non si fermano alle vendite: dicono anche quanto trattiene Amazon, quanto stock resta e cosa pensano gli acquirenti. Quattro cose prima di trarre conclusioni:
- Le commissioni e il margine Seller sono al netto dell'IVA, mentre
salesla include dove si applica: non sottrarre le une dall'altro.margin_before_adsè ciò che resta dopo aver pagato Amazon, prima della pubblicità e del costo del prodotto: per il margine dopo la pubblicità, sottraigli la spesa di/v1/product-ad-metrics. Amazon imputa lo stoccaggio a un solo giorno del mese e i resi alla data del rimborso, quindi il margine si legge per mese, non per giorno. days_of_coveragesono i giorni che dura lo stock al ritmo del periodo: lo stock dell'ultimo giorno diviso per le unità medie giornaliere dell'intervallo richiesto. Ènullcon qualsiasi granularità diversa datotal, se il prodotto non ha venduto nulla o, quando si raggruppa, segroup_bynon include il paese. Conorder_by=days_of_coverage&order=ascottieni prima quelli che stanno per esaurirsi.- In Vendor c'è anche il sell-in: le unità che hai confermato ad Amazon, quelle degli ordini di acquisto aperti, il fill rate e i tempi di consegna, oltre ai resi separati tra manufacturing e sourcing e alla salute dell'inventario.
- La categoria del ranking e le recensioni si chiedono al prodotto, non alle metriche.
expand=salesRanksindica a quale categoria appartiene ogni posizione del Best Seller Rank, e in Vendorexpand=customerFeedbackrestituisce i temi positivi e negativi delle recensioni e i motivi di reso della categoria. È la fotografia della settimana, con la tendenza di sei mesi calcolata da Amazon, non uno storico.
Totali dell'account, per periodo e per cluster
Per sapere quanto ha venduto l'account a settembre non serve paginare il catalogo e sommare: le sette risorse di metriche aggregano da sole.
group_bysomma tra entità.accountdà il totale dell'account;countryeconnectionsuddividono per paese o per connessione, e si combinano ripetendo il parametro (group_by[]=connection&group_by[]=country).accountnon si combina con nient'altro. Le righe restano separate per valuta — gli importi non vengono mai convertiti — e, nella pubblicità, per tipo di annuncio (SP,SB,SD).granularitydivide l'intervallo in periodi di calendario. Oltre atotaledailyaccettaweekly,monthly,quarterlyeyearly, e ogni riga porta indatel'inizio del suo periodo: il lunedì della settimana o il primo giorno del mese, del trimestre o dell'anno. I periodi agli estremi sono parziali: dal 15 gennaio al 10 marzo conmonthlyrestituisce gennaio dal 15 al 31, febbraio intero e marzo dall'1 al 10.clusterrestringe a una famiglia di prodotti. Nelle metriche Seller, Vendor e di prodotto pubblicizzato,cluster=<id>lascia solo i prodotti di quel cluster; con più id, l'unione. Si combina con quanto sopra:group_by=account&granularity=monthly&cluster=<id>è la serie mensile di quella famiglia.group_by=clusterdà una riga per cluster. Nelle stesse tre metriche,group_by=clusterrestituisce in una sola chiamata i dati di ciascuno dei tuoi cluster, con il suo id inclustere il suo nome incluster_name. Un prodotto presente in più cluster conta per intero in ognuno, quindi le righe non sommano il totale dell'account, e i prodotti senza cluster non compaiono. Si combina concountryeconnection, e con il filtroclusterper scegliere quali cluster restituire; se i tuoi cluster superano le 2.000 appartenenze prodotto-cluster, l'API ti chiede di restringerli con quel filtro.
Nelle righe raggruppate, i campi che identificano un'entità (product, asin, campaign…) arrivano a null, come ciò che non si può sommare: il rank, il prezzo, il canale e i tassi Vendor. Lo stock Seller si somma solo se raggruppi per paese: con l'inventario paneuropeo di FBA, Amazon riporta lo stesso stock in ogni marketplace, e sommarlo tra paesi conterebbe le stesse unità più volte. Per questo, con group_by=account o connection, stock e days_of_coverage arrivano a null.
Un cluster raggruppa prodotti del catalogo, non ASIN singoli: lo stesso ASIN su un'altra connessione resta fuori a meno che anche il suo prodotto non sia nel cluster. E le righe che Amazon non è riuscito ad associare a un prodotto del catalogo non entrano nel filtro: circa il 5 % delle vendite Vendor e il 3 % della spesa dei prodotti pubblicizzati.
Quanto fa risparmiare in crediti lo trovi in Crediti.
Il P&L con costo prodotto
È lo stesso conto economico che vedi in Redditività → P&L: vendite, commissioni e logistica Amazon, pubblicità e, se il tuo piano lo include, il costo dei tuoi prodotti e le tue spese proprie, con lo stesso calcolo e gli stessi numeri.
Ciò che vedi dipende dal tuo piano. In Free e Guru il P&L arriva fino a margin_before_ads: ciò che resta dopo Amazon, prima della pubblicità e prima del costo prodotto - non chiamarlo "profitto", perché non lo è. In Business e Master arriva fino in fondo: margine di contribuzione, ogni riga di costo prodotto e la sua copertura, e le tue spese proprie fino all'utile netto. includes_product_cost in ogni risposta ti dice quale dei due stai vedendo, così non devi indovinarlo a seconda che i numeri corrispondano a quanto ti aspettavi. Perdite di margine (/v1/pnl/margin-leaks e /v1/pnl/category-medians) è solo per Business e Master: in Free e Guru risponde 403 con code: "plan_feature_not_allowed", e le sue risposte non portano includes_product_cost, perché includono sempre il costo. Lo stesso vale per l'inventario (/v1/pnl/inventory), valorizzato al costo prodotto.
| Endpoint | Cosa restituisce |
|---|---|
/v1/pnl/cascade | La cascata del periodo: vendite, resi, commissioni, logistica, pubblicità, costo prodotto e spese proprie fino all'utile netto, mese per mese o giorno per giorno |
/v1/pnl/products | Una riga per prodotto, con il suo margine di contribuzione e la sua copertura di costo |
/v1/pnl/products/{id} | Il dettaglio di un prodotto: la sua cascata, mese per mese |
/v1/pnl/clusters | Una riga per cluster, con il suo margine di contribuzione, la sua copertura dei costi e quanti prodotti ha |
/v1/pnl/channels | Una riga per canale di vendita (Seller, Vendor…), con la sua pubblicità suddivisa per piattaforma |
/v1/pnl/ads-matrix | La spesa pubblicitaria incrociata: su quale canale di vendita fa pubblicità ogni piattaforma |
/v1/pnl/freshness | La data dell'ultimo dato di ogni fonte -Amazon, pubblicità e costo prodotto- per sapere se ciò che leggi è già completo |
/v1/pnl/margin-leaks | I prodotti che hanno perso margine rispetto al periodo precedente, ordinati per denaro a rischio, con il loro stato, la causa principale e i totali di tutta la classifica: lo stesso di Perdite di margine |
/v1/pnl/category-medians | L'abituale nel tuo account: la mediana del peso di ogni costo sulle vendite nette, per vedere se il costo di un prodotto è fuori dal normale |
/v1/pnl/inventory | Il capitale immobilizzato nei magazzini di Amazon: lo stock FBA di oggi valorizzato al costo, con i suoi giorni di stock, la rotazione e lo stoccaggio fino alla vendita: lo stesso di Inventario |
Nove cose da sapere prima della prima chiamata:
- Questa è l'unica parte dell'API che converte la valuta. Le altre risorse restituiscono ogni importo nella valuta in cui si è verificato; qui chiedi una
currencye tutto viene convertito in essa, al tasso di cambio del giorno in cui si è verificato ogni importo. Un giorno senza tasso di cambio ricade su uno approssimativo, mai su un errore. - Le spese proprie arrivano in
own_expenses. Le variabili sono già sottratte nella sezionevariable_expenses, prima del margine di contribuzione, eown_expenses.periods[].variablele suddivide per categoria. Le fisse (fixed) si sottraggono dopo, fino anet_profit. Siccome sono di tutto l'account, conconnection,countryocluster, o con un token che non raggiunge tutte le connessioni di vendita,fixedenet_profitescononullefixed_unavailabledice perché:filteredopartial_access. Se l'account non ha spese fisse non manca nulla, enet_profitesce anche con un filtro o con un token che non raggiunge tutte le connessioni. Nella tabella per prodotto, la colonnaown_expensesè la parte delle spese variabili di ogni prodotto. coveragedice quale parte delle vendite ha un costo reale. Un prodotto senza costo caricato non viene scartato né azzerato in silenzio:coverage.covered_salessucoverage.total_salesti dice quale proporzione della cifra è attendibile. Incoverage,estimated_salesè la parte dicovered_salescon costo stimato: lo stock ha venduto più unità di quelle lasciate dagli acquisti registrati, e quelle vendite portano l'ultimo costo medio.breakeven_acos, in/v1/seller-product-metrics, è fino a che ACOS puoi permetterti di spendere in pubblicità prima di perdere denaro su quel prodotto, calcolato con il tuo margine e il tuo costo reali -mai con una percentuale di commissione presunta. Escenull-mai un numero inventato- se il prodotto non ha un costo completo, non ha venduto nulla nel periodo, ha il costo registrato in una valuta diversa da quella del proprio marketplace (questa risorsa non converte le valute, a differenza di/v1/pnl/*), oppure se il tuo piano non include il costo prodotto (Free e Guru).- Il costo prodotto si conserva scendendo di piano, non viene eliminato. Se passi a Guru, il costo già caricato resta lì: smette solo di essere servito. Torna non appena risali di piano.
clusterrestringe/v1/pnl/cascade,/v1/pnl/products,/v1/pnl/clusters,/v1/pnl/freshness,/v1/pnl/margin-leaks,/v1/pnl/category-medianse/v1/pnl/inventoryai prodotti di uno o più cluster, come nelle metriche: con più id, l'unione, e un cluster senza prodotti restituisce un risultato vuoto, non un errore. La pubblicità conta solo la spesa di quei prodotti: Sponsored Brands e la spesa di campagna che non corrisponde a un prodotto specifico restano esclusi, perché non appartengono a nessun cluster. In/v1/pnl/clustersun prodotto che è in due cluster conta in entrambi, e ciò che non è in nessun cluster non appare./v1/pnl/margin-leaksrestituisce di default i prodotti di tutti e tre gli stati, come la schermata; constatustieni quelli che scegli. Nella stessa chiamata,summarydà quanti ce ne sono per stato e il totale a rischio dei prodotti in Perdita e Da monitorare di tutta la classifica, senza paginare, e ogni riga portamain_cause, il costo che ha tolto più margine, calcolato come nella schermata. Se il periodo precedente non ha vendite,has_previous_salesèfalse: l'elenco vuoto vuol dire che non c'è nulla da confrontare, non che non ci siano perdite./v1/pnl/inventoryè lo stock di oggi, senza periodo: una riga per stock, e nell'UE uno SKU paneuropeo compare una sola volta, con tutti i suoicountries, quindi non sommare righe tra paesi.summarydà il capitale immobilizzato di tutto il perimetro e la sua ripartizione per rotazione, senza paginare e senza cherotationesearchlo modifichino.currencyè obbligatoria: il costo si converte all'ultimo tasso di cambio e lo stoccaggio a quello di ogni giorno. Conta solo lo stock FBA delle tue connessioni Seller.- Il costo valido oggi di ogni prodotto arriva in
/v1/products. Il campocostcontienecogseshipping, ciascuno con l'importo unitario, la sua valuta,valid_fromesource, oppurenullse non ce l'ha. Concost_statetieni i prodotti attiviwith(con costo),missing(senza costo) omissing_with_sales(senza costo e con vendite negli ultimi 30 giorni, quelli che gonfiano di più il margine), e coninclude_totalsai quanti sono. È lo stesso che vedi in Costi e spese. In Free e Gurucostarrivanullecost_staterisponde403.
Cosa ha cambiato l'automazione su una campagna
/v1/campaigns/{id}/optimization-history risponde a cosa ha cambiato il workflow su una campagna, non a cosa ha deciso. La differenza conta: in uno storico di decisioni lo stesso target può comparire con un rialzo e un ribasso nella stessa notte, e lì non si vede che si annullano.
Per questo ogni riga arriva aggregata all'effetto netto dell'entità: l'offerta di prima del primo cambio del periodo contro quella di dopo l'ultimo, più quante volte si è mossa lungo il percorso. Un target salito da 0,18 € a 0,45 € e riportato a 0,18 € quella stessa notte torna con un netto di zero e due movimenti — che è la lettura utile, e proprio quella che un elenco nasconde.
Tre cose delimitano ciò che restituisce:
- Solo cambiamenti reali. Le simulazioni non sono esposte qui, con nessun parametro: sono offerte che non hanno mai raggiunto Amazon.
- Solo ciò che è stato applicato, non ciò che è stato proposto. L'ottimizzatore calcola un'offerta che un tetto può poi tagliare; viene riportato solo ciò che è stato inviato.
- Finestra di 90 giorni al massimo. È quanto vengono conservati questi record. Senza date, restituisce gli ultimi 90 giorni.
I cambiamenti che non sono di offerta — keyword raccolte, negativi, aggiustamenti di posizionamento, target in quarantena o bloccati — sono contati a parte in other_changes, perché non hanno un'offerta precedente con cui confrontarsi.
Tutto ciò che Epinium ha modificato su Amazon
/v1/advertising-changes risponde a una domanda diversa dalla precedente: non perché l'automazione ha deciso, ma cosa è stato toccato e se Amazon l'ha accettato. E non solo ciò che fa l'automazione: anche ciò che ha fatto una persona dall'applicazione, un processo interno o questa stessa API.
La regola sta in una riga: se è stato inviato ad Amazon, c'è una riga. Ne derivano tre conseguenze, ed è bene averle chiare:
- Anche ciò che Amazon ha rifiutato lascia una riga, con
result: "failed"e il messaggio di Amazon inerror. È il primo posto dove guardare quando una modifica non ha avuto effetto. - Ciò che non è stato nemmeno tentato non lascia riga: un budget sotto il minimo del paese, o un'offerta che era già quella richiesta.
- Le modifiche di configurazione dentro Epinium restano fuori, perché non arrivano ad Amazon.
Ogni riga dice da dove viene. source distingue l'applicazione (front), l'ottimizzatore (workflow), un processo interno (system) e questo canale (public-api, mcp), e actor identifica la persona o la credenziale specifica — quando la modifica l'ha fatta qualcuno dall'applicazione, lì c'è la sua email. Se viene da un workflow, correlation_id è l'identificatore di quella esecuzione, la chiave per incrociare questa risposta con optimization-history.
Puoi filtrare per campaign, adgroup, entity, entity_type, source, result, field e correlation_id, e restringere la finestra con start_date e end_date (YYYY-MM-DD, entrambi inclusi). I record si conservano dodici mesi.
Scrivere su Amazon
Con il permesso campaigns:write l'API smette di essere in sola lettura: crea campagne, ad group, target e product ad, e muove i loro stati, budget e offerte. Ciò che scrivi arriva davvero ad Amazon e lascia la sua riga in /v1/advertising-changes.
Cinque cose da sapere prima della prima chiamata:
- Tutto nasce in pausa. Una campagna o un ad group si creano
PAUSEDsalvo che chiedaENABLEDesplicitamente, perché ciò che è attivo inizia a spendere appena Amazon lo accetta. - Archiviare ha un verbo proprio:
DELETE /v1/<risorsa>/{id}. È l'unica operazione irreversibile di questa API: su Amazon archiviare non si annulla. Per questo non è un valore distateche potresti impostare per sbaglio accanto a un cambio di offerta, ma una chiamata separata con un verbo separato. Se vuoi solo fermare la spesa usastate: "PAUSED", che è reversibile. - Ogni scrittura richiede un header
Idempotency-Key. Riusa lo stesso valore se ritenti la stessa intenzione: senza, un timeout di rete diventa due campagne. - Un lotto non è tutto-o-niente.
POST /v1/<risorsa>/batchaccetta fino a 1000 entità e risponde una riga per entità, nell'ordine in cui le hai inviate.appliedè ciò che è arrivato ad Amazon, ed è l'unica cosa che si addebita. Un risultato parziale è la norma, non un errore: leggilo invece di ritentare tutto il lotto, perché un nuovo tentativo duplicherebbe ciò che era già passato. - Un'entità conta come applicata solo se è passato tutto ciò che hai chiesto. Se un
PATCHcambia stato e budget e Amazon accetta il primo e rifiuta il secondo, quell'entità tornafailedcon il motivo — dirla applicata è come finire per credere che l'offerta si sia mossa quando non è così.
| Rotta | Cosa fa |
|---|---|
POST /v1/campaigns | Creare una campagna |
POST /v1/campaigns/full | Campagna + ad group + target + product ad in una chiamata |
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batch | Stato, budget giornaliero, nome e portafoglio (il portafoglio, solo in Sponsored Products) |
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batch | Creare; stato, offerta predefinita e nome |
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batch | Creare target (i tipi dipendono dall'ad product dell'ad group); stato e offerta |
POST /v1/product-ads · PATCH /v1/product-ads/{id} · POST /v1/product-ads/batch | Pubblicizzare prodotti; stato |
POST /v1/portfolios · PATCH /v1/portfolios/{id} | Creare un portafoglio; nome, stato e tetto di budget |
DELETE /v1/campaigns/{id} · DELETE /v1/adgroups/{id} · DELETE /v1/targets/{id} · DELETE /v1/product-ads/{id} | Archiviare - irreversibile |
Ciò che non si può cambiare, e perché: ciò che definisce un target — la sua keyword, il suo ASIN, la sua corrispondenza — non è modificabile su Amazon, quindi per cambiarlo se ne crea un altro e si archivia il precedente. Un product ad accetta solo lo stato: è il collegamento tra un prodotto e un ad group, senza offerta né nome propri.
Il tetto di un portafoglio limita quanto spendono insieme tutte le sue campagne. MONTHLY_RECURRING si azzera ogni mese, DATE_RANGE vale tra startDate e endDate e NO_CAP lo toglie; la valuta è quella del marketplace e non si invia. In un PATCH, budget si sostituisce per intero: manda il tetto completo che vuoi, non solo l'importo. Per spostare una campagna Sponsored Products dentro o fuori da un portafoglio, cambia il suo portfolioId con PATCH /v1/campaigns/{id}.
Due codici da distinguere. Un'entità che non esiste, o che appartiene a un altro account, risponde 404 — mai 403, che confermerebbe che esiste. Un rifiuto di Amazon risponde 200 con result: "failed" e il motivo: la chiamata è arrivata, ciò che è fallito è il cambiamento.
Tutti e tre gli ad product si scrivono, ma non allo stesso modo:
- Sponsored Brands e Sponsored Display si modificano e si archiviano con le stesse rotte di Sponsored Products: stato, budget, nome e offerte di campagne, ad group, target e product ad. Quello che ancora non si può fare è crearli:
POST /v1/campaigns,/v1/campaigns/full,/v1/adgroupse/v1/product-adssono solo per Sponsored Products. - Gli ad group di Sponsored Brands non hanno offerta predefinita. Una modifica di
defaultBidsu uno di essi viene rifiutata con un messaggio che lo spiega. Quelli di Sponsored Display invece ce l'hanno. - Target e target negativi si creano anche negli ad group SB e SD, con
POST /v1/targets. IltargetTypeaccettato dipende dall'ad product dell'ad group (tabella qui sotto). Solo a livello di ad group: SB e SD non hanno target negativi di campagna. - Epinium controlla i limiti di offerta e budget del marketplace solo per Sponsored Products, prima dell'invio. Per Brands e Display non applica limiti propri: valida Amazon, e il suo motivo torna nella risposta, per entità con
result: "failed"oppure, alla creazione di target, infailure_details, dovereferenceidentifica il target (keyword, ASIN, SKU o l'id di audience, categoria o località).
| Ad product | targetType accettati |
|---|---|
| Sponsored Products | KEYWORD, PRODUCT, PRODUCT_CATEGORY |
| Sponsored Brands | Quelli di Sponsored Products più THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND o KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES) |
| Sponsored Display | KEYWORD; PRODUCT per ASIN o per sku, con productMatchType PRODUCT_EXACT o PRODUCT_SIMILAR; PRODUCT_CATEGORY con affinamenti (marca, prezzo, valutazione, fascia d'età, idoneità Prime); THEME (INTERESTED_AUDIENCE); PRODUCT_AUDIENCE (ASIN + event PURCHASE o VIEW + lookback di 7, 14, 30, 60, 90, 180 o 365 giorni); AUDIENCE (audienceId), CONTENT_CATEGORY (contentCategoryId) e LOCATION (locationId) |
Gli id di AUDIENCE, CONTENT_CATEGORY e LOCATION si ricavano dalla console di Amazon Ads: l'API non li elenca ancora.
Configurazione dell'ottimizzazione
Con lo stesso permesso campaigns:write, oltre a scrivere su Amazon puoi leggere e cambiare la configurazione che usa l'ottimizzatore di Epinium: cosa persegue in ogni campagna. È una superficie diversa da quella della sezione precedente, e conviene non confonderle.
Non arriva ad Amazon. È una configurazione propria di Epinium, che l'ottimizzatore consuma nella sua esecuzione di ogni notte, non un dato dell'account Amazon. Per questo qui non valgono due regole di "Scrivere su Amazon": non serve l'header Idempotency-Key - non c'è nessun andata-e-ritorno verso Amazon che un nuovo tentativo possa duplicare - e il cambio non lascia riga in /v1/advertising-changes, che registra solo ciò che è stato inviato ad Amazon.
Si legge con expand, non di default. GET /v1/campaigns e GET /v1/campaigns/{id} restituiscono optimizationConfig solo se chiedi ?expand[]=optimizationConfig. È opt-in perché pochissime campagne hanno questa configurazione salvata: senza expand, la colonna tornerebbe quasi sempre null.
Cosa si può impostare con PATCH /v1/campaigns/{id}/optimization-config, in linguaggio di business:
- L'obiettivo: un ACOS o un ROAS target, oppure un obiettivo di volume - impression o ordini - con un tetto di ACOS che lo accompagna.
- I limiti di offerta: il pavimento e il tetto che non può superare, il tetto del moltiplicatore di placement, e la spesa minima prima di negativizzare un target.
- Il budget mensile che persegue l'ottimizzatore - non il budget giornaliero della campagna su Amazon, che si cambia con
PATCH /v1/campaigns/{id}ed è un dato diverso con lo stesso nome. - Gli override di harvesting della campagna: il suo livello di discovery e se permette di puntare ad ASIN della concorrenza.
- Quali workflow la ottimizzano.
Quest'ultimo punto è quello che conta davvero: assegnare workflow è ciò che mette la campagna sotto ottimizzazione, non nessun altro campo di questo blocco. linkedWorkflowDefinitionIds la forza a entrare - il workflow la processa ogni notte anche se il suo filtro non l'avrebbe scelta - ed è la via con cui un workflow muove offerte reali su Amazon; confermalo con la persona prima di scriverlo, esattamente come per attivare un'automazione. Un workflow con selezione automatica può anche raccoglierla per conto suo, e workflowsOptOut: true è ciò che declina quella selezione automatica. L'unica cosa che la toglie con garanzia è excludedWorkflowDefinitionIds: vince sempre, qualunque cosa dica il resto.
aiEnabled non è l'interruttore dell'ottimizzatore
È il consenso del titolare dell'account, e viaggia verso Amazon come il tag epinium:ai_enabled. Metterlo a false non toglie la campagna dall'ottimizzazione: per questo c'è excludedWorkflowDefinitionIds, oppure toglierla da linkedWorkflowDefinitionIds.
optimizeDate e optimizingSince sono di sola lettura - li timbra l'ottimizzatore stesso - e scrivere uno dei due risponde con un 400.
POST /v1/campaigns/optimization-config/batch applica lo stesso patch fino a 1000 campagne, e non è tutto-o-niente: risponde una riga per campagna, nell'ordine in cui le hai inviate, e ognuna si valida contro il proprio stato salvato - un tetto obbligatorio per un obiettivo può essere facoltativo per un altro - quindi una riga può fallire senza che le altre ne risentano.
Due codici da distinguere, come per la scrittura su Amazon: un rifiuto di validazione - un obiettivo fuori intervallo, un workflow che non è tuo - risponde 200 con result: "failed" e il motivo in reason. Una campagna che non esiste o è di un altro account risponde 404 nel PATCH singolo; nel lotto, invece, quella stessa campagna torna come riga failed con reason: "not_found", proprio perché una riga fallita non affondi le altre 999.
| Rotta | Cosa fa |
|---|---|
PATCH /v1/campaigns/{id}/optimization-config | Cambiare la configurazione di ottimizzazione di una campagna |
POST /v1/campaigns/optimization-config/batch | La stessa configurazione su fino a 1000 campagne, una riga per risultato |
Scrivere task
Con il permesso tasks:write l'API crea task e decide sui loro suggerimenti, come fai tu in Processi → Attività. È il pezzo che permette a un assistente o a un'integrazione di proporre modifiche e a una persona di rivederle prima che arrivino ad Amazon.
Quattro cose da sapere prima della prima chiamata:
- Approvare non applica. Sono due passaggi: approvare o rifiutare ogni suggerimento, e poi
POST /v1/tasks/{id}/apply. A quel punto le modifiche di campagna — budget giornaliero, stato e nome — vanno ad Amazon subito, e la risposta dice quali sono entrate (applied) e quali ha rifiutato (failed). Quelle di prodotto vengono messe in coda (enqueued) e applicate in background: per sapere se sono entrate, rileggi i suggerimenti e guardaappliedAteapplyError. - Un suggerimento che niente sa applicare è una nota. Oggi si applicano quelli di prodotto e quelli di campagna che hanno un
fieldPath; quelli che non ce l'hanno, e quelli di ad group, target, product ad e termini di ricerca, restano note. Approvarli lascia traccia della decisione e non cambia nulla, e la risposta lo dice conautoApplySkipped: true. Non è un errore. Alla creazione, invece, un suggerimento di campagna con un campo diverso dadailyBudget,stateoname, o con un valore che non si può applicare, viene rifiutato con un400: salvarlo significherebbe promettere una modifica che nessuno farà. - I suggerimenti vanno con il task. Fino a 50 in
itemsquando lo crei, ognuno riferito a un'entità del tuo account; non se ne aggiungono dopo. Un'entità che non esiste o che è di un altro account fa rifiutare l'intero task, senza creare nulla. - Risolvere un task è definitivo. I suoi suggerimenti in sospeso non si risolvono con lui: restano congelati e non si possono più approvare. Decidi prima quelli che ti interessano e chiudi il task dopo. Risolverlo non fa nemmeno ripartire alcun workflow.
| Rotta | Cosa fa |
|---|---|
POST /v1/tasks | Creare un task, con i suoi suggerimenti |
PATCH /v1/tasks/{id} | Titolo, descrizione, priorità e data di scadenza |
POST /v1/tasks/{id}/resolve | Risolverlo o scartarlo |
PATCH /v1/task-items/{id} · POST /v1/task-items/batch | Approvare o rifiutare suggerimenti, facoltativamente con un tuo valore in appliedValue |
POST /v1/tasks/{id}/apply | Applicare ciò che è stato approvato |
POST /v1/tasks/listing-optimizations | Chiedere all'IA di Epinium di riscrivere schede, come suggerimenti di un task - spiegato in Riscrivere le schede con l'IA di Epinium |
Come su Amazon, ogni scrittura richiede Idempotency-Key, e il lotto di suggerimenti non è tutto-o-niente: risponde una riga per suggerimento e applied conta quelli che sono stati registrati. Creare, modificare o risolvere un task costa un addebito fisso per chiamata; approvare o rifiutare si addebita per suggerimento registrato. Applicare non si addebita a parte: ogni suggerimento è già stato addebitato quando è stato approvato.
Riscrivere le schede con l'IA di Epinium
Con il permesso tasks:write, POST /v1/tasks/listing-optimizations chiede all'IA di Epinium di riscrivere il titolo (con i suoi punti salienti, gli Item Highlights), i bullet point, la descrizione e i termini di ricerca di 1-20 prodotti del tuo catalogo. È la stessa generazione dell'applicazione: segue i cluster di keyword di ogni prodotto, i prompt collegati a essi e la tua identità di marca. Il risultato non modifica nessuna scheda: resta come suggerimenti in un task, quello dell'onboarding, perché una persona li riveda.
Cinque cose da sapere prima della prima chiamata:
- Risponde subito e genera dopo. La risposta è un
202con l'id del task (task) e quanto resta del tetto (limit). Ogni suggerimento compare nel task quando è pronto: leggili in/v1/task-itemsfiltrando pertask. - Niente arriva su Amazon senza passare da te. Approvi o rifiuti ogni suggerimento e applichi il task (
POST /v1/tasks/{id}/apply), come qualsiasi altro. Applicare lascia le modifiche in attesa di pubblicazione: arrivano su Amazon quando le pubblichi, dall'applicazione o conPOST /v1/pending-listing-changes/publish, che richiedecatalog:publish. - Non consuma i tuoi crediti, ma ha un tetto. La riscrittura la paga Epinium, fino a 20 prodotti per account in totale. Conta ogni prodotto di ogni chiamata, anche se ne rilanci uno o se la sua generazione fallisce. Una chiamata che chiede più prodotti di quelli che ti restano viene rifiutata per intero con un
403il cuicodeèlisting_optimization_limit_reached, senza generare nulla;limit(cap,used,remaining) ti dice in ogni risposta quanti te ne restano. Approvare o rifiutare i suggerimenti si addebita come in qualsiasi task. - Scegli tu prodotti e campi.
productssono id di prodotti del catalogo, Seller o Vendor (/v1/products; quelli di pubblicità non valgono).fieldsaccettatitle,bullets,descriptionesearch_terms; senza, si riscrivono tutti e quattro.titleriscrive anche i punti salienti. - Richiede
Idempotency-Key. Riusa la stessa chiave quando riprovi, altrimenti consumeresti di nuovo prodotti del tetto.
Scrivere cluster di keyword
Con il permesso catalog:write l'API crea e modifica i tuoi cluster di keyword, gli stessi che gestisci in Segmentazione → Cluster: un gruppo di prodotti con un nome, le keyword positive per cui dovrebbero posizionarsi o essere pubblicizzati e quelle negative da cui stare lontani. È il modo in cui un assistente che ha trovato un vuoto di keyword può lasciarlo salvato dove lo raccoglieranno i prompt SEO di Epinium, la scoperta di keyword dell'ottimizzatore e il filtro per cluster dei grafici di prodotto.
Quattro cose da sapere prima della prima chiamata:
- Niente arriva su Amazon. Un cluster vive in Epinium. Per questo queste scritture non lasciano righe in
/v1/advertising-changes, e per questo il tuo client di IA non ti chiederà conferma per farle. - Si modifica per delta, non per sostituzione.
PATCH /v1/clusters/{id}accettaaddPositiveKeywords,removePositiveKeywords,addNegativeKeywords,removeNegativeKeywords,addProducts,removeProducts,addPrompts,removePromptsename; invia solo ciò che cambia. Aggiungere una keyword già presente ne aggiorna lingua, punteggio e scopo, abbinata per testo; rimuoverne una che non c'è non fa nulla. Un cluster ammette fino a 100 keyword positive e 50 negative, contate dopo la modifica, e una keyword non può essere positiva e negativa allo stesso tempo. - Le keyword seguono le regole dell'applicazione. In minuscolo, fino a 80 caratteri, il set di caratteri di Amazon, senza
-né.all'inizio né-,+o.alla fine; i duplicati vengono uniti.languageè un codice comees-ESoen-GB,epiniumScoreva da 1 a 5 epurposeèSEO,PPCo entrambi (entrambi per impostazione predefinita). - Un cluster protetto viene rifiutato con
409. Proteggere un cluster dall'applicazione è una decisione di una persona, e questa API non può annullarla: rimuovi prima la protezione in Segmentazione → Cluster. Il campoprotecteddella risposta te lo dice prima di provare.
| Rotta | Cosa fa |
|---|---|
POST /v1/clusters | Creare un cluster, con le sue keyword, i suoi prodotti e i suoi prompt se già li hai |
PATCH /v1/clusters/{id} | Aggiungere o rimuovere keyword, prodotti e prompt, o rinominarlo |
DELETE /v1/clusters/{id} | Eliminarlo, senza possibilità di tornare indietro |
Ogni prompt che colleghi deve essere del tuo account, altrimenti la chiamata viene rifiutata con un 400 che nomina gli id in eccesso. Ogni prodotto che colleghi deve essere del tuo account — per un'agenzia, delle connessioni che l'account ti ha condiviso — e di catalogo (type seller o vendor in /v1/products; quelli pubblicitari vengono rifiutati), altrimenti l'intera chiamata viene rifiutata con un 400 che nomina gli id in eccesso, senza scrivere nulla. Il cluster resta intestato alla persona dietro la credenziale, quindi compare nella tabella dell'applicazione a suo nome. L'eliminazione è definitiva - non c'è cestino - e viene rifiutata con un 409 finché il cluster è protetto o una smart campaign lo usa come cluster di base; l'errore nomina quelle smart campaign, che vanno modificate o eliminate prima. Ogni scrittura costa un addebito fisso per chiamata, e la quota di cluster del piano si applica qui come nell'applicazione.
Scrivere prompt personalizzati
Con il permesso catalog:write l'API crea e modifica i tuoi prompt personalizzati, quelli della tua libreria di prompt: istruzioni con un nome che l'IA di Epinium segue quando redige il contenuto delle tue schede -tono, struttura, parole da usare o da evitare-. Leggerli richiede solo catalog:read, in /v1/prompts, e ogni cluster restituisce in prompts gli id dei suoi; con expand[]=prompts li restituisce interi.
Quattro cose da sapere prima della prima chiamata:
- Un prompt da solo non cambia nulla. Non tocca Amazon né riscrive alcuna scheda quando viene salvato: si applica quando si genera il contenuto dei prodotti dei cluster a cui lo colleghi (
addPromptsinPATCH /v1/clusters/{id}). Se più prompt dei cluster di un prodotto valgono per lo stesso campo, se ne usa solo uno, quindi lascia un prompt per campo. fieldsindica a quali campi della scheda si applica:titleAndHighlights(il titolo e i punti salienti dell'articolo, che si redigono insieme),product_description,bullet_pointogeneric_keyword(i termini di ricerca). Senzafields, o con[], vale per tutti. Un prompt vecchio può portare ancoraitem_name, il titolo da solo, che si legge ma non si accetta più in scrittura.- L'istruzione ha un tetto: fino a 2.000 caratteri, gli stessi dell'applicazione. Il nome ne richiede almeno 3.
- Quando modifichi, ciò che invii sostituisce ciò che c'era:
PATCH /v1/prompts/{id}accettaname,instructionefields, efieldssostituisce l'intera lista.
| Rotta | Cosa fa |
|---|---|
POST /v1/prompts | Creare un prompt |
PATCH /v1/prompts/{id} | Rinominarlo o cambiarne l'istruzione o i campi |
Il prompt resta intestato alla persona dietro la credenziale. L'eliminazione dei prompt non è disponibile tramite l'API. Ogni scrittura costa un addebito fisso per chiamata, e la quota di prompt del piano si applica qui come nell'applicazione: se l'hai già raggiunta, la creazione risponde 403.
Scrivere la tua identità di marca
Con il permesso catalog:write l'API crea e modifica la tua identità di marca, quella di Configurazione → Marchio: il nome del marchio, il settore, i siti web, quelli dei tuoi concorrenti, le tue osservazioni (tono, pubblico, parole da usare o evitare) e i brand del tuo catalogo che copre. È il contesto che usa l'IA di Epinium per redigere le tue schede. Leggerla richiede solo catalog:read, in /v1/brand-identities. Non sono i brand del tuo catalogo, che si trovano in /v1/product-brands.
Oltre ai siti web sciolti di competitor_urls, ogni concorrente può avere la sua scheda in competitors, fino a 50:
| Campo | Cos'è |
|---|---|
name | Nome del marchio o del venditore. Obbligatorio |
url | Il suo sito web o il suo negozio su Amazon |
asins | Gli ASIN dei suoi prodotti in concorrenza con i tuoi, fino a 20 |
threat | La sua pericolosità: level (low, medium o high) e reason, il motivo visto nei dati. Il livello non va mai senza il suo motivo; se non ci sono ancora prove, si lascia fuori |
price_position | Il suo prezzo rispetto al tuo: below, similar o above |
Quattro cose da sapere prima della prima chiamata:
- Le schede dei concorrenti non si vedono ancora nell'applicazione. Si salvano e si leggono tramite l'API e l'MCP; Configurazione → Marchio non le mostra ancora.
- Quando modifichi, una lista sostituisce quella che c'era.
PATCH /v1/brand-identities/{id}cambia solo i campi che invii, macompetitors,competitor_urls,brand_urlseproduct_brand_idssi sostituiscono per intero: per aggiungere un concorrente, invia quelli che avevi più il nuovo. I valori precedenti non vengono conservati da nessuna parte. - Le schede non sostituiscono
competitor_urls. Sono due liste indipendenti, e i siti web che avevi già restano. Un'identità salvata prima che esistessero le schede hacompetitorsvuoto. - Niente arriva su Amazon. L'identità di marca vive in Epinium: salvarla non tocca né riscrive le tue schede. Tramite l'API non si può eliminare né caricarne il logo.
| Rotta | Cosa fa |
|---|---|
POST /v1/brand-identities | Creare un'identità di marca |
PATCH /v1/brand-identities/{id} | Modificarne i campi o le liste |
Come ogni scrittura, richiede Idempotency-Key.
Modificare i listing da un file
Con il permesso catalog:write l'API salva modifiche agli attributi di molte schede Amazon in una volta, partendo da un Excel o da un CSV: qualsiasi attributo che Amazon permetta di modificare nel tipo di prodotto di ogni scheda, in Seller e in Vendor. È ciò che usa l'MCP di Epinium, dove il flusso completo è spiegato dal punto di vista di chi lo richiede.
| Rotta | Permesso | Cosa fa |
|---|---|---|
POST /v1/listing-files | catalog:read | Carica il file (.xlsx, .xls o .csv) e restituisce il suo file_id. Viene conservato 7 giorni |
POST /v1/listing-files/rows | catalog:write | Salva come file delle intestazioni e delle righe che hai già, senza caricare nulla |
POST /v1/listing-updates/prepare | catalog:read | Trova i prodotti del file per SKU, ASIN o EAN e dice quali attributi accettano |
POST /v1/listing-updates/validate | catalog:read | Convalida le righe con le regole di Amazon di ogni tipo di prodotto, senza salvare nulla |
POST /v1/listing-updates/apply | catalog:write | Salva le righe valide come modifiche in attesa di pubblicazione, in background |
GET /v1/listing-updates/apply/{file_id} | catalog:read | Lo stato di quel salvataggio, cosa è stato inviato e quanto è costato |
Cinque cose da sapere prima della prima chiamata:
- Niente arriva su Amazon al salvataggio.
applylascia le modifiche in attesa di pubblicazione, e partono verso Amazon quando qualcuno le pubblica da Pubblica modifiche in Epinium o conPOST /v1/pending-listing-changes/publish(vedi Creare nuove offerte su Amazon). - I dati che vanno insieme richiedono una persona. Un valore che obbliga a compilarne altri, come le batterie, viene salvato solo se il suo
cascade_idarriva inconfirmed_cascades; altrimenti finisce in un task da rivedere. Il resto della riga viene salvato comunque. - Si pagano 5 crediti per riga. Quando il file viene accettato si riservano 5 crediti per ogni riga, con un
402se il saldo non basta. Alla fine si addebitano solo le righe inviate e il resto viene restituito, per intero se fallisce. Caricare, preparare, validare e consultare lo stato non si pagano. - I prezzi vanno per pubblico. Una colonna si dichiara con
offer: { audience, field }(field:price,min,max,sale_price,sale_startosale_end);clear: truefa sì che le sue celle vuote cancellino, edate_order(dmyomdy) fissa l'ordine di date ambigue.validaterestituisce inoffer_clearsle colonne di prezzo con celle vuote su prodotti che hanno quel valore, e le regole di prezzo come problemi bloccantioffer_*. In Vendor non si modifica nessun prezzo: quelle colonne arrivano innot_applicablecon il motivovendor_price.prepareoffre i campi di prezzo inoffer_fields. - Un file si applica una volta. Ripetere la chiamata con le stesse impostazioni restituisce lo stato; con impostazioni diverse, o con un file a cui restano meno di 24 ore, risponde
409. Come ogni scrittura, richiedeIdempotency-Key.
I parametri di ogni rotta sono nel riferimento del catalogo.
Creare nuove offerte su Amazon
Con il permesso catalog:write l'API salva nuove offerte: prodotti che non sono ancora nel tuo account Amazon. Può essere un'offerta su un ASIN che esiste già (solo in Seller), un prodotto nuovo o una famiglia di varianti, in Seller e in Vendor. Cos'è ognuna, cosa chiede Amazon e come si pubblica una famiglia è spiegato in Nuove offerte di prodotti su Amazon.
| Rotta | Permesso | Cosa fa |
|---|---|---|
GET /v1/amazon-catalog/search | catalog:read | Cerca un prodotto nel catalogo di Amazon per ASIN, EAN, UPC o GTIN, con le sue restrizioni per il tuo account |
GET /v1/amazon-product-types/search | catalog:read | Consiglia tipi di prodotto a partire dal nome di un prodotto nuovo |
GET /v1/amazon-shipping-templates | catalog:read | I modelli di spedizione del tuo account Seller, per un'offerta che spedisci tu |
POST /v1/listing-drafts/validate | catalog:read | Convalida la nuova offerta con le regole di Amazon e con un'anteprima di Amazon, senza salvare nulla |
POST /v1/listing-drafts | catalog:write | Salva la nuova offerta in attesa di pubblicazione |
GET /v1/listing-drafts | catalog:read | Le tue nuove offerte e il loro stato, con ciò che ha risposto Amazon |
DELETE /v1/listing-drafts/{id} | catalog:write | Scarta una nuova offerta in sospeso |
GET /v1/pending-listing-changes | catalog:read | Ciò che è in attesa di pubblicazione, come in Pubblica modifiche |
POST /v1/pending-listing-changes/publish | catalog:write e catalog:publish | Pubblica su Amazon le modifiche e le nuove offerte scelte, per la stessa strada del pulsante Pubblicare dell'app |
Quattro cose da sapere prima della prima chiamata:
- Salvare non è pubblicare. La nuova offerta resta in sospeso finché non viene pubblicata dall'app o con
publish, che richiede anchecatalog:publishe non si può annullare. - Lo SKU deve essere nuovo in quel marketplace (in Vendor, sotto quel vendor code): uno che esiste già, in Epinium o su Amazon, risponde
409. - Salvare interroga di nuovo Amazon e risponde
400, con ciò che manca, se Amazon rifiuterebbe la nuova offerta: convalida prima. - Si pagano la convalida (1 credito) e il salvataggio (5). Cercare, i modelli, elencare, scartare e pubblicare non si pagano. Come ogni scrittura, salvare e pubblicare richiedono
Idempotency-Key.
I parametri di ogni rotta sono nel riferimento del catalogo.
Scrivere il costo di un prodotto
Con il permesso proprio costs:write -non catalog:write, che è per i cluster, i prompt e i listing- l'API crea o aggiorna il costo unitario e il costo di spedizione di un prodotto: la stessa azione che fai sulla scheda del prodotto o caricando il modello CSV dei costi, con la stessa semantica. Per molti prodotti alla volta, usa l'importazione.
| Rotta | Cosa fa |
|---|---|
POST /v1/products/{id}/costs | Crea o aggiorna il costo unitario (price) e il costo di spedizione (shipping_cost) di un prodotto |
Quattro cose da sapere prima della prima chiamata:
- La semantica è quella del CSV. Un campo vuoto non tocca il valore: se mandi solo
price, il costo di spedizione già presente resta invariato. Uno0lo azzera davvero -non è lo stesso che non mandare il campo. Almeno uno trapriceeshipping_costè obbligatorio. - Una data passata ricalcola lo storico.
datedi default è oggi; se mandi una data precedente, il nuovo costo si applica da lì e il P&L dei periodi già chiusi successivi si ricalcola da solo. La risposta dice cosa è successo inrecalculation:not_neededcon data di oggi,queuedse ha messo in coda il ricalcolo, ofailedse non è riuscito a metterlo in coda -il costo si salva comunque, solo che il P&L metterà un po' a rifletterlo. - Solo nei piani che includono il costo prodotto. In Free e Guru questa rotta risponde
403, come qualsiasi altra scrittura su quei piani. Come ogni scrittura, richiedeIdempotency-Key. - Un prodotto con acquisti non accetta
price. Il suo costo del prodotto lo calcolano gli acquisti registrati, quindi risponde409con il codiceCOST_FROM_PURCHASES. Per cambiare solo la sua spedizione, inviashipping_costda solo, senzaprice: con entrambi, si rifiuta tutto e la spedizione non viene salvata. Per cambiare il suo costo prodotto, registra o correggi un acquisto (Registrare gli acquisti di un prodotto).
Registrare gli acquisti di un prodotto
Quando un prodotto ha acquisti, il suo costo prodotto è il costo medio del suo stock: ogni acquisto lo ricalcola con le unità che avevi e quelle che acquisti. È lo stesso di Registrare gli acquisti sulla scheda del prodotto, con lo stesso calcolo. Leggere richiede catalog:read; registrare, correggere ed eliminare, costs:write. Entrambe le cose, solo nei piani che includono il costo prodotto.
| Rotta | Cosa fa |
|---|---|
GET /v1/products/{id}/purchases | Gli acquisti del prodotto, con il costo medio lasciato da ciascuno |
GET /v1/products/{id}/stock-group | Con quali prodotti condivide lo stock, o con quali verrebbe raggruppato al suo primo acquisto |
GET /v1/purchases | I tuoi acquisti, per account e per date |
GET /v1/purchases/{id} | Un acquisto |
POST /v1/products/{id}/purchases | Registra un acquisto |
PATCH /v1/purchases/{id} | Corregge un acquisto: invia solo ciò che cambia |
DELETE /v1/purchases/{id} | Elimina un acquisto |
- Lo stock condiviso ha un solo costo. Con il paneuropeo, lo stesso SKU nei paesi dell'UE è lo stesso stock, quindi un acquisto cambia il costo di tutti questi paesi (UK e Vendor vanno a parte). Il gruppo nasce con il primo acquisto; se oggi quei paesi hanno costi diversi, quell'acquisto richiede
prior_stock_unit_cost, quanto valeva lo stock già presente, oppure risponde400conPRIOR_STOCK_VALUE_REQUIRED. - Lo stock prima dell'acquisto. Senza
stock_on_handsi prende l'ultimo stock Amazon FBA dei 7 giorni precedenti, più gli acquisti registrati da allora. In FBM è obbligatorio. - Il numero d'ordine non si ripete. Con
reference, lo stesso acquisto inviato di nuovo risponde409conDUPLICATE_PURCHASE_EXTERNAL_IDinvece di duplicarsi. - Correggere o eliminare ricalcola. Cambia il costo medio di quell'acquisto e di quelli successivi, e il P&L dei periodi già chiusi, come un costo con data passata. L'eliminazione non si annulla; se era l'ultimo acquisto del gruppo, tornano a valere i costi di prima.
- Con più account, leggere ne richiede uno e scrivere tutti. Se lo stock è condiviso da account a cui la chiave non arriva, puoi leggere i loro acquisti ma non modificarli:
400conSTOCK_GROUP_OUT_OF_SCOPEquando registri,404quando correggi o elimini. - Ogni scrittura costa quanto scrivere un costo, e come ogni scrittura richiede
Idempotency-Key.
Importare i costi di molti prodotti
Per caricare il costo del tuo catalogo, usa l'importazione: è la stessa di Importare costi da un file nell'app, con lo stesso modello e le stesse regole, e ricalcola il P&L una sola volta, alla fine. Con lo stesso permesso costs:write.
Non farlo prodotto per prodotto con POST /v1/products/{id}/costs: ogni costo con una data passata ricalcola il P&L dell'intero account, e mentre è in corso l'API rifiuta i successivi con un 409.
| Rotta | Cosa fa |
|---|---|
POST /v1/cost-imports/files | Carica il file dei costi e restituisce il suo file_id, senza importare nulla. Viene conservato 7 giorni. GET elenca quelli che hai caricato |
POST /v1/cost-imports/preview | Controlla l'importazione senza salvare nulla: quali righe si applicherebbero, quali no e perché, quante sono senza data, quante conteranno solo fino a un costo successivo che il prodotto ha già e quanto costerebbe |
POST /v1/cost-imports | Importa i costi dei prodotti di un account, da file caricati o da righe |
GET /v1/cost-imports/{id} | Lo stato dell'importazione: quante righe sono state applicate, quante non cambiavano nulla e quante sono state rifiutate, con il motivo di ciascuna |
Cosa conviene sapere:
- Le righe arrivano in due modi. Con
file_ids, i file che hai caricato conPOST /v1/cost-imports/files(.xlsx,.xlso.csv, fino a 8 MB e 200.000 righe per importazione: un catalogo intero sta in un file; un Excel con molte colonne può non entrare, e allora si tolgono quelle in più o si carica come CSV). I file caricati per le modifiche ai listing non valgono qui. Oppure conheaderserows, fino a 5.000 righe, se non hai caricato nessun file. - Le colonne sono quelle del modello (
sellerSku,marketplace,date,cogs,cogsCurrency,shippingCosteshippingCostCurrency) e vengono riconosciute come nell'app, anche con nomi comuni come "sku", "cost" o "date". Se una non viene riconosciuta, indica da quale intestazione viene ogni dato concolumns. Ogni riga segue le regole del file dell'app. - Controllala prima, gratis.
POST /v1/cost-imports/previewriceve lo stesso corpo e applica le stesse regole riga per riga, compreso il confronto con il tuo catalogo, ma non salva né addebita nulla. Ti dice quante righe si applicherebbero, verrebbero saltate (vuote, o con lo stesso costo che il prodotto aveva già nella loro data:unchanged) o rifiutate, con il motivo ed esempi, quante sarebbero senza data e quanti crediti costerebbe. Solo all'applicazione una riga può ancora essere rifiutata, se non c'è un tasso di cambio per la sua valuta alla sua data. - Una riga senza data vale da oggi. Se le tue righe non hanno data, passa in
dateil giorno da cui valgono i costi: si applica alle righe senza data, e quelle che ce l'hanno tengono la loro. - I prodotti padre di variazione vengono rifiutati con
parent_product: non si vendono, quindi il loro costo non coprirebbe nessuna vendita. Il costo va sulle loro variazioni. - È asincrona. Risponde
202constatus: "processing". ConsultaGET /v1/cost-imports/{id}finché non indicafinished,finished_with_errorsoerror; consultarla non costa nulla. Le righe con una cella più lunga di quanto ammette il modello tornano innot_sente non vengono importate. - Resta nella cronologia dell'app, nella Cronologia dell'importazione dei costi di quell'account, come se l'avessi caricata dall'app.
- Un account per importazione. Mentre il P&L di quell'account si sta ricalcolando per una modifica di costo precedente, risponde
409senza importare nulla: aspetta che finisca e rilanciala. - Ogni riga applicata costa quanto scrivere il costo di un prodotto. Alla creazione si riservano le righe che possono essere applicate e, se il tuo saldo non basta, risponde
402senza importare nulla. Alla fine si addebitano solo le righe applicate e il resto viene restituito: le righe rifiutate e quelle che non cambiavano nulla non costano. Solo nei piani che includono il costo prodotto, e richiedeIdempotency-Key. - Anche acquisti. Con
kind: "purchases"importa acquisti con il modello degli acquisti dell'app (sellerSku,marketplace,date,units,currency,productCost,inboundShippingCost,tariffCost,otherCost,stockOnHand,reference), solo negli account Seller. Il controllo degli acquisti verifica solo il formato di ogni riga (checks: "format") e rifiuta già le righe malformate: lo SKU, il suo gruppo di stock e lo stock si verificano all'applicazione, quindi qualche riga in più può essere rifiutata in quel momento. Ogni acquisto applicato costa quanto registrarlo singolarmente.
Scrivere spese proprie
Le tue spese proprie (personale, agenzia, 3PL, software…) si leggono con catalog:read e si scrivono con lo stesso permesso costs:write del costo prodotto. Sono le stesse che registri in Costi e spese → Spese proprie, e il P&L le sottrae fino all'utile netto.
| Rotta | Cosa fa |
|---|---|
GET /v1/expenses | Le tue spese, filtrabili per basis, status (active, upcoming o ended) e category |
GET /v1/expenses/{id} | Una spesa, con lo storico dei suoi importi per mese |
POST /v1/expenses | Crea una spesa |
POST /v1/expenses/batch | Crea fino a 100 spese in una volta, da un elenco o da un foglio caricato (file_id), o le verifica senza creare nulla |
POST /v1/expenses/files | Carica un foglio di spese e restituisce il suo file_id, senza creare nulla. Si conserva 7 giorni. GET elenca quelli che hai caricato |
PATCH /v1/expenses/{id} | Cambia la voce o la categoria, o la termina con valid_to (null la riapre). Terminarla elimina i cambi di importo programmati dopo quel mese, e riaprirla non li recupera |
POST /v1/expenses/{id}/amounts | Cambia l'importo da un mese; i precedenti mantengono il loro |
DELETE /v1/expenses/{id} | La elimina da tutto lo storico |
GET /v1/expense-categories | Le categorie standard e le tue |
POST, PATCH e DELETE /v1/expense-categories | Crea, rinomina o elimina una tua categoria. Una categoria usata da qualche spesa non si può eliminare |
basis dice come si calcola ogni spesa: fixed (un importo fisso, con frequency monthly, quarterly, yearly o once e, in quest'ultimo caso, spread_months 1, 3, 6 o 12), per_unit (per unità venduta netta), pct_net_sales o pct_ad_spend (in punti: 5 è il 5 %). Le tre variabili accettano scope per applicarsi solo ad alcune connessioni o paesi.
Cinque cose da sapere prima della prima chiamata:
- Per più di una spesa, il batch.
POST /v1/expenses/batchne crea fino a 100 in una volta.dry_runè obbligatorio: mandalo prima contrue, che non scrive nulla né consuma crediti, e poi confalse. È tutto o niente: se una spesa fallisce non ne viene creata nessuna, efailure_detailsdice quali e perché.possible_duplicatesavvisa di quelle che somigliano a una che hai già o a un'altra dello stesso batch, senza bloccarle. Si addebitano solo le spese create. - Un foglio di spese, come file. Caricalo con
POST /v1/expenses/files(.xlsx,.xlso.csv, fino a 8 MB e 1.000 righe) e manda il suofile_idal batch: si legge con le stesse regole dell'importazione dell'app. Se le sue colonne non si chiamano come quelle del modello, indica da quale arriva ogni dato concolumns, e passa intypeecurrencyil tipo e la valuta delle righe che non li hanno. Una riga che non si può leggere torna infailure_detailscomerow N, e allora non si crea nulla. - Il P&L le sottrae subito. Le spese si calcolano quando si legge il P&L, quindi una creazione, una modifica o un'eliminazione si vede alla richiesta successiva, anche nei mesi già passati.
- Ogni token tocca le spese delle sue connessioni. Un token che non raggiunge tutte le connessioni di vendita dell'account vede e modifica solo le spese delle sue, e non può creare spese di tutto l'account (le fisse e le variabili senza connessioni in
scope) né rinominare o eliminare categorie: risponde403, e nel batch quella riga torna infailure_details. Una spesa che non può vedere risponde404. - Solo nei piani che includono il costo prodotto. In Free e Guru queste rotte rispondono
403, compreso il caricamento del file. Tutte le scritture, tranne il caricamento del file, richiedonoIdempotency-Key.
Limiti
- Le metriche richiedono un intervallo di date.
start_dateeend_datesono obbligatori su tutte le risorse di metriche. - L'intervallo ha un massimo, e dipende dalla granularità. Con
granularity=daily, 93 giorni; contotalo con i periodi di calendario (weekly,monthly,quarterly,yearly), 366. Su target e termini di ricerca, le risorse più pesanti, scendono a 31 e 93. Chiedere di più restituisce un errore che indica il limite esatto. Entrambe le date sono incluse nell'intervallo. - Gli elenchi si paginano in due modi. Le risorse di catalogo e struttura usano un cursore (
starting_after); quelle di metriche usanolimiteoffset. In entrambi i casihas_moreindica se c'è un'altra pagina. - C'è un limite di richieste per token. Se lo superi ricevi un
429e basta riprovare più lentamente. - C'è anche un limite di richieste simultanee. Un
429può significare "troppe insieme", non solo "troppe al minuto"; un503significa che il server è momentaneamente saturo. Entrambi portanoRetry-Aftered entrambi sono transitori: riprova con meno richieste in parallelo. - Una risposta non può espandere più di 5.000 oggetti.
expandsu liste — i prodotti di un cluster, i paesi di una connessione — si moltiplica a ogni livello. Superandolo ricevi un400che dice quanti oggetti avrebbe restituito: abbassalimit, togli unexpand, oppure chiedi quei dati al loro endpoint.
Crediti
Le chiamate a questa API consumano crediti del tuo account. Quanto costa ogni risorsa lo vedi nell'applicazione, in Impostazioni → Crediti.
Ogni risposta ti dice quanto hai speso:
| Header | Cos'è |
|---|---|
X-Epinium-Credits-Cost | Quanto è costata questa chiamata |
X-Epinium-Credits-Remaining | Quanto ti resta. È approssimativo: se hai altre cose che consumano contemporaneamente, può discostarsi |
X-Epinium-Credits-Breakdown | Il dettaglio, per risorsa e prezzo unitario: product=100x1,country=100x0 |
X-Epinium-Credits-Max | Il massimo che poteva costare, calcolato prima di eseguirla |
Tre cose da sapere:
- Si paga solo ciò che viene consegnato. Una chiamata che va in errore non consuma nulla, e nemmeno un
expandche non restituisce dati — perché il tuo token non ha quello scope, o il record è di un altro account. - Nelle metriche costa anche l'intervallo di date, non solo le righe. Chiedere un anno con
limit=1non è economico: oltre a ogni riga restituita si paga ogni giorno dell'intervallo, perché è quello che bisogna leggere per rispondere, con un minimo di 3 giorni per chiamata. Per spendere meno, accorcia l'intervallo. - Per un totale,
group_byinvece di paginare. Un totale di account è fatto di poche righe, una per valuta, mentre paginare il catalogo per sommarlo paga ogni prodotto in ogni pagina. In un account reale, il totale delle vendite di un mese costa 157 crediti congroup_by=accounte circa 17.600 paginando.
Se i crediti non bastano ricevi un 402 prima di eseguire la chiamata: non ti ritroverai mai con mezza risposta. E non dice solo di no, dice cosa cambiare e a quale valore:
{
"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 è lo stesso rimedio in forma leggibile da una macchina: limit, end_date o include_total. Se manca, nessun parametro fa entrare la chiamata e bisogna ricaricare.
Parametri e risposte di ogni endpoint
La tabella sopra dice quali risorse esistono. Per vedere i parametri di input e la forma esatta di ogni risposta ci sono due strade:
- Riferimento navigabile — ogni endpoint con i suoi parametri, i loro tipi e un esempio di risposta. È generato dall'API stessa, quindi non può diventare obsoleto. È in inglese.
- Schema OpenAPI — il documento OpenAPI 3.0 grezzo, da importare in Postman, Insomnia o un generatore di client. Non serve token.