API Epinium
Accès : Configuration → API Keys
Epinium expose vos données via une API REST pour que vous puissiez les lire depuis vos propres outils : un tableau de bord maison, un script d'analyse ou un assistant IA. Ce sont les mêmes informations que celles affichées dans l'application, avec les mêmes chiffres.
L'API lit vos données et écrit sur Amazon et dans vos boutiques : elle consulte catalogue, campagnes et métriques, votre P&L avec coût produit, et ce que contiennent vos boutiques Shopify et WooCommerce ; elle crée et édite des campagnes Sponsored Products et édite celles de Sponsored Brands et Display ; elle crée et édite des portefeuilles ; elle crée, édite, clone et exécute des workflows ; elle crée, résout et applique des tâches ; elle crée ou met à jour le coût de vos produits et enregistre leurs achats auprès des fournisseurs ; elle enregistre des modifications sur n'importe quel attribut de vos listings Amazon et crée de nouvelles offres : offres, nouveaux produits et familles de variations ; et elle crée, édite et supprime des produits et du contenu dans vos boutiques Shopify et WooCommerce connectées. Dans votre catalogue Amazon, ce que vous enregistrez reste en attente et n'arrive sur Amazon que lorsqu'il est publié, depuis l'application ou depuis l'API avec sa propre permission ; celui de vos boutiques change directement, sans rester en attente. Chaque domaine a sa permission, et celles d'écriture, c'est vous qui les donnez à la création de la clé.
Vous voulez l'utiliser depuis un assistant IA ?
Aucun développement n'est nécessaire. Le MCP Epinium connecte ces mêmes données à Claude et à d'autres assistants compatibles.
Générer un token
- Allez dans Configuration → API Keys
- Cliquez sur Créer une API key et donnez-lui un nom qui rappelle son usage
- Cochez les permissions nécessaires
- Copiez la clé et conservez-la en lieu sûr
- Utilisez-la dans l'en-tête
Authorizationde chaque requête
La clé ne s'affiche qu'une seule fois
La valeur complète apparaît une seule fois à la création. Si vous la perdez elle est irrécupérable : il faut la révoquer et en créer une autre.
Permissions
Chaque token porte les permissions cochées à sa création. N'accordez que celles dont votre intégration a besoin.
| Permission | Donne accès à |
|---|---|
catalog:read | Produits, marques, pays, clusters, prompts personnalisés et identité de marque, avec leurs métriques : ventes, frais Amazon et marge, retours, stock et, pour Vendor, avis ; et votre P&L, avec le coût produit et vos dépenses propres si votre plan l'inclut |
campaigns:read | Campagnes, portefeuilles, ad groups, targets, product ads et termes de recherche |
workflows:read | Vos workflows, leur configuration et les campagnes qu'ils atteignent |
connections:read | Les connexions de votre compte : Amazon, Shopify et WooCommerce |
tasks:read | Tâches Epinium et leurs items |
skills:read | Le catalogue de playbooks marketing validés d’Epinium |
platform:read | Ce que contiennent vos boutiques Shopify et WooCommerce : produits, stock, prix et le reste de ce qu'expose chaque boutique, lu en direct depuis sa propre API. Cela inclut le registre des modifications qui y sont faites (/v1/platform-changes, 1 crédit par ligne renvoyée) |
catalog:write | Créer, modifier et supprimer des clusters de mots-clés : leur nom, leurs mots-clés positifs et négatifs, les produits qu'ils regroupent et les prompts qu'ils utilisent. Créer et modifier des prompts personnalisés. Créer et modifier votre identité de marque, avec une fiche par concurrent. Enregistrer depuis un fichier des modifications d'attributs de vos listings Amazon, en attente de publication. Enregistrer et abandonner des nouvelles offres sur Amazon (offres sur des produits qui existent déjà, nouveaux produits et familles) et importer des images de produit. Rien n'arrive sur Amazon tant que vous ne le publiez pas |
costs:write | Créer ou mettre à jour le coût unitaire et le coût d'expédition de vos produits, et enregistrer, corriger et supprimer leurs achats, un par un ou en les important depuis un fichier ; et créer, modifier et supprimer vos dépenses propres et leurs catégories |
campaigns:write | Créer et modifier campagnes, portefeuilles, ad groups, targets et product ads sur Amazon, et configurer ce que l'optimiseur poursuit sur chacune |
platform:write | Créer, modifier et supprimer des produits et du contenu dans vos boutiques Shopify et WooCommerce connectées, directement et sans validation préalable, par la même route que celle qui sert à les consulter (POST /v1/platform-request) : une mutation dans Shopify, ou une méthode autre que GET dans WooCommerce, avec l'en-tête Idempotency-Key. Il faut aussi platform:read (le niveau Modifier de l'écran API Keys accorde les deux). Chaque modification est enregistrée pendant 12 mois et coûte autant qu'une consultation : 5 crédits par appel plus 1 par KB renvoyé |
tasks:write | Créer des tâches, approuver ou rejeter leurs suggestions, les clôturer et appliquer ce qui a été approuvé. Demander à l'IA d'Epinium de réécrire des fiches sous forme de suggestions d'une tâche |
workflows:write | Créer, copier, éditer, activer, mettre en pause, supprimer et restaurer des workflows, et les lancer ou les simuler |
catalog:publish | Publier sur Amazon les modifications de listings et les nouvelles offres en attente que vous choisissez (POST /v1/pending-listing-changes/publish), par le même chemin que le bouton Publier de l'application. Cela ne s'annule pas. Il faut aussi catalog:write |
L'écriture est réservée aux plans Business et Master. En Free et Guru, les tokens lisent : on ne peut ni créer une clé ni autoriser un assistant avec des permissions d'écriture, et si vous passez à l'un de ces plans, ceux que vous aviez déjà continuent de lire mais leurs écritures sont refusées avec un 403.
Un token atteint toutes les connexions de votre compte. Si vous êtes une agence, il atteint les connexions que chaque client vous a partagées en acceptant votre invitation.
Si vous êtes une agence : choisissez le compte à chaque appel
Un token d'agence atteint plusieurs comptes, donc chaque requête doit dire sur lequel elle opère. Avec l'en-tête Epinium-Account : <id du compte>, ou avec le paramètre account_id si vous appelez depuis le MCP.
/v1/me et /v1/accounts font exception : ils répondent sans choisir de compte, et ce sont justement eux qui vous disent quels comptes vous atteignez et comment ils s'appellent.
Le compte choisi, vous le voyez en entier : ses produits et ses campagnes sont limités aux connexions qu'il vous a partagées, et ses ressources de compte — workflows, tâches et clusters, qui ne dépendent d'aucune connexion — sont limitées au compte. Ce qui sort de votre portée n'est pas filtré en silence : un account_id auquel vous n'êtes pas invité renvoie une erreur explicite, pas une liste vide.
Quels endpoints elle couvre
Chaque ressource dispose d'un listing, et la plupart permettent aussi de récupérer un élément par son id. Les ressources de métriques n'ont qu'un listing : une ligne agrégée sur une plage de dates n'a pas d'identifiant propre.
Catalogue — catalog:read
| Endpoint | Ce qu'il renvoie |
|---|---|
/v1/products | Vos produits unifiés |
/v1/amazon-seller-products | La vue Seller Central de chaque produit, et la catégorie de son classement avec expand=salesRanks |
/v1/amazon-vendor-products | La vue Vendor Central, la catégorie du classement avec expand=salesRanks et les avis avec expand=customerFeedback |
/v1/amazon-advertising-products | La vue Advertising |
/v1/seller-product-metrics | Ventes, sessions, Buy Box, rank, frais Amazon, marge, retours, stock, B2B et jours de couverture par produit |
/v1/vendor-product-metrics | Ventes Vendor par produit, avec manufacturing et sourcing, retours, sell-in avec Amazon, inventaire et jours de couverture |
/v1/product-brands | Vos marques |
/v1/countries | Pays et marketplaces |
/v1/clusters | Vos clusters de mots-clés ; avec catalog:write, vous les créez et les modifiez aussi |
/v1/pnl/* | Votre P&L : cascade, tableau par produit, par cluster, par canal de vente, publicité croisée, fraîcheur, fuites de marge et inventaire - expliqué dans Le P&L avec coût produit |
/v1/prompts | Vos prompts personnalisés ; avec catalog:write, vous les créez et les modifiez aussi |
/v1/brand-identities | Votre identité de marque, avec une fiche par concurrent ; avec catalog:write vous la créez et la modifiez aussi - expliqué dans Écrire votre identité de marque |
/v1/listing-files | Les fichiers de modifications de listings que vous avez importés au cours des 7 derniers jours ; en importer un demande catalog:read, et enregistrer comme fichier des lignes écrites à la main, catalog:write |
/v1/listing-updates | Préparer et valider les modifications d'un fichier sans rien enregistrer ; avec catalog:write, les enregistrer en attente de publication - expliqué dans Modifier des listings depuis un fichier |
/v1/listing-drafts | Vos nouvelles offres sur Amazon et leur état ; avec catalog:write, les enregistrer et les écarter. Pour rechercher le produit et les valider, /v1/amazon-catalog/search, /v1/amazon-product-types/search, /v1/amazon-shipping-templates et /v1/listing-drafts/validate - expliqué dans Créer de nouvelles offres sur Amazon |
/v1/listing-images | Avec catalog:write, importer une image de produit pour un listing ou une nouvelle offre : JPG, PNG, GIF ou TIFF, jusqu'à 8 Mo, conservée 30 jours |
/v1/pending-listing-changes | Ce qui est en attente de publication sur Amazon, modifications et nouvelles offres ; avec catalog:write et catalog:publish, le publier |
/v1/publications | Chaque publication sur Amazon et où elle en est par pays, comme le panneau Publications de l'application |
Publicité — campaigns:read
| Endpoint | Ce qu'il renvoie |
|---|---|
/v1/campaigns | Vos campagnes Amazon Advertising |
/v1/campaigns/budget-usage | Ce que chaque campagne a dépensé aujourd'hui de son budget quotidien, selon Amazon, avec au plus une demi-heure de retard |
/v1/campaign-metrics | Dépense, ventes, ACOS et ROAS par campagne |
/v1/portfolios | Vos portefeuilles et le plafond de budget que chacun impose à ses campagnes |
/v1/portfolios/budget-usage | Ce que chaque portefeuille a dépensé de son plafond sur la période, son rythme et ce qu’il peut dépenser par jour pour finir pile au plafond |
/v1/adgroups | Les ad groups de chaque campagne |
/v1/adgroup-metrics | Performance par ad group |
/v1/targets | Mots-clés et targets produit |
/v1/target-metrics | Performance par target, avec son mot-clé et son type de correspondance |
/v1/product-ads | Le lien entre un ad group et le produit qu'il annonce |
/v1/product-ad-metrics | Performance par produit annoncé, avec son ASIN |
/v1/search-terms | Les recherches réelles des acheteurs |
/v1/search-term-metrics | Performance par recherche, avec le texte et le target qui l'a associée |
/v1/campaigns/{id}/optimization-history | Ce que l'automatisation a changé sur une campagne, avec l'effet net |
/v1/advertising-changes | Tout ce qu'Epinium a modifié sur Amazon, quelle qu'en soit l'origine |
Automatisation — workflows:read
| Endpoint | Ce qu'il renvoie |
|---|---|
/v1/workflows | Vos workflows, avec leur planification et s'ils sont actifs |
/v1/workflows/{id} | La configuration complète de l'un d'eux : son diagramme et chaque variable avec sa valeur effective |
/v1/workflows/{id}/campaigns | Les campagnes qu'il atteint réellement, et pourquoi chacune en fait partie |
/v1/workflows/{id}/performance | La performance de ces campagnes, avec leur objectif à côté pour pouvoir la juger |
Un workflow peut être planifié chaque nuit et ne toucher aucune campagne : /campaigns est ce qui le révèle, et quand l'ensemble revient vide il en donne la raison.
Connexions, tâches et skills
| Endpoint | Permission | Ce qu'il renvoie |
|---|---|---|
/v1/connections | connections:read | Vos connexions : Amazon, Shopify et WooCommerce |
POST /v1/platform-request | platform:read, et platform:write pour écrire | Une requête vers l'une de vos boutiques ou, avec platform:write, une modification : GraphQL sur Shopify, REST sur WooCommerce |
/v1/platform-request/docs/{platform} | platform:read | La version de l'API de cette plateforme, sa référence et les champs qu'a votre boutique en ce moment |
/v1/tasks | tasks:read | Tâches Epinium |
/v1/task-items | tasks:read | Les items de chaque tâche |
/v1/skills | skills:read | Le catalogue de playbooks marketing d’Epinium |
Le catalogue de skills est du contenu rédigé par Epinium, pas des données de votre compte : il est identique pour tous les clients. Les parties de chaque playbook que vous recevez dépendent de votre plan.
Les requêtes vers vos boutiques ne renvoient aucune donnée personnelle : noms, e-mails, téléphones et adresses sont refusés avant que la requête n'atteigne la boutique. Elles sont facturées selon la taille de la réponse, comme les modifications. Ces deux routes ne figurent pas dans la référence navigable : on les utilise d'habitude depuis le MCP Epinium.
Il existe également /v1/me, qui indique quelles permissions et quels comptes votre token atteint. C'est le premier appel utile pour vérifier que la clé fonctionne.
Trois règles pour lire les données
Ces trois points expliquent presque toutes les questions d'interprétation :
- Les montants sont du texte, pas des nombres.
"cost": "8.22"arrive en chaîne à dessein, pour ne pas perdre de précision à la conversion en décimal binaire. - Les ratios sont en fraction, pas en pourcentage. Un ACOS de 90,83 % arrive comme
0.908287. Multipliez par 100 pour l'afficher. nulln'est pas0.nullsignifie qu'Amazon n'a pas remonté la donnée ;0signifie un vrai zéro. Unacosànullest une campagne qui a dépensé sans vendre, pas de la publicité gratuite. Etnew_to_brand_salesarrive ànullen Sponsored Products parce qu'Amazon ne le mesure pas pour ce format.
Rentabilité, stock et avis de vos produits
Les métriques produit ne s'arrêtent pas aux ventes : elles disent aussi ce que garde Amazon, combien de stock il reste et ce que pensent les acheteurs. Quatre points avant de tirer des conclusions :
- Les frais et la marge Seller sont hors TVA, alors que
salesl'inclut là où elle s'applique : ne soustrayez pas les uns de l'autre.margin_before_adsest ce qui reste après avoir payé Amazon, avant publicité et coût du produit : pour la marge après publicité, soustrayez-lui la dépense de/v1/product-ad-metrics. Amazon impute le stockage à un seul jour du mois et les retours à la date du remboursement, donc la marge se lit par mois, pas par jour. days_of_coverageest le nombre de jours que dure le stock au rythme de la période : le stock du dernier jour divisé par les unités moyennes par jour de la plage demandée. Il vautnullavec toute granularité autre quetotal, si le produit n'a rien vendu ou, en regroupant, sigroup_byn'inclut pas le pays. Avecorder_by=days_of_coverage&order=asc, vous obtenez d'abord ceux qui sont sur le point d'être en rupture.- Côté Vendor il y a aussi le sell-in : les unités que vous avez confirmées à Amazon, celles des commandes d'achat ouvertes, le taux de remplissage et le délai de livraison, ainsi que les retours séparés entre manufacturing et sourcing et la santé de l'inventaire.
- La catégorie du classement et les avis se demandent au produit, pas aux métriques.
expand=salesRanksindique à quelle catégorie appartient chaque position du Best Seller Rank, et côté Vendorexpand=customerFeedbackrenvoie les thèmes positifs et négatifs des avis et les motifs de retour de la catégorie. C'est l'image de la semaine, avec la tendance sur six mois calculée par Amazon, pas un historique.
Totaux du compte, par période et par cluster
Pour savoir combien le compte a vendu en septembre, inutile de paginer le catalogue et de faire la somme : les sept ressources de métriques agrègent d'elles-mêmes.
group_byadditionne les entités entre elles.accountdonne le total du compte ;countryetconnectionventilent par pays ou par connexion, et se combinent en répétant le paramètre (group_by[]=connection&group_by[]=country).accountne se combine avec rien. Les lignes restent séparées par devise (les montants ne sont jamais convertis) et, en publicité, par type d'annonce (SP,SB,SD).granularitydécoupe la plage en périodes calendaires. En plus detotaletdaily, elle accepteweekly,monthly,quarterlyetyearly, et chaque ligne porte dansdatele début de sa période : le lundi de la semaine ou le 1er du mois, du trimestre ou de l'année. Les périodes aux extrémités sont partielles : du 15 janvier au 10 mars avecmonthly, vous obtenez janvier du 15 au 31, février entier et mars du 1er au 10.clusterrestreint à une famille de produits. Dans les métriques Seller, Vendor et produit annoncé,cluster=<id>ne garde que les produits de ce cluster ; avec plusieurs ids, leur union. Il se combine avec ce qui précède :group_by=account&granularity=monthly&cluster=<id>donne la série mensuelle de cette famille.group_by=clusterdonne une ligne par cluster. Sur les trois mêmes métriques,group_by=clusterrenvoie en un seul appel les chiffres de chacun de vos clusters, avec son id dansclusteret son nom danscluster_name. Un produit présent dans plusieurs clusters compte en entier dans chacun d'eux : les lignes ne s'additionnent donc pas en total du compte, et les produits sans cluster n'apparaissent pas. Il se combine aveccountryetconnection, et avec le filtreclusterpour choisir les clusters renvoyés ; si vos clusters dépassent 2 000 appartenances produit-cluster, l'API vous demande de les restreindre avec ce filtre.
Dans les lignes regroupées, les champs qui identifient une entité (product, asin, campaign…) valent null, de même que ce qui ne peut pas s'additionner : le rank, le prix, le canal et les taux Vendor. Le stock Seller ne s'additionne que si vous regroupez par pays : avec l'inventaire paneuropéen FBA, Amazon remonte le même stock sur chaque marketplace, et l'additionner entre pays compterait plusieurs fois les mêmes unités. C'est pourquoi, avec group_by=account ou connection, stock et days_of_coverage valent null.
Un cluster regroupe des produits du catalogue, pas des ASIN isolés : le même ASIN sur une autre connexion reste exclu, sauf si son produit figure aussi dans le cluster. Et les lignes qu'Amazon n'a pas pu associer à un produit du catalogue n'entrent pas dans le filtre : environ 5 % des ventes Vendor et 3 % de la dépense en produits annoncés.
Ce que cela fait économiser en crédits, vous le trouverez dans Crédits.
Le P&L avec coût produit
C'est le même compte de résultat que celui que vous voyez dans Rentabilité → P&L : ventes, commissions et logistique Amazon, publicité et, si votre plan l'inclut, le coût de vos produits et vos dépenses propres, avec le même calcul et les mêmes chiffres.
Ce que vous voyez dépend de votre plan. En Free et Guru, le P&L va jusqu'à margin_before_ads : ce qui reste après Amazon, avant la publicité et avant le coût produit - ne l'appelez pas « profit », car ce n'en est pas un. En Business et Master, il va jusqu'au bout : marge de contribution, chaque ligne de coût produit et sa couverture, et vos dépenses propres jusqu'au bénéfice net. includes_product_cost dans chaque réponse vous dit laquelle des deux vous regardez, vous n'avez donc pas à le deviner selon que les chiffres correspondent ou non à ce que vous attendiez. Fuites de marge (/v1/pnl/margin-leaks et /v1/pnl/category-medians) est réservé à Business et Master : en Free et Guru, la réponse est 403 avec code: "plan_feature_not_allowed", et ses réponses ne portent pas includes_product_cost, car elles incluent toujours le coût. Il en va de même pour l'inventaire (/v1/pnl/inventory), valorisé au coût produit.
| Endpoint | Ce qu'il renvoie |
|---|---|
/v1/pnl/cascade | La cascade de la période : ventes, remboursements, commissions, logistique, publicité, coût produit et dépenses propres jusqu'au bénéfice net, mois par mois ou jour par jour |
/v1/pnl/products | Une ligne par produit, avec sa marge de contribution et sa couverture de coût |
/v1/pnl/products/{id} | Le détail d'un produit : sa propre cascade, mois par mois |
/v1/pnl/clusters | Une ligne par cluster, avec sa marge de contribution, sa couverture des coûts et son nombre de produits |
/v1/pnl/channels | Une ligne par canal de vente (Seller, Vendor…), avec sa publicité ventilée par plateforme |
/v1/pnl/ads-matrix | La dépense publicitaire croisée : sur quel canal de vente chaque plateforme fait de la publicité |
/v1/pnl/freshness | La date de la dernière donnée de chaque source -Amazon, publicité et coût produit- pour savoir si ce que vous lisez est déjà complet |
/v1/pnl/margin-leaks | Les produits qui ont perdu de la marge par rapport à la période précédente, triés par montant à risque, avec leur statut, leur cause principale et les totaux de tout le classement : la même chose que Fuites de marge |
/v1/pnl/category-medians | L'habituel de votre compte : la médiane du poids de chaque coût dans les ventes nettes, pour voir si le coût d'un produit sort de l'ordinaire |
/v1/pnl/inventory | Le capital immobilisé dans les entrepôts d'Amazon : le stock FBA du jour valorisé au coût, avec ses jours de stock, sa rotation et le stockage jusqu'à la vente : la même chose que Inventaire |
Neuf choses à savoir avant le premier appel :
- C'est la seule partie de l'API qui convertit la devise. Les autres ressources renvoient chaque montant dans la devise où il s'est produit ; ici vous demandez une
currencyet tout y est converti, au taux de change du jour où chaque montant s'est produit. Un jour sans taux de change retombe sur un taux approximatif, jamais sur une erreur. - Les dépenses propres arrivent dans
own_expenses. Les variables sont déjà déduites dans la sectionvariable_expenses, avant la marge de contribution, etown_expenses.periods[].variableles détaille par catégorie. Les fixes (fixed) sont déduites ensuite, jusqu'ànet_profit. Comme elles concernent tout le compte, avecconnection,countryoucluster, ou avec un token qui n'atteint pas toutes les connexions de vente,fixedetnet_profitvalentnulletfixed_unavailabledit pourquoi :filteredoupartial_access. Si le compte n'a pas de dépenses fixes, rien ne manque etnet_profitest renvoyé même avec un filtre ou un token qui n'atteint pas toutes les connexions. Dans le tableau par produit, la colonneown_expensesest la part des dépenses variables de chaque produit. coverageindique quelle part des ventes a un coût réel. Un produit sans coût chargé n'est ni écarté ni mis à zéro en silence :coverage.covered_salessurcoverage.total_salesvous dit quelle proportion du chiffre est fiable. Danscoverage,estimated_salesest la part decovered_salesavec un coût estimé : le stock a vendu plus d'unités que n'en ont laissé les achats enregistrés, et ces ventes portent le dernier coût moyen.breakeven_acos, sur/v1/seller-product-metrics, est le plafond d'ACOS que vous pouvez vous permettre de dépenser en publicité avant de perdre de l'argent sur ce produit, calculé avec votre marge et votre coût réels -jamais avec un pourcentage de commission supposé. Il revient ennull-jamais un chiffre inventé- si le produit n'a pas de coût complet, n'a rien vendu sur la période, a son coût enregistré dans une devise différente de celle de sa propre marketplace (cette ressource ne convertit pas les devises, contrairement à/v1/pnl/*), ou si votre plan n'inclut pas le coût produit (Free et Guru).- Le coût produit est conservé en cas de rétrogradation de plan, il n'est pas supprimé. Si vous passez en Guru, le coût déjà chargé reste là : il cesse simplement d'être servi. Il revient dès que vous remontez de plan.
clusterrestreint/v1/pnl/cascade,/v1/pnl/products,/v1/pnl/clusters,/v1/pnl/freshness,/v1/pnl/margin-leaks,/v1/pnl/category-medianset/v1/pnl/inventoryaux produits d'un ou plusieurs clusters, comme dans les métriques : avec plusieurs ids, leur union, et un cluster sans produits renvoie un résultat vide, pas une erreur. La publicité ne compte que la dépense de ces produits : Sponsored Brands et les dépenses de campagne qui ne correspondent à aucun produit précis sont exclus, car ils n'appartiennent à aucun cluster. Dans/v1/pnl/clusters, un produit présent dans deux clusters compte dans les deux, et ce qui n'est dans aucun cluster n'apparaît pas./v1/pnl/margin-leaksrenvoie par défaut les produits des trois statuts, comme l'écran ;statusne garde que ceux que vous choisissez. Dans le même appel,summarydonne combien il y en a dans chaque statut et le total à risque des produits en Fuite et À surveiller de tout le classement, sans paginer, et chaque ligne portemain_cause, le coût qui a le plus réduit la marge, calculé comme à l'écran. Si la période précédente n'a pas de ventes,has_previous_salesvautfalse: la liste vide signifie qu'il n'y a rien à comparer, pas qu'il n'y a pas de fuites./v1/pnl/inventoryest le stock du jour, sans période : une ligne par stock, et dans l'UE un SKU paneuropéen apparaît une seule fois, avec tous sescountries, donc n'additionnez pas les lignes entre pays.summarydonne le capital immobilisé de tout le périmètre et sa répartition par rotation, sans pagination et sans être affecté parrotationnisearch.currencyest obligatoire : le coût est converti au dernier taux de change et le stockage au taux de chaque jour. Seul compte le stock FBA de vos connexions Seller.- Le coût valable aujourd'hui de chaque produit arrive dans
/v1/products. Le champcostcontientcogsetshipping, chacun avec le montant unitaire, sa devise,valid_frometsource, ounulls'il n'en a pas. Aveccost_state, vous gardez les produits actifswith(avec coût),missing(sans coût) oumissing_with_sales(sans coût et avec des ventes ces 30 derniers jours, ceux qui gonflent le plus la marge), et avecinclude_totalvous savez combien il y en a. C'est la même chose que dans Coûts et dépenses. En Free et Guru,costvautnulletcost_staterépond403.
Ce que l'automatisation a changé sur une campagne
/v1/campaigns/{id}/optimization-history répond à ce que le workflow a changé sur une campagne, pas à ce qu'il a décidé. La différence compte : dans un historique de décisions, le même target peut apparaître avec une hausse et une baisse la même nuit, et là on ne voit pas qu'elles s'annulent.
Chaque ligne arrive donc agrégée à l'effet net de l'entité : l'enchère d'avant le premier changement de la période face à celle d'après le dernier, plus le nombre de fois où elle a bougé en chemin. Un target passé de 0,18 € à 0,45 € puis ramené à 0,18 € la même nuit revient avec un net de zéro et deux mouvements — c'est la lecture utile, et précisément celle qu'une liste masque.
Trois choses délimitent ce qu'il renvoie :
- Uniquement les changements réels. Les simulations ne sont pas exposées ici, avec aucun paramètre : ce sont des enchères qui n'ont jamais atteint Amazon.
- Uniquement l'appliqué, pas le proposé. L'optimiseur calcule une enchère qu'un plafond peut ensuite rogner ; seul ce qui a été envoyé est rapporté.
- Fenêtre de 90 jours au maximum. C'est la durée de conservation de ces enregistrements. Sans dates, il renvoie les 90 derniers jours.
Les changements qui ne sont pas des enchères — keywords récoltées, négatifs, ajustements d'emplacement, targets en quarantaine ou bloqués — sont comptés à part dans other_changes, car ils n'ont pas d'enchère antérieure à laquelle se comparer.
Tout ce qu'Epinium a modifié sur Amazon
/v1/advertising-changes répond à une question différente de la précédente : non pas pourquoi l'automatisation a décidé, mais ce qui a été touché et si Amazon l'a accepté. Et pas seulement ce que fait l'automatisation : aussi ce qu'une personne a fait depuis l'application, un processus interne ou cette API elle-même.
La règle tient en une ligne : si c'est parti vers Amazon, il y a une ligne. Trois conséquences en découlent, et mieux vaut les avoir claires :
- Ce qu'Amazon a refusé laisse aussi une ligne, avec
result: "failed"et le message d'Amazon danserror. C'est le premier endroit où regarder quand un changement n'a pas pris effet. - Ce qui n'a jamais été tenté ne laisse pas de ligne : un budget sous le minimum du pays, ou une enchère qui était déjà celle demandée.
- Les changements de configuration à l'intérieur d'Epinium restent dehors, car ils ne partent pas vers Amazon.
Chaque ligne dit d'où elle vient. source distingue l'application (front), l'optimiseur (workflow), un processus interne (system) et ce canal (public-api, mcp), et actor identifie la personne ou la clé concernée — quand le changement vient de quelqu'un dans l'application, son email est là. S'il vient d'un workflow, correlation_id est l'identifiant de cette exécution, la clé pour croiser cette réponse avec optimization-history.
Vous pouvez filtrer par campaign, adgroup, entity, entity_type, source, result, field et correlation_id, et borner la fenêtre avec start_date et end_date (YYYY-MM-DD, les deux inclus). Les enregistrements sont conservés douze mois.
Écrire sur Amazon
Avec la permission campaigns:write, l'API ne fait plus que lire : elle crée campagnes, ad groups, targets et product ads, et déplace leurs états, budgets et enchères. Ce que vous écrivez part réellement vers Amazon et laisse sa ligne dans /v1/advertising-changes.
Cinq choses à savoir avant le premier appel :
- Tout naît en pause. Une campagne ou un ad group est créé
PAUSEDsauf si vous demandezENABLEDexplicitement, car ce qui est actif commence à dépenser dès qu'Amazon l'accepte. - Archiver a son propre verbe :
DELETE /v1/<ressource>/{id}. C'est la seule opération irréversible de cette API : sur Amazon, archiver ne se défait pas. C'est pourquoi ce n'est pas une valeur destateque vous pourriez poser par mégarde à côté d'un changement d'enchère, mais un appel distinct avec un verbe distinct. Pour seulement arrêter la dépense, utilisezstate: "PAUSED", qui est réversible. - Toute écriture exige un en-tête
Idempotency-Key. Réutilisez la même valeur si vous réessayez la même intention : sans cela, un timeout réseau devient deux campagnes. - Un lot n'est pas tout-ou-rien.
POST /v1/<ressource>/batchaccepte jusqu'à 1000 entités et répond une ligne par entité, dans l'ordre d'envoi.appliedest ce qui est arrivé chez Amazon, et c'est la seule chose facturée. Un résultat partiel est le cas normal, pas une erreur : lisez-le au lieu de réessayer tout le lot, car un nouvel essai dupliquerait ce qui est déjà passé. - Une entité n'est appliquée que si tout ce que vous avez demandé est passé. Si un
PATCHchange état et budget et qu'Amazon accepte le premier et refuse le second, cette entité revient enfailedavec le motif — la déclarer appliquée, c'est croire qu'une enchère a bougé alors que non.
| Route | Ce qu'elle fait |
|---|---|
POST /v1/campaigns | Créer une campagne |
POST /v1/campaigns/full | Campagne + ad group + targets + product ads en un appel |
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batch | État, budget quotidien, nom et portefeuille (le portefeuille, en Sponsored Products uniquement) |
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batch | Créer ; état, enchère par défaut et nom |
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batch | Créer des targets (les types dépendent de l'ad product de l'ad group) ; état et enchère |
POST /v1/product-ads · PATCH /v1/product-ads/{id} · POST /v1/product-ads/batch | Annoncer des produits ; état |
POST /v1/portfolios · PATCH /v1/portfolios/{id} | Créer un portefeuille ; nom, état et plafond de budget |
DELETE /v1/campaigns/{id} · DELETE /v1/adgroups/{id} · DELETE /v1/targets/{id} · DELETE /v1/product-ads/{id} | Archiver - irréversible |
Ce qui ne peut pas changer, et pourquoi : ce qui définit un target — son mot-clé, son ASIN, son type de correspondance — n'est pas modifiable sur Amazon ; pour le changer, on en crée un autre et on archive le précédent. Un product ad n'accepte que l'état : c'est le lien entre un produit et un ad group, sans enchère ni nom propres.
Le plafond d'un portefeuille limite ce que dépensent ensemble toutes ses campagnes. MONTHLY_RECURRING se réinitialise chaque mois, DATE_RANGE s'applique entre startDate et endDate et NO_CAP le supprime ; la devise est celle du marketplace et ne s'envoie pas. Dans un PATCH, budget est remplacé en entier : envoyez le plafond complet que vous voulez, pas seulement le montant. Pour faire entrer ou sortir une campagne Sponsored Products d'un portefeuille, changez son portfolioId avec PATCH /v1/campaigns/{id}.
Deux codes à distinguer. Une entité qui n'existe pas, ou qui appartient à un autre compte, répond 404 — jamais 403, qui confirmerait son existence. Un refus d'Amazon répond 200 avec result: "failed" et le motif : l'appel est bien arrivé, c'est le changement qui a échoué.
Les trois ad products s'écrivent, mais pas de la même façon :
- Sponsored Brands et Sponsored Display se modifient et s'archivent avec les mêmes routes que Sponsored Products : état, budget, nom et enchères des campagnes, ad groups, targets et product ads. Ce qui n'est pas encore possible, c'est de les créer :
POST /v1/campaigns,/v1/campaigns/full,/v1/adgroupset/v1/product-adssont réservés à Sponsored Products. - Les ad groups Sponsored Brands n'ont pas d'enchère par défaut. Un changement de
defaultBidsur l'un d'eux est refusé avec un message qui l'explique. Ceux de Sponsored Display en ont une. - Les targets et targets négatifs se créent bien dans les ad groups SB et SD, avec
POST /v1/targets. LetargetTypeaccepté dépend de l'ad product de l'ad group (tableau ci-dessous). Au niveau de l'ad group uniquement : SB et SD n'ont pas de targets négatifs de campagne. - Epinium ne vérifie les limites d'enchère et de budget du marketplace que pour Sponsored Products, avant l'envoi. Pour Brands et Display, il n'applique pas de limites propres : c'est Amazon qui valide, et son motif revient dans la réponse, par entité avec
result: "failed"ou, à la création de targets, dansfailure_details, oùreferenceidentifie le target (mot-clé, ASIN, SKU ou l'id d'audience, de catégorie ou de localisation).
| Ad product | targetType acceptés |
|---|---|
| Sponsored Products | KEYWORD, PRODUCT, PRODUCT_CATEGORY |
| Sponsored Brands | Ceux de Sponsored Products plus THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND ou KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES) |
| Sponsored Display | KEYWORD ; PRODUCT par ASIN ou par sku, avec productMatchType PRODUCT_EXACT ou PRODUCT_SIMILAR ; PRODUCT_CATEGORY avec affinages (marque, prix, note, tranche d'âge, éligibilité Prime) ; THEME (INTERESTED_AUDIENCE) ; PRODUCT_AUDIENCE (ASIN + event PURCHASE ou VIEW + lookback de 7, 14, 30, 60, 90, 180 ou 365 jours) ; AUDIENCE (audienceId), CONTENT_CATEGORY (contentCategoryId) et LOCATION (locationId) |
Les ids de AUDIENCE, CONTENT_CATEGORY et LOCATION viennent de la console Amazon Ads : l'API ne les liste pas encore.
Configuration de l'optimisation
Avec la même permission campaigns:write, en plus d'écrire sur Amazon vous pouvez lire et changer la configuration qu'utilise l'optimiseur d'Epinium : ce qu'il poursuit sur chaque campagne. C'est une surface différente de la précédente, et il ne faut pas les confondre.
Elle ne part jamais vers Amazon. C'est une configuration propre à Epinium, consommée par l'optimiseur lors de son exécution de chaque nuit, pas une donnée du compte Amazon. C'est pourquoi deux règles d'« Écrire sur Amazon » ne s'appliquent pas ici : pas besoin d'en-tête Idempotency-Key - il n'y a aucun aller-retour vers Amazon qu'un nouvel essai pourrait dupliquer - et le changement ne laisse pas de ligne dans /v1/advertising-changes, qui n'enregistre que ce qui a été envoyé à Amazon.
Elle se lit avec expand, pas par défaut. GET /v1/campaigns et GET /v1/campaigns/{id} ne renvoient optimizationConfig que si vous demandez ?expand[]=optimizationConfig. C'est opt-in car très peu de campagnes ont cette configuration enregistrée : sans expand, la colonne reviendrait presque toujours à null.
Ce qui peut être fixé avec PATCH /v1/campaigns/{id}/optimization-config, en langage métier :
- L'objectif : un ACOS ou un ROAS cible, ou un objectif de volume - impressions ou commandes - accompagné d'un plafond d'ACOS.
- Les limites d'enchère : le plancher et le plafond qu'elle ne peut pas franchir, le plafond du multiplicateur de placement, et la dépense minimale avant de passer un target en négatif.
- Le budget mensuel que poursuit l'optimiseur - pas le budget quotidien de la campagne sur Amazon, qui se change avec
PATCH /v1/campaigns/{id}et qui est une donnée différente portant le même nom. - Les overrides de harvesting de la campagne : son niveau de découverte et si elle autorise le ciblage d'ASIN concurrents.
- Quels workflows l'optimisent.
Ce dernier point est celui qui compte vraiment : assigner des workflows est ce qui place la campagne sous optimisation, aucun autre champ de ce bloc. linkedWorkflowDefinitionIds la force à entrer - le workflow la traite chaque nuit même si son propre filtre ne l'aurait pas choisie - et c'est la voie par laquelle un workflow déplace de vraies enchères sur Amazon ; confirmez-le avec la personne avant de l'écrire, exactement comme pour activer une automatisation. Un workflow à sélection automatique peut aussi la récupérer de lui-même, et workflowsOptOut: true décline cette sélection automatique. Seul excludedWorkflowDefinitionIds la retire avec certitude : il gagne toujours, quoi que dise le reste.
aiEnabled n'est pas l'interrupteur de l'optimiseur
C'est le consentement du titulaire du compte, et il part vers Amazon comme le tag epinium:ai_enabled. Le mettre à false ne retire pas la campagne de l'optimisation : c'est le rôle d'excludedWorkflowDefinitionIds, ou de la retirer de linkedWorkflowDefinitionIds.
optimizeDate et optimizingSince sont en lecture seule - c'est l'optimiseur lui-même qui les tamponne - et écrire l'un ou l'autre répond par un 400.
POST /v1/campaigns/optimization-config/batch applique le même patch à jusqu'à 1000 campagnes, et ce n'est pas tout-ou-rien : il répond une ligne par campagne, dans l'ordre d'envoi, et chacune est validée contre son propre état enregistré - un plafond obligatoire pour un objectif peut être facultatif pour un autre - donc une ligne peut échouer sans affecter les autres.
Deux codes à distinguer, comme pour l'écriture sur Amazon : un refus de validation - un objectif hors plage, un workflow qui n'est pas le vôtre - répond 200 avec result: "failed" et le motif dans reason. Une campagne qui n'existe pas ou qui appartient à un autre compte répond 404 sur le PATCH individuel ; dans le lot, en revanche, cette même campagne revient comme une ligne failed avec reason: "not_found", précisément pour qu'une ligne en échec ne fasse pas couler les 999 autres.
| Route | Ce qu'elle fait |
|---|---|
PATCH /v1/campaigns/{id}/optimization-config | Changer la configuration d'optimisation d'une campagne |
POST /v1/campaigns/optimization-config/batch | La même configuration sur jusqu'à 1000 campagnes, une ligne par résultat |
Écrire des tâches
Avec la permission tasks:write, l'API crée des tâches et décide de leurs suggestions, comme vous le faites dans Processus → Tâches. C'est la pièce qui permet à un assistant ou à une intégration de proposer des changements et à une personne de les examiner avant qu'ils n'arrivent sur Amazon.
Quatre choses à savoir avant le premier appel :
- Approuver n'applique pas. Il y a deux étapes : approuver ou rejeter chaque suggestion, puis
POST /v1/tasks/{id}/apply. À ce moment-là, les changements de campagne — budget quotidien, état et nom — partent vers Amazon immédiatement, et la réponse indique lesquels sont passés (applied) et lesquels ont été refusés (failed). Ceux de produit sont mis en file d'attente (enqueued) et appliqués en arrière-plan : pour savoir s'ils sont passés, relisez les suggestions et regardezappliedAtetapplyError. - Une suggestion que rien ne sait appliquer est une note. Aujourd'hui, on applique les suggestions de produit et celles de campagne qui portent un
fieldPath; celles qui n'en ont pas, et celles d'ad groups, targets, product ads et termes de recherche, restent des notes. Les approuver garde une trace de la décision et ne change rien, et la réponse l'indique avecautoApplySkipped: true. Ce n'est pas une erreur. En revanche, à la création, une suggestion de campagne avec un champ autre quedailyBudget,stateouname, ou avec une valeur qui ne peut pas être appliquée, est refusée avec un400: l'enregistrer reviendrait à promettre un changement que personne ne fera. - Les suggestions viennent avec la tâche. Jusqu'à 50 dans
itemsà la création, chacune pointant vers une entité de votre compte ; on ne peut pas en ajouter ensuite. Une entité qui n'existe pas ou qui appartient à un autre compte fait refuser la tâche entière, sans rien créer. - Résoudre une tâche est définitif. Ses suggestions en attente ne sont pas résolues avec elle : elles restent figées et ne peuvent plus être approuvées. Décidez d'abord celles qui vous importent et clôturez la tâche ensuite. La résoudre ne relance pas non plus de workflow.
| Route | Ce qu'elle fait |
|---|---|
POST /v1/tasks | Créer une tâche, avec ses suggestions |
PATCH /v1/tasks/{id} | Titre, description, priorité et date d'expiration |
POST /v1/tasks/{id}/resolve | La résoudre ou l'écarter |
PATCH /v1/task-items/{id} · POST /v1/task-items/batch | Approuver ou rejeter des suggestions, éventuellement avec votre propre valeur dans appliedValue |
POST /v1/tasks/{id}/apply | Appliquer ce qui a été approuvé |
POST /v1/tasks/listing-optimizations | Demander à l'IA d'Epinium de réécrire des fiches, sous forme de suggestions d'une tâche - expliqué dans Réécrire des fiches avec l'IA d'Epinium |
Comme sur Amazon, toute écriture exige Idempotency-Key, et le lot de suggestions n'est pas tout-ou-rien : il répond une ligne par suggestion et applied compte celles qui ont été enregistrées. Créer, modifier ou résoudre une tâche coûte un montant fixe par appel ; approuver ou rejeter est facturé par suggestion enregistrée. Appliquer n'est pas facturé à part : chaque suggestion a déjà été facturée lors de son approbation.
Réécrire des fiches avec l'IA d'Epinium
Avec la permission tasks:write, POST /v1/tasks/listing-optimizations demande à l'IA d'Epinium de réécrire le titre (avec ses points forts, les Item Highlights), les puces, la description et les termes de recherche de 1 à 20 produits de votre catalogue. C'est la même génération que dans l'application : elle suit les clusters de mots-clés de chaque produit, les prompts qui leur sont liés et votre identité de marque. Le résultat ne modifie aucune fiche : il reste sous forme de suggestions dans une tâche, celle de l'onboarding, pour qu'une personne les vérifie.
Cinq choses à savoir avant le premier appel :
- Elle répond tout de suite et génère ensuite. La réponse est un
202avec l'id de la tâche (task) et ce qui reste du plafond (limit). Chaque suggestion apparaît dans la tâche quand elle est prête : lisez-les dans/v1/task-itemsen filtrant partask. - Rien n'arrive sur Amazon sans passer par vous. Vous approuvez ou rejetez chaque suggestion et vous appliquez la tâche (
POST /v1/tasks/{id}/apply), comme n'importe quelle autre. Appliquer laisse les modifications en attente de publication : elles arrivent sur Amazon quand vous les publiez, depuis l'application ou avecPOST /v1/pending-listing-changes/publish, qui demandecatalog:publish. - Elle ne consomme pas vos crédits, mais elle a un plafond. C'est Epinium qui paie la réécriture, jusqu'à 20 produits par compte au total. Chaque produit de chaque appel compte, y compris celui que vous relancez ou dont la génération échoue. Un appel qui demande plus de produits qu'il ne vous en reste est rejeté en entier avec un
403dont lecodeestlisting_optimization_limit_reached, sans rien générer ;limit(cap,used,remaining) indique dans chaque réponse combien il vous en reste. Approuver ou rejeter les suggestions est facturé comme dans n'importe quelle tâche. - Vous choisissez les produits et les champs.
productssont des ids de produits du catalogue, Seller ou Vendor (/v1/products; ceux de publicité ne sont pas acceptés).fieldsacceptetitle,bullets,descriptionetsearch_terms; sans lui, les quatre sont réécrits.titleréécrit aussi les points forts. - Elle exige
Idempotency-Key. Réutilisez la même clé en cas de nouvel essai, sinon vous consommeriez à nouveau des produits du plafond.
Écrire des clusters de mots-clés
Avec la permission catalog:write, l'API crée et modifie vos clusters de mots-clés, les mêmes que vous gérez dans Segmentation → Clusters : un groupe de produits nommé, avec les mots-clés positifs sur lesquels ils devraient se positionner ou être annoncés et les mots-clés négatifs dont il faut s'éloigner. C'est le moyen pour un assistant qui a trouvé un trou de mots-clés de le laisser enregistré là où les prompts SEO d'Epinium, la découverte de mots-clés de l'optimiseur et le filtre par cluster des graphiques produit le reprendront.
Quatre choses à savoir avant votre premier appel :
- Rien n'arrive sur Amazon. Un cluster vit dans Epinium. C'est pourquoi ces écritures ne laissent aucune ligne dans
/v1/advertising-changes, et pourquoi votre client d'IA ne vous demandera pas de les confirmer. - On modifie par deltas, pas par remplacement.
PATCH /v1/clusters/{id}accepteaddPositiveKeywords,removePositiveKeywords,addNegativeKeywords,removeNegativeKeywords,addProducts,removeProducts,addPrompts,removePromptsetname; n'envoyez que ce qui change. Ajouter un mot-clé déjà présent met à jour sa langue, son score et son usage, apparié par son texte ; retirer un mot-clé absent ne fait rien. Un cluster admet jusqu'à 100 mots-clés positifs et 50 négatifs, comptés après le changement, et un mot-clé ne peut pas être positif et négatif à la fois. - Les mots-clés suivent les règles de l'application. En minuscules, jusqu'à 80 caractères, le jeu de caractères d'Amazon, sans
-ni.au début ni-,+ou.à la fin ; les doublons sont fusionnés.languageest un code commees-ESouen-GB,epiniumScoreva de 1 à 5 etpurposevautSEO,PPCou les deux (les deux par défaut). - Un cluster protégé est refusé avec
409. Protéger un cluster depuis l'application est la décision d'une personne, et cette API ne peut pas la défaire : déprotégez-le d'abord dans Segmentation → Clusters. Le champprotectedde la réponse vous le dit avant d'essayer.
| Route | Ce qu'elle fait |
|---|---|
POST /v1/clusters | Créer un cluster, avec ses mots-clés, ses produits et ses prompts si vous les avez déjà |
PATCH /v1/clusters/{id} | Ajouter ou retirer des mots-clés, des produits et des prompts, ou le renommer |
DELETE /v1/clusters/{id} | Le supprimer, sans retour possible |
Chaque prompt que vous liez doit appartenir à votre compte, sinon l'appel est refusé avec un 400 qui nomme les ids en trop. Chaque produit que vous liez doit appartenir à votre compte — pour une agence, aux connexions que le compte vous a partagées — et être un produit de catalogue (type seller ou vendor dans /v1/products ; les produits publicitaires sont refusés), sinon l'appel entier est refusé avec un 400 qui nomme les ids en trop, sans rien écrire. Le cluster appartient à la personne derrière l'identifiant, et apparaît donc dans le tableau de l'application à son nom. La suppression est définitive - il n'y a pas de corbeille - et elle est refusée avec un 409 tant que le cluster est protégé ou qu'une smart campaign l'utilise comme cluster de base ; l'erreur nomme ces smart campaigns, qu'il faut modifier ou supprimer d'abord. Chaque écriture coûte un montant fixe par appel, et le quota de clusters du plan s'applique ici comme dans l'application.
Écrire des prompts personnalisés
Avec la permission catalog:write, l'API crée et modifie vos prompts personnalisés, ceux de votre bibliothèque de prompts : des instructions nommées que l'IA d'Epinium suit lorsqu'elle rédige le contenu de vos fiches -ton, structure, mots à employer ou à éviter-. Les lire ne demande que catalog:read, dans /v1/prompts, et chaque cluster renvoie dans prompts les ids des siens ; avec expand[]=prompts, il les renvoie en entier.
Quatre choses à savoir avant votre premier appel :
- Un prompt ne change rien à lui seul. Il ne touche pas Amazon et ne réécrit aucune fiche quand il est enregistré : il s'applique lorsque le contenu des produits des clusters auxquels vous le liez est généré (
addPromptsdansPATCH /v1/clusters/{id}). Si plusieurs prompts des clusters d'un produit valent pour le même champ, un seul est utilisé : laissez donc un prompt par champ. fieldsindique à quels champs de la fiche il s'applique :titleAndHighlights(le titre et les points forts de l'article, rédigés ensemble),product_description,bullet_pointougeneric_keyword(les termes de recherche). Sansfields, ou avec[], il vaut pour tous. Un prompt ancien peut encore porteritem_name, le titre seul, qui se lit mais n'est plus accepté en écriture.- L'instruction a un plafond : jusqu'à 2 000 caractères, comme dans l'application. Le nom en demande au moins 3.
- En modification, ce que vous envoyez remplace ce qu'il y avait :
PATCH /v1/prompts/{id}acceptename,instructionetfields, etfieldsremplace la liste entière.
| Route | Ce qu'elle fait |
|---|---|
POST /v1/prompts | Créer un prompt |
PATCH /v1/prompts/{id} | Le renommer ou changer son instruction ou ses champs |
Le prompt appartient à la personne derrière l'identifiant. La suppression de prompts n'est pas disponible par l'API. Chaque écriture coûte un montant fixe par appel, et le quota de prompts du plan s'applique ici comme dans l'application : si vous l'avez déjà atteint, la création répond 403.
Écrire votre identité de marque
Avec la permission catalog:write, l'API crée et modifie votre identité de marque, celle de Paramètres → Marque : le nom de la marque, son secteur, ses sites web, ceux de vos concurrents, vos observations (ton, public, mots à utiliser ou à éviter) et les marques de votre catalogue qu'elle couvre. C'est le contexte que l'IA d'Epinium utilise pour rédiger vos fiches. La lire ne demande que catalog:read, dans /v1/brand-identities. Ce ne sont pas les marques de votre catalogue, qui se trouvent dans /v1/product-brands.
En plus des sites web isolés de competitor_urls, chaque concurrent peut avoir sa fiche dans competitors, jusqu'à 50 :
| Champ | Ce que c'est |
|---|---|
name | Nom de la marque ou du vendeur. Obligatoire |
url | Son site web ou sa boutique Amazon |
asins | Les ASIN de ses produits qui concurrencent les vôtres, jusqu'à 20 |
threat | Sa dangerosité : level (low, medium ou high) et reason, le motif observé dans les données. Le niveau ne va jamais sans son motif ; s'il n'y a pas encore de preuves, on le laisse de côté |
price_position | Son prix par rapport au vôtre : below, similar ou above |
Quatre choses à savoir avant le premier appel :
- Les fiches de concurrents ne s'affichent pas encore dans l'application. Elles s'enregistrent et se lisent par l'API et le MCP ; Paramètres → Marque ne les affiche pas encore.
- En modification, une liste remplace celle qui existait.
PATCH /v1/brand-identities/{id}ne change que les champs que vous envoyez, maiscompetitors,competitor_urls,brand_urlsetproduct_brand_idssont remplacées en entier : pour ajouter un concurrent, envoyez ceux que vous aviez plus le nouveau. Les valeurs précédentes ne sont conservées nulle part. - Les fiches ne remplacent pas
competitor_urls. Ce sont deux listes indépendantes, et les sites web que vous aviez déjà sont conservés. Une identité enregistrée avant l'existence des fiches acompetitorsvide. - Rien n'arrive sur Amazon. L'identité de marque vit dans Epinium : l'enregistrer ne touche ni ne réécrit vos fiches. Par l'API, on ne peut ni la supprimer ni téléverser son logo.
| Route | Ce qu'elle fait |
|---|---|
POST /v1/brand-identities | Créer une identité de marque |
PATCH /v1/brand-identities/{id} | Modifier ses champs ou ses listes |
Comme toute écriture, elle exige Idempotency-Key.
Modifier des listings depuis un fichier
Avec la permission catalog:write, l'API enregistre des modifications d'attributs sur de nombreuses fiches Amazon à la fois, à partir d'un fichier Excel ou CSV : n'importe quel attribut qu'Amazon permet de modifier pour le type de produit de chaque fiche, en Seller comme en Vendor. C'est ce qu'utilise le MCP Epinium, qui décrit le parcours complet du point de vue de la personne qui fait la demande.
| Route | Permission | Ce qu'elle fait |
|---|---|---|
POST /v1/listing-files | catalog:read | Importe le fichier (.xlsx, .xls ou .csv) et renvoie son file_id. Il est conservé 7 jours |
POST /v1/listing-files/rows | catalog:write | Enregistre comme fichier des en-têtes et des lignes que vous avez déjà, sans rien importer |
POST /v1/listing-updates/prepare | catalog:read | Retrouve les produits du fichier par SKU, ASIN ou EAN et indique quels attributs ils acceptent |
POST /v1/listing-updates/validate | catalog:read | Valide les lignes avec les règles d'Amazon de chaque type de produit, sans rien enregistrer |
POST /v1/listing-updates/apply | catalog:write | Enregistre les lignes valides comme modifications en attente de publication, en arrière-plan |
GET /v1/listing-updates/apply/{file_id} | catalog:read | L'état de cet enregistrement, ce qui a été envoyé et ce que cela a coûté |
Cinq choses à savoir avant votre premier appel :
- Rien n'arrive sur Amazon à l'enregistrement.
applylaisse les modifications en attente de publication, et elles partent vers Amazon quand quelqu'un les publie depuis Publier les modifications dans Epinium ou avecPOST /v1/pending-listing-changes/publish(voir Créer de nouvelles offres sur Amazon). - Les données qui vont ensemble demandent une personne. Une valeur qui oblige à en renseigner d'autres, comme les piles, n'est enregistrée que si son
cascade_idfigure dansconfirmed_cascades; sinon, elle part dans une tâche pour être révisée. Le reste de la ligne est enregistré quand même. - La facturation est de 5 crédits par ligne. À l'acceptation du fichier, 5 crédits par ligne sont réservés, avec un
402si le solde ne suffit pas. À la fin, seules les lignes envoyées sont facturées et le reste est restitué, en totalité en cas d'échec. Envoyer, préparer, valider et consulter l'état ne sont pas facturés. - Les prix vont par audience. Une colonne se déclare avec
offer: { audience, field }(field:price,min,max,sale_price,sale_startousale_end) ;clear: truefait que ses cellules vides effacent, etdate_order(dmyoumdy) fixe l'ordre de dates ambiguës.validaterenvoie dansoffer_clearsles colonnes de prix avec des cellules vides sur des produits qui ont cette valeur, et les règles de prix comme problèmes bloquantsoffer_*. Côté Vendor, aucun prix ne se modifie : ces colonnes reviennent dansnot_applicableavec le motifvendor_price.preparepropose les champs de prix dansoffer_fields. - Un fichier ne s'applique qu'une fois. Répéter l'appel avec les mêmes réglages renvoie l'état ; avec d'autres réglages, ou avec un fichier qui expire dans moins de 24 heures, il répond
409. Comme toute écriture, il exigeIdempotency-Key.
Les paramètres de chaque route se trouvent dans la référence du catalogue.
Créer de nouvelles offres sur Amazon
Avec la permission catalog:write, l'API enregistre des nouvelles offres : des produits qui ne sont pas encore dans votre compte Amazon. Il peut s'agir d'une offre sur un ASIN qui existe déjà (en Seller uniquement), d'un nouveau produit ou d'une famille de variations, en Seller comme en Vendor. Ce qu'est chacune, ce que demande Amazon et comment se publie une famille se trouvent dans Nouvelles offres de produits sur Amazon.
| Route | Permission | Ce qu'elle fait |
|---|---|---|
GET /v1/amazon-catalog/search | catalog:read | Recherche un produit dans le catalogue d'Amazon par ASIN, EAN, UPC ou GTIN, avec ses restrictions pour votre compte |
GET /v1/amazon-product-types/search | catalog:read | Recommande des types de produit à partir du nom d'un nouveau produit |
GET /v1/amazon-shipping-templates | catalog:read | Les modèles d'expédition de votre compte Seller, pour une offre que vous expédiez vous-même |
POST /v1/listing-drafts/validate | catalog:read | Valide la nouvelle offre avec les règles d'Amazon et avec une prévisualisation d'Amazon, sans rien enregistrer |
POST /v1/listing-drafts | catalog:write | Enregistre la nouvelle offre en attente de publication |
GET /v1/listing-drafts | catalog:read | Vos nouvelles offres et leur état, avec ce qu'Amazon a répondu |
DELETE /v1/listing-drafts/{id} | catalog:write | Écarte une nouvelle offre en attente |
GET /v1/pending-listing-changes | catalog:read | Ce qui est en attente de publication, comme dans Publier les modifications |
POST /v1/pending-listing-changes/publish | catalog:write et catalog:publish | Publie sur Amazon les modifications et les nouvelles offres choisies, par le même chemin que le bouton Publier de l'application |
Quatre choses à savoir avant votre premier appel :
- Enregistrer ne publie pas. La nouvelle offre reste en attente jusqu'à ce qu'elle soit publiée depuis l'application ou avec
publish, qui exige en pluscatalog:publishet ne peut pas être annulé. - Le SKU doit être nouveau sur cette marketplace (en Vendor, sous ce vendor code) : un SKU qui existe déjà, dans Epinium ou sur Amazon, répond
409. - L'enregistrement interroge à nouveau Amazon et répond
400, avec ce qui manque, si Amazon devait rejeter la nouvelle offre : validez d'abord. - La validation (1 crédit) et l'enregistrement (5) sont facturés. La recherche, les modèles d'expédition, la liste, l'écart et la publication ne sont pas facturés. Comme toute écriture, l'enregistrement et la publication exigent
Idempotency-Key.
Les paramètres de chaque route se trouvent dans la référence du catalogue.
Écrire le coût d'un produit
Avec la permission propre costs:write -pas catalog:write, qui est pour les clusters, les prompts et les listings- l'API crée ou met à jour le coût unitaire et le coût d'expédition d'un produit : la même action que vous faites sur la fiche du produit ou en important le modèle CSV de coûts, avec la même sémantique. Pour de nombreux produits à la fois, utilisez l'import.
| Route | Ce qu'elle fait |
|---|---|
POST /v1/products/{id}/costs | Crée ou met à jour le coût unitaire (price) et le coût d'expédition (shipping_cost) d'un produit |
Quatre choses à savoir avant le premier appel :
- La sémantique est celle du CSV. Un champ vide ne touche pas la valeur : si vous n'envoyez que
price, le coût d'expédition déjà présent reste inchangé. Un0le met vraiment à zéro -ce qui n'est pas pareil que de ne pas envoyer le champ. Au moins l'un des deux,priceoushipping_cost, est obligatoire. - Une date passée recalcule l'historique.
datevaut aujourd'hui par défaut ; si vous envoyez une date antérieure, le nouveau coût s'applique depuis cette date et le P&L des périodes déjà closes après elle se recalcule tout seul. La réponse indique ce qui s'est passé dansrecalculation:not_neededavec la date du jour,queuedsi le recalcul a été mis en file d'attente, oufaileds'il n'a pas pu l'être -le coût est enregistré quand même, c'est seulement le P&L qui mettra du temps à le refléter. - Uniquement sur les plans qui incluent le coût produit. En Free et Guru, cette route répond avec un
403, comme toute autre écriture sur ces plans. Comme toute écriture, elle exigeIdempotency-Key. - Un produit avec des achats n'accepte pas
price. Son coût du produit est calculé par les achats enregistrés, donc la route répond409avec le codeCOST_FROM_PURCHASES. Pour modifier seulement son expédition, envoyezshipping_costseul, sansprice: avec les deux, tout est rejeté et l'expédition n'est pas enregistrée. Pour changer son coût produit, enregistrez ou corrigez un achat (Enregistrer les achats d'un produit).
Enregistrer les achats d'un produit
Quand un produit a des achats, son coût produit est le coût moyen de son stock : chaque achat le recalcule avec les unités que vous aviez et celles que vous achetez. C'est la même chose que Enregistrer des achats sur la fiche du produit, avec le même calcul. Lire demande catalog:read ; enregistrer, corriger et supprimer, costs:write. Les deux, uniquement sur les plans qui incluent le coût produit.
| Route | Ce qu'elle fait |
|---|---|
GET /v1/products/{id}/purchases | Les achats du produit, avec le coût moyen laissé par chacun |
GET /v1/products/{id}/stock-group | Avec quels produits il partage son stock, ou avec lesquels il serait regroupé lors de son premier achat |
GET /v1/purchases | Vos achats, par compte et par dates |
GET /v1/purchases/{id} | Un achat |
POST /v1/products/{id}/purchases | Enregistre un achat |
PATCH /v1/purchases/{id} | Corrige un achat : envoyez seulement ce qui change |
DELETE /v1/purchases/{id} | Supprime un achat |
- Le stock partagé a un seul coût. En paneuropéen, le même SKU dans les pays de l'UE est le même stock, donc un achat change le coût de tous ces pays (le Royaume-Uni et Vendor sont à part). Le groupe naît avec le premier achat ; si ces pays ont aujourd'hui des coûts différents, cet achat demande
prior_stock_unit_cost, ce que valait le stock déjà présent, ou répond400avecPRIOR_STOCK_VALUE_REQUIRED. - Le stock avant l'achat. Sans
stock_on_hand, on prend le dernier stock Amazon FBA des 7 jours précédents, plus les achats enregistrés depuis. En FBM, il est obligatoire. - Le numéro de commande ne se répète pas. Avec
reference, renvoyer le même achat répond409avecDUPLICATE_PURCHASE_EXTERNAL_IDau lieu de le dupliquer. - Corriger ou supprimer recalcule. Cela change le coût moyen de cet achat et des suivants, ainsi que le P&L des périodes déjà closes, comme un coût avec une date passée. Une suppression ne s'annule pas ; si c'était le dernier achat du groupe, les coûts d'avant s'appliquent de nouveau.
- Avec plusieurs comptes, lire en demande un et écrire les demande tous. Si le stock est partagé par des comptes que la clé n'atteint pas, vous pouvez lire leurs achats mais pas les modifier :
400avecSTOCK_GROUP_OUT_OF_SCOPEà l'enregistrement,404à la correction ou à la suppression. - Chaque écriture coûte autant qu'écrire un coût, et comme toute écriture elle exige
Idempotency-Key.
Importer les coûts de nombreux produits
Pour charger le coût de votre catalogue, utilisez l'import : c'est le même que Importer des coûts depuis un fichier dans l'app, avec le même modèle et les mêmes règles, et il ne recalcule le P&L qu'une seule fois, à la fin. Avec la même permission costs:write.
Ne le faites pas produit par produit avec POST /v1/products/{id}/costs : chaque coût avec une date passée recalcule le P&L de tout le compte, et pendant ce temps l'API rejette les suivants avec un 409.
| Route | Ce qu'elle fait |
|---|---|
POST /v1/cost-imports/files | Téléverse le fichier de coûts et renvoie son file_id, sans rien importer. Il est conservé 7 jours. GET liste ceux que vous avez téléversés |
POST /v1/cost-imports/preview | Vérifie l'import sans rien enregistrer : quelles lignes s'appliqueraient, lesquelles non et pourquoi, combien sont sans date, combien ne compteront que jusqu'à un coût ultérieur que le produit a déjà et ce que cela coûterait |
POST /v1/cost-imports | Importe les coûts des produits d'un compte, depuis des fichiers téléversés ou depuis des lignes |
GET /v1/cost-imports/{id} | L'état de l'import : combien de lignes ont été appliquées, combien ne changeaient rien et combien ont été rejetées, avec le motif de chacune |
Ce qu'il faut savoir :
- Les lignes arrivent de deux façons. Avec
file_ids, les fichiers que vous avez téléversés avecPOST /v1/cost-imports/files(.xlsx,.xlsou.csv, jusqu'à 8 Mo et 200 000 lignes par import : un catalogue entier tient dans un fichier ; un Excel avec beaucoup de colonnes peut ne pas passer, il faut alors supprimer les colonnes en trop ou le téléverser en CSV). Les fichiers téléversés pour des modifications de listings ne sont pas acceptés ici. Ou avecheadersetrows, jusqu'à 5 000 lignes, si vous n'avez téléversé aucun fichier. - Les colonnes sont celles du modèle (
sellerSku,marketplace,date,cogs,cogsCurrency,shippingCostetshippingCostCurrency) et elles sont reconnues comme dans l'app, aussi avec des noms courants comme « sku », « cost » ou « date ». Si l'une n'est pas reconnue, indiquez de quel en-tête vient chaque donnée aveccolumns. Chaque ligne suit les règles du fichier de l'app. - Vérifiez-le avant, gratuitement.
POST /v1/cost-imports/previewreçoit le même corps et applique les mêmes règles ligne par ligne, y compris le rapprochement avec votre catalogue, mais n'enregistre et ne facture rien. Il vous dit combien de lignes s'appliqueraient, seraient ignorées (vides, ou avec le même coût que le produit avait déjà à leur date :unchanged) ou rejetées, avec le motif et des exemples, combien seraient sans date et combien de crédits cela coûterait. Ce n'est qu'à l'application qu'une ligne peut encore être rejetée, s'il n'y a pas de taux de change pour sa devise à sa date. - Une ligne sans date s'applique à partir d'aujourd'hui. Si vos lignes n'ont pas de date, passez dans
datele jour à partir duquel les coûts s'appliquent : il s'applique aux lignes sans date, et celles qui en ont une gardent la leur. - Les produits parents de variation sont rejetés avec
parent_product: ils ne se vendent pas, leur coût ne couvrirait donc aucune vente. Le coût va sur leurs variations. - C'est asynchrone. Elle répond
202avecstatus: "processing". InterrogezGET /v1/cost-imports/{id}jusqu'à obtenirfinished,finished_with_errorsouerror; l'interroger ne coûte rien. Les lignes avec une cellule plus longue que ce qu'admet le modèle reviennent dansnot_sentet ne sont pas importées. - Il reste dans l'historique de l'app, dans l'Historique de l'import de coûts de ce compte, comme si vous l'aviez téléversé depuis l'app.
- Un compte par import. Tant que le P&L de ce compte est en cours de recalcul à cause d'un changement de coût antérieur, elle répond
409sans rien importer : attendez la fin et relancez-le. - Chaque ligne appliquée coûte autant qu'écrire le coût d'un produit. À la création, les lignes qui peuvent s'appliquer sont réservées et, si votre solde ne suffit pas, il répond
402sans rien importer. À la fin, seules les lignes appliquées sont facturées et le reste est rendu : les lignes rejetées et celles qui ne changeaient rien ne coûtent rien. Uniquement sur les plans qui incluent le coût produit, et il exigeIdempotency-Key. - Les achats aussi. Avec
kind: "purchases", il importe des achats avec le modèle d'achats de l'app (sellerSku,marketplace,date,units,currency,productCost,inboundShippingCost,tariffCost,otherCost,stockOnHand,reference), uniquement sur les comptes Seller. La vérification des achats ne contrôle que le format de chaque ligne (checks: "format") et rejette déjà les lignes mal formées : le SKU, son groupe de stock et le stock sont contrôlés à l'application, donc quelques lignes de plus peuvent être rejetées à ce moment-là. Chaque achat appliqué coûte autant que de l'enregistrer seul.
Écrire des dépenses propres
Vos dépenses propres (personnel, agence, 3PL, logiciels…) se lisent avec catalog:read et s'écrivent avec la même permission costs:write que le coût produit. Ce sont les mêmes que celles que vous créez dans Coûts et dépenses → Dépenses propres, et le P&L les déduit jusqu'au bénéfice net.
| Route | Ce qu'elle fait |
|---|---|
GET /v1/expenses | Vos dépenses, filtrables par basis, status (active, upcoming ou ended) et category |
GET /v1/expenses/{id} | Une dépense, avec l'historique de ses montants par mois |
POST /v1/expenses | Crée une dépense |
POST /v1/expenses/batch | Crée jusqu'à 100 dépenses d'un coup, depuis une liste ou une feuille importée (file_id), ou les vérifie sans rien créer |
POST /v1/expenses/files | Importe une feuille de dépenses et renvoie son file_id, sans rien créer. Conservée 7 jours. GET liste celles que vous avez importées |
PATCH /v1/expenses/{id} | Change le libellé ou la catégorie, ou la termine avec valid_to (null la rouvre). La terminer supprime les changements de montant prévus après ce mois, et la rouvrir ne les récupère pas |
POST /v1/expenses/{id}/amounts | Change le montant à partir d'un mois ; les mois précédents gardent le leur |
DELETE /v1/expenses/{id} | La supprime de tout l'historique |
GET /v1/expense-categories | Les catégories standard et les vôtres |
POST, PATCH et DELETE /v1/expense-categories | Crée, renomme ou supprime une de vos catégories. Une catégorie utilisée par une dépense ne peut pas être supprimée |
basis indique comment se calcule chaque dépense : fixed (un montant fixe, avec frequency monthly, quarterly, yearly ou once et, dans ce dernier cas, spread_months 1, 3, 6 ou 12), per_unit (par unité vendue nette), pct_net_sales ou pct_ad_spend (en points : 5 vaut 5 %). Les trois variables acceptent scope pour ne s'appliquer qu'à certaines connexions ou certains pays.
Cinq choses à savoir avant le premier appel :
- Pour plus d'une dépense, le lot.
POST /v1/expenses/batchen crée jusqu'à 100 d'un coup.dry_runest obligatoire : envoyez-le d'abord avectrue, qui n'écrit rien et ne consomme pas de crédits, puis avecfalse. C'est tout ou rien : si une dépense échoue, aucune n'est créée, etfailure_detailsdit lesquelles et pourquoi.possible_duplicatessignale celles qui ressemblent à une dépense que vous avez déjà ou à une autre du même lot, sans les bloquer. Seules les dépenses créées sont facturées. - Une feuille de dépenses, en fichier. Importez-la avec
POST /v1/expenses/files(.xlsx,.xlsou.csv, jusqu'à 8 Mo et 1 000 lignes) et envoyez sonfile_idau lot : elle est lue avec les mêmes règles que l'import de l'application. Si ses colonnes ne s'appellent pas comme celles du modèle, indiquez d'où vient chaque donnée aveccolumns, et passez danstypeetcurrencyle type et la devise des lignes qui n'en ont pas. Une ligne illisible revient dansfailure_detailscommerow N, et alors rien n'est créé. - Le P&L les déduit immédiatement. Les dépenses sont calculées à la lecture du P&L : une création, une modification ou une suppression apparaît dès la requête suivante, y compris sur les mois déjà passés.
- Chaque token touche les dépenses de ses connexions. Un token qui n'atteint pas toutes les connexions de vente du compte ne voit et ne modifie que les dépenses des siennes, et ne peut pas créer de dépenses de tout le compte (les fixes et les variables sans connexions dans
scope) ni renommer ou supprimer des catégories : il répond403, et dans le lot cette ligne revient dansfailure_details. Une dépense qu'il ne peut pas voir répond404. - Uniquement sur les plans qui incluent le coût produit. En Free et Guru, ces routes répondent
403, y compris l'envoi du fichier. Toutes les écritures, sauf l'envoi du fichier, exigentIdempotency-Key.
Limites
- Les métriques exigent une plage de dates.
start_dateetend_datesont obligatoires sur toutes les ressources de métriques. - La plage a un maximum, et il dépend de la granularité. Avec
granularity=daily, 93 jours ; avectotalou avec les périodes calendaires (weekly,monthly,quarterly,yearly), 366. Sur les targets et les termes de recherche, les ressources les plus lourdes, cela descend à 31 et 93. Demander davantage renvoie une erreur indiquant la limite exacte. Les deux dates sont incluses dans la plage. - Les listings se paginent de deux façons. Les ressources de catalogue et de structure utilisent un curseur (
starting_after) ; celles de métriques utilisentlimitetoffset. Dans les deux cas,has_moreindique s'il reste une page. - Il existe une limite de requêtes par token. Si vous la dépassez vous recevez un
429et il suffit de réessayer plus lentement. - Il existe aussi une limite de requêtes simultanées. Un
429peut signifier « trop à la fois », pas seulement « trop par minute » ; un503signifie que le serveur est momentanément saturé. Les deux comportentRetry-Afteret les deux sont transitoires : réessayez avec moins de requêtes en parallèle. - Une réponse ne peut pas étendre plus de 5 000 objets.
expandsur des listes — les produits d'un cluster, les pays d'une connexion — se multiplie à chaque niveau. Au-delà, vous recevez un400indiquant combien d'objets auraient été renvoyés : baissezlimit, retirez unexpand, ou demandez ces données à leur propre endpoint.
Crédits
Les appels à cette API consomment des crédits de votre compte. Le coût de chaque ressource est visible dans l'application, sous Configuration → Crédits.
Chaque réponse vous indique ce que vous avez dépensé :
| En-tête | Ce que c'est |
|---|---|
X-Epinium-Credits-Cost | Ce qu'a coûté cet appel |
X-Epinium-Credits-Remaining | Ce qu'il vous reste. C'est approximatif : si d'autres traitements consomment en même temps, l'écart est possible |
X-Epinium-Credits-Breakdown | Le détail, par ressource et prix unitaire : product=100x1,country=100x0 |
X-Epinium-Credits-Max | Le maximum que l'appel pouvait coûter, calculé avant de l'exécuter |
Trois choses à savoir :
- Vous ne payez que ce qui est livré. Un appel qui échoue ne consomme rien, et un
expandqui ne renvoie aucune donnée — parce que votre token n'a pas ce scope, ou que l'enregistrement appartient à un autre compte — non plus. - Dans les métriques, la plage de dates coûte aussi, pas seulement les lignes. Demander une année avec
limit=1n'est pas économique : en plus de chaque ligne renvoyée, vous payez chaque jour de la plage, car c'est ce qu'il faut lire pour répondre, avec un minimum de 3 jours par appel. Pour dépenser moins, raccourcissez la plage. - Pour un total,
group_byplutôt que paginer. Un total de compte tient en peu de lignes (une par devise), alors que paginer le catalogue pour en faire la somme fait payer chaque produit à chaque page. Sur un compte réel, le total des ventes d'un mois coûte 157 crédits avecgroup_by=accountet environ 17 600 en paginant.
Si vos crédits ne suffisent pas, vous recevez un 402 avant l'exécution de l'appel : vous ne vous retrouverez jamais avec une demi-réponse. Et il ne dit pas seulement non, il dit quoi changer et à quelle valeur :
{
"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 est le même remède en version lisible par machine : limit, end_date ou include_total. S'il est absent, aucun paramètre ne permet de faire passer l'appel et il faut recharger.
Paramètres et réponses de chaque endpoint
Le tableau ci-dessus indique quelles ressources existent. Pour voir les paramètres d'entrée et la forme exacte de chaque réponse, il y a deux chemins :
- Référence navigable — chaque endpoint avec ses paramètres, leurs types et un exemple de réponse. Générée depuis l'API elle-même, elle ne peut donc pas devenir obsolète. En anglais.
- Schéma OpenAPI — le document OpenAPI 3.0 brut, à importer dans Postman, Insomnia ou un générateur de clients. Aucun token nécessaire.