Epinium API
Access: Settings → API Keys
Epinium exposes your data through a REST API so you can read it from your own tools: a custom dashboard, an analysis script or an AI assistant. It is the same information you see in the app, with the same figures.
The API reads your data and writes to Amazon and to your stores: it queries catalogue, campaigns and metrics, your P&L with product cost, and what is inside your Shopify and WooCommerce stores; it creates and edits Sponsored Products campaigns and edits Sponsored Brands and Display ones; it creates and edits portfolios; it creates, edits, clones and runs workflows; it creates, resolves and applies tasks; it creates or updates your products' cost and records their purchases from suppliers; it saves changes to any attribute of your Amazon listings and creates new listings for offers, new products and variation families; and it creates, edits and deletes products and content in your connected Shopify and WooCommerce stores. In your Amazon catalogue, what you save stays pending and only reaches Amazon when it is published, from the app or from the API with its own permission; your stores' catalogue changes directly, without staying pending. Each area has its own permission, and you grant the write ones when you create the key.
Looking to use it from an AI assistant?
You do not need to write any code. The Epinium MCP connects this same data to Claude and other compatible assistants.
Generate a token
- Go to Settings → API Keys
- Click Create API key and give it a name that reminds you what it is for
- Tick the permissions it needs
- Copy the key and store it somewhere safe
- Use it in the
Authorizationheader of every request
The key is shown only once
The full value appears a single time when you create it. If you lose it there is no way to recover it: you have to revoke it and create another.
Permissions
Every token carries the permissions you tick when creating it. Grant only the ones your integration needs.
| Permission | Gives access to |
|---|---|
catalog:read | Products, brands, countries, clusters, custom prompts and brand identity, with their metrics: sales, Amazon fees and margin, returns, stock and, for Vendor, reviews; and your P&L, with product cost and your own expenses if your plan includes it |
campaigns:read | Campaigns, portfolios, ad groups, targets, product ads and search terms |
workflows:read | Your workflows, their configuration and which campaigns they reach |
connections:read | Your account's connections: Amazon, Shopify and WooCommerce |
tasks:read | Epinium tasks and their items |
skills:read | Epinium's catalog of validated marketing playbooks |
platform:read | What is inside your Shopify and WooCommerce stores: products, stock, prices and the rest of what each store exposes, read live from its own API. It includes the record of the changes made in them (/v1/platform-changes, 1 credit per row returned) |
catalog:write | Create, edit and delete keyword clusters: their name, their positive and negative keywords, the products they group and the prompts they use. Create and edit custom prompts. Create and edit your brand identity, with a profile per competitor. Save changes to the attributes of your Amazon listings from a file, as changes pending to publish. Save and discard new listings on Amazon (offers on products that already exist, new products and families) and upload product images. Nothing reaches Amazon until you publish it |
costs:write | Create or update the unit cost and shipping cost of your products, and record, correct and delete their purchases, one by one or importing them from a file; and create, change and delete your own expenses and their categories |
campaigns:write | Create and change campaigns, portfolios, ad groups, targets and product ads on Amazon, and configure what the optimizer chases on each one |
platform:write | Create, edit and delete products and content in your connected Shopify and WooCommerce stores, directly and with no review first, through the same route used to query them (POST /v1/platform-request): a mutation in Shopify, or a non-GET method in WooCommerce, with the Idempotency-Key header. It also needs platform:read (the Edit level on the API keys screen grants both). Every change is recorded for 12 months and costs the same as a query: 5 credits per call plus 1 per KB returned |
tasks:write | Create tasks, approve or reject their suggestions, close them and apply what was approved. Ask Epinium's AI to rewrite listings as suggestions in a task |
workflows:write | Create, copy, edit, switch on, pause, delete and restore workflows, and run or simulate them |
catalog:publish | Publish to Amazon the pending listing changes and new listings you choose (POST /v1/pending-listing-changes/publish), the same way as the Publish button of the app. It cannot be undone. It also needs catalog:write |
Writing is for the Business and Master plans. On Free and Guru tokens read: you cannot create a key or authorise an assistant with write permissions, and if you move down to one of those plans, the ones you already had keep reading but their writes are refused with a 403.
A token reaches all the connections in your account. If you are an agency, it reaches the connections each client shared with you when accepting your invitation.
If you are an agency: pick the account on every call
An agency token reaches several accounts, so every request has to say which one it operates on. Use the Epinium-Account: <account id> header, or the account_id parameter if you are calling through the MCP.
/v1/me and /v1/accounts are the exception: they answer without picking an account, and they are exactly the ones that tell you which accounts you reach and what they are called.
Once the account is picked, you see all of it: its products and campaigns are scoped to the connections it shared with you, and its account-level resources — workflows, tasks and clusters, which hang off no connection — are scoped to the account. Anything outside your reach is not filtered out silently: an account_id you were not invited to returns an explicit error, not an empty list.
What endpoints it covers
Every resource has a list endpoint, and most also let you retrieve a single item by its id. The metrics resources only have a list: an aggregated row over a date range has no identifier of its own.
Catalog — catalog:read
| Endpoint | What it returns |
|---|---|
/v1/products | Your unified products |
/v1/amazon-seller-products | The Seller Central view of each product, and the category of its rank with expand=salesRanks |
/v1/amazon-vendor-products | The Vendor Central view, the category of the rank with expand=salesRanks and the reviews with expand=customerFeedback |
/v1/amazon-advertising-products | The Advertising view |
/v1/seller-product-metrics | Sales, sessions, Buy Box, rank, Amazon fees, margin, returns, stock, B2B and days of coverage per product |
/v1/vendor-product-metrics | Vendor sales per product, with manufacturing and sourcing, returns, sell-in with Amazon, inventory and days of coverage |
/v1/product-brands | Your brands |
/v1/countries | Countries and marketplaces |
/v1/clusters | Your keyword clusters; with catalog:write you can also create and edit them |
/v1/pnl/* | Your P&L: waterfall, per-product table, per cluster, per sales channel, cross advertising, freshness, margin leaks and inventory - explained in The P&L with product cost |
/v1/prompts | Your custom prompts; with catalog:write you can also create and edit them |
/v1/brand-identities | Your brand identity, with a profile per competitor; with catalog:write you also create and edit it - explained in Writing your brand identity |
/v1/listing-files | The listing change files you have uploaded in the last 7 days; uploading one takes catalog:read, and saving rows you wrote by hand as a file takes catalog:write |
/v1/listing-updates | Prepare and validate the changes in a file without saving anything; with catalog:write, save them as pending to publish - explained in Changing listings from a file |
/v1/listing-drafts | Your new listings on Amazon and their status; with catalog:write, save and discard them. To find the product and validate them, /v1/amazon-catalog/search, /v1/amazon-product-types/search, /v1/amazon-shipping-templates and /v1/listing-drafts/validate - explained in Listing new products on Amazon |
/v1/listing-images | With catalog:write, upload a product image for a listing or a new listing: JPG, PNG, GIF or TIFF, up to 8 MB, kept 30 days |
/v1/pending-listing-changes | What is pending to publish on Amazon, changes and new listings; with catalog:write and catalog:publish, publish it |
/v1/publications | Each publication to Amazon and how it is going per country, like the Publications panel of the app |
Advertising — campaigns:read
| Endpoint | What it returns |
|---|---|
/v1/campaigns | Your Amazon Advertising campaigns |
/v1/campaigns/budget-usage | How much of its daily budget each campaign has spent today, as Amazon counts it, at most half an hour behind |
/v1/campaign-metrics | Spend, sales, ACOS and ROAS per campaign |
/v1/portfolios | Your portfolios and the budget cap each one puts on its campaigns |
/v1/portfolios/budget-usage | How much of its cap each portfolio has spent this period, its pace and what it can spend per day to land on the cap |
/v1/adgroups | The ad groups of each campaign |
/v1/adgroup-metrics | Performance per ad group |
/v1/targets | Keywords and product targets |
/v1/target-metrics | Performance per target, with its keyword and match type |
/v1/product-ads | The link between an ad group and the product it advertises |
/v1/product-ad-metrics | Performance per advertised product, with its ASIN |
/v1/search-terms | The actual shopper queries |
/v1/search-term-metrics | Performance per query, with the text and the target that matched it |
/v1/campaigns/{id}/optimization-history | What the automation changed on a campaign, with the net effect |
/v1/advertising-changes | Every change Epinium has pushed to Amazon, whatever set it off |
Automation — workflows:read
| Endpoint | What it returns |
|---|---|
/v1/workflows | Your workflows, with their schedule and whether they are active |
/v1/workflows/{id} | The full configuration of one: its diagram and every variable with its effective value |
/v1/workflows/{id}/campaigns | Which campaigns it actually reaches, and why each one is in |
/v1/workflows/{id}/performance | The performance of those campaigns, with their target next to it so you can judge it |
A workflow can be scheduled every night and still touch no campaign at all: /campaigns is what surfaces that, and when the set comes back empty it names the reason.
Connections, tasks and skills
| Endpoint | Permission | What it returns |
|---|---|---|
/v1/connections | connections:read | Your connections: Amazon, Shopify and WooCommerce |
POST /v1/platform-request | platform:read, and platform:write to write | A query to one of your stores or, with platform:write, a change to it: GraphQL on Shopify, REST on WooCommerce |
/v1/platform-request/docs/{platform} | platform:read | That platform's API version, its reference and the fields your store has right now |
/v1/tasks | tasks:read | Epinium tasks |
/v1/task-items | tasks:read | The items of each task |
/v1/skills | skills:read | Epinium's catalog of marketing playbooks |
The skills catalog is content written by Epinium, not data from your account: it is the same for every client. Which parts of each playbook you receive depends on your plan.
Queries to your stores return no personal data: names, emails, phones and addresses are refused before the request reaches the store. They are charged by the size of the response, and so are changes. These two routes are not in the browsable reference: the usual way to use them is through the Epinium MCP.
There is also /v1/me, which tells you which permissions and which accounts your token reaches. It is the first useful call to check that the key works.
Three rules when reading the data
These three explain almost every question about interpreting the response:
- Monetary amounts are text, not numbers.
"cost": "8.22"arrives as a string on purpose, so it does not lose precision when converted to a binary decimal. - Ratios come as fractions, not percentages. An ACOS of 90.83% arrives as
0.908287. Multiply by 100 to display it. nullis not0.nullmeans Amazon did not report that figure;0means an actual zero. Anacosofnullis a campaign that spent without selling, not free advertising. Andnew_to_brand_salesarrives asnullon Sponsored Products because Amazon does not measure it for that format.
Profitability, stock and reviews of your products
Product metrics go beyond sales: they also tell you how much Amazon keeps, how much stock is left and what buyers think. Four things before drawing conclusions:
- Seller fees and margin exclude VAT, while
salesincludes it where it applies: do not subtract one from the other.margin_before_adsis what is left after paying Amazon, before advertising and product cost: for the margin after ads, subtract the spend from/v1/product-ad-metrics. Amazon books storage on a single day of the month and refunds on the refund date, so read the margin by month, not by day. days_of_coverageis how many days the stock lasts at the pace of the window: the stock of the last day divided by the average daily units of the range you ask for. It isnullwith any granularity other thantotal, when the product sold nothing or, when grouping, ifgroup_bydoes not include the country. Withorder_by=days_of_coverage&order=ascyou get first the products about to run out.- Vendor also has the sell-in: the units you confirmed to Amazon, those in open purchase orders, the fill rate and the lead time, plus returns split by manufacturing and sourcing and the health of the inventory.
- The category of the rank and the reviews are requested on the product, not on the metrics.
expand=salesRankstells you which category each Best Seller Rank position belongs to, and on Vendorexpand=customerFeedbackreturns the positive and negative review topics and the return reasons of the category. It is this week's snapshot, with the six-month trend Amazon calculates, not a history.
Account totals, by period and by cluster
To know how much the account sold in September you do not need to page through the catalog and add it up: the seven metrics resources aggregate on their own.
group_byadds up across entities.accountgives the account total;countryandconnectionbreak it down by country or by connection, and they combine by repeating the parameter (group_by[]=connection&group_by[]=country).accountdoes not combine with anything. Rows are still split by currency, since amounts are never converted, and, in advertising, by ad type (SP,SB,SD).granularitysplits the range into calendar periods. Besidestotalanddailyit acceptsweekly,monthly,quarterlyandyearly, and each row carries indatethe start of its period: the Monday of the week, or the 1st of the month, quarter or year. The periods at either end are partial: from January 15 to March 10 withmonthlyreturns January from the 15th to the 31st, all of February, and March from the 1st to the 10th.clusternarrows it down to a product family. On Seller, Vendor and product ad metrics,cluster=<id>keeps only the products in that cluster; with several ids, their union. It combines with the above:group_by=account&granularity=monthly&cluster=<id>is the monthly series for that family.group_by=clustergives one row per cluster. On the same three metrics,group_by=clusterreturns the figures of each of your clusters in a single call, with its id inclusterand its name incluster_name. A product in several clusters counts in full in each of them, so the rows do not add up to the account total, and products in no cluster do not appear. It combines withcountryandconnection, and with theclusterfilter to choose which clusters come back; if your clusters add up to more than 2,000 product-cluster memberships, the API asks you to narrow them down with that filter.
In grouped rows, the fields that identify an entity (product, asin, campaign…) arrive as null, and so does whatever cannot be added up: the rank, the price, the channel and the Vendor rates. Seller stock is only added up if you group by country: with FBA's pan-European inventory, Amazon reports the same stock in every marketplace, and adding it up across countries would count the same units several times. That is why, with group_by=account or connection, stock and days_of_coverage arrive as null.
A cluster groups catalog products, not loose ASINs: the same ASIN on another connection is left out unless its product is in the cluster too. And rows Amazon could not match to a catalog product do not enter the filter: around 5% of Vendor sales and 3% of product ad spend.
How much it saves in credits is explained in Credits.
The P&L with product cost
This is the same profit and loss statement you see in Profitability → P&L: sales, Amazon fees and logistics, advertising and, if your plan includes it, your product cost and your own expenses, with the same calculation and the same figures.
What you see depends on your plan. On Free and Guru the P&L reaches margin_before_ads: what is left after Amazon, before advertising and before product cost - do not call it "profit", because it is not. On Business and Master it goes all the way: contribution margin, every product-cost line and its coverage, and your own expenses down to net profit. includes_product_cost on every response tells you which of the two you are looking at, so you do not have to guess from whether the figures match what you expected. Margin leaks (/v1/pnl/margin-leaks and /v1/pnl/category-medians) is Business and Master only: on Free and Guru it returns 403 with code: "plan_feature_not_allowed", and its responses carry no includes_product_cost, because they always include cost. The same goes for inventory (/v1/pnl/inventory), which is valued at product cost.
| Endpoint | What it returns |
|---|---|
/v1/pnl/cascade | The period's waterfall: sales, refunds, fees, logistics, advertising, product cost and own expenses down to net profit, month by month or day by day |
/v1/pnl/products | One row per product, with its contribution margin and its cost coverage |
/v1/pnl/products/{id} | A product's detail: its own waterfall, month by month |
/v1/pnl/clusters | One row per cluster, with its contribution margin, its cost coverage and how many products it has |
/v1/pnl/channels | One row per sales channel (Seller, Vendor…), with its advertising broken down by platform |
/v1/pnl/ads-matrix | Cross advertising spend: which sales channel each platform advertises on |
/v1/pnl/freshness | The latest date of data for each source -Amazon, advertising and product cost- so you know whether what you are reading is already complete |
/v1/pnl/margin-leaks | The products that lost margin versus the previous period, sorted by money at risk, with their status, their main cause and the totals of the whole ranking: the same as Margin leaks |
/v1/pnl/category-medians | What is usual in your account: the median share of each cost in net sales, to see whether a product's cost is out of the ordinary |
/v1/pnl/inventory | The capital tied up in Amazon's warehouses: today's FBA stock valued at cost, with its days of stock, its rotation and the storage until it sells: the same as Inventory |
Nine things worth knowing before your first call:
- This is the only part of the API that converts currency. Every other resource returns each amount in the currency it occurred in; here you ask for
currencyand everything is converted to it, at the exchange rate of the day each amount occurred. A day with no exchange rate falls back to an approximate one, never an error. - Own expenses come in
own_expenses. Variable ones are already subtracted in thevariable_expensessection, before contribution margin, andown_expenses.periods[].variablebreaks them down by category. Fixed ones (fixed) are subtracted afterwards, down tonet_profit. Since they belong to the whole account, withconnection,countryorcluster, or with a token that does not reach every sales connection,fixedandnet_profitcome backnullandfixed_unavailablesays why:filteredorpartial_access. If the account has no fixed expenses nothing is missing, andnet_profitcomes back even with filters or with a token that does not reach every connection. In the per-product table, theown_expensescolumn is each product's share of the variable expenses. coveragetells you what portion of sales has a real cost. A product with no cost loaded is not silently discarded or set to zero:coverage.covered_salesovercoverage.total_salestells you what proportion of the figure you can trust. Incoverage,estimated_salesis the part ofcovered_saleswith an estimated cost: the stock sold more units than the recorded purchases left, and those sales carry the latest average cost.breakeven_acos, on/v1/seller-product-metrics, is the ACOS ceiling you can afford to spend on advertising before losing money on that product, computed with your real margin and your real cost -never with an assumed fee percentage. It comes backnull-never a made-up number- if the product does not have a full cost, sold nothing in the window, has its cost recorded in a currency other than its own marketplace's (this resource does not convert currencies, unlike/v1/pnl/*), or your plan does not include product cost (Free and Guru).- Product cost is kept when you downgrade your plan, not deleted. If you move to Guru, the cost you already had loaded stays there: it just stops being served. It comes back as soon as you upgrade again.
clusternarrows/v1/pnl/cascade,/v1/pnl/products,/v1/pnl/clusters,/v1/pnl/freshness,/v1/pnl/margin-leaks,/v1/pnl/category-mediansand/v1/pnl/inventoryto the products of one or more clusters, just like on the metrics: with several ids, their union, and a cluster with no products returns empty, not an error. Advertising only counts the spend of those products: Sponsored Brands and campaign spend that does not belong to a specific product are left out, because they belong to no cluster. In/v1/pnl/clustersa product that is in two clusters counts in both, and what is in no cluster does not show./v1/pnl/margin-leaksreturns the products in all three statuses by default, like the screen;statuskeeps the ones you choose. In the same call,summarygives how many there are in each status and the total at risk of the Leak and Watch products of the whole ranking, without paging, and every row carriesmain_cause, the cost that took the most margin, computed the same way as on the screen. If the previous period has no sales,has_previous_salesisfalse: the empty list means there is nothing to compare against, not that there are no leaks./v1/pnl/inventoryis today's stock, with no period: one row per stock, and in the EU a pan-European SKU comes once, with all itscountries, so do not add rows up across countries.summarygives the tied-up capital of the whole scope and its split by rotation, without paging and unaffected byrotationandsearch.currencyis required: cost is converted at the latest exchange rate and storage at each day's rate. Only the FBA stock of your Seller connections counts.- The cost that applies today to each product comes in
/v1/products. Thecostfield carriescogsandshipping, each with the unit amount, its currency,valid_fromandsource, ornullif it has none. Withcost_stateyou keep the active productswith(with cost),missing(no cost) ormissing_with_sales(no cost and sales in the last 30 days, the ones that inflate the margin the most), and withinclude_totalyou get how many there are. It is the same as what you see in Costs and expenses. On Free and Gurucostcomes asnullandcost_stateresponds403.
What the automation changed on a campaign
/v1/campaigns/{id}/optimization-history answers what the workflow changed on a campaign, not what it decided. The difference matters: in a decision log the same target can show up with a raise and a cut on the same night, and there you cannot see that they cancel each other out.
So every row comes aggregated to the entity's net effect: the bid from before the first change of the period against the bid after the last one, plus how many times it moved along the way. A target raised from €0.18 to €0.45 and cut back to €0.18 that same night comes back with a net of zero and two moves — which is the useful reading, and exactly the one a flat list hides.
Three things bound what it returns:
- Real changes only. Simulations are not exposed here, under any parameter: they are bids that never reached Amazon.
- Only what was applied, not what was proposed. The optimizer computes a bid that a ceiling can then cut; only what was sent is reported.
- A 90-day window at most. That is how long these records are kept. With no dates, it returns the last 90 days.
Changes that are not bids — harvested keywords, negatives, placement adjustments, quarantined or blocked targets — are counted separately in other_changes, because they have no previous bid to compare against.
Everything Epinium has changed on Amazon
/v1/advertising-changes answers a different question from the previous one: not why the automation decided something, but what was touched and whether Amazon accepted it. And not only what the automation does: also what a person did from the app, an internal process, or this very API.
The rule is one line: if it was sent to Amazon, there is a row. Three consequences follow, and they are worth having clear:
- What Amazon rejected leaves a row too, with
result: "failed"and the Amazon message inerror. It is the first place to look when a change did not take effect. - What was never attempted leaves no row: a budget below the country minimum, or a bid that already was the one being asked for.
- Configuration changes inside Epinium stay out, because they never reach Amazon.
Every row says where it came from. source tells the app (front), the optimizer (workflow), an internal process (system) and this channel (public-api, mcp) apart, and actor identifies the person or the specific credential — when someone made the change from the app, their email is there. If it came from a workflow, correlation_id is that run's identifier, which is the key for cross-referencing this response with optimization-history.
You can filter by campaign, adgroup, entity, entity_type, source, result, field and correlation_id, and narrow the window with start_date and end_date (YYYY-MM-DD, both inclusive). Records are kept for twelve months.
Writing to Amazon
With the campaigns:write permission the API stops being read-only: it creates campaigns, ad groups, targets and product ads, and moves their states, budgets and bids. What you write really goes to Amazon and leaves its row in /v1/advertising-changes.
Five things worth knowing before your first call:
- Everything is born paused. A campaign or an ad group is created
PAUSEDunless you ask forENABLEDexplicitly, because anything enabled starts spending as soon as Amazon accepts it. - Archiving has its own verb:
DELETE /v1/<resource>/{id}. It is the only irreversible operation in this API: on Amazon, archiving cannot be undone. That is why it is not astatevalue you could set by accident next to a bid change, but a separate call with a separate verb. If you only want to stop the spend, usestate: "PAUSED", which is reversible. - Every write requires an
Idempotency-Keyheader. Reuse the same value if you retry the same intent: without it, a network timeout becomes two campaigns. - A batch is not all-or-nothing.
POST /v1/<resource>/batchtakes up to 1000 entities and answers with one row per entity, in the order you sent them.appliedis what reached Amazon, and it is the only thing billed. A partial result is the normal outcome, not an error: read it instead of retrying the whole batch, because a retry would duplicate what already went in. - An entity counts as applied only if everything you asked for went through. If a
PATCHchanges state and budget and Amazon accepts the first and rejects the second, that entity comes backfailedwith the reason — calling it applied is how you end up believing a bid moved when it did not.
| Route | What it does |
|---|---|
POST /v1/campaigns | Create a campaign |
POST /v1/campaigns/full | Campaign + ad group + targets + product ads in one call |
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batch | State, daily budget, name and portfolio (the portfolio, Sponsored Products only) |
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batch | Create; state, default bid and name |
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batch | Create targets (the types depend on the ad group's ad product); state and bid |
POST /v1/product-ads · PATCH /v1/product-ads/{id} · POST /v1/product-ads/batch | Advertise products; state |
POST /v1/portfolios · PATCH /v1/portfolios/{id} | Create a portfolio; name, state and budget cap |
DELETE /v1/campaigns/{id} · DELETE /v1/adgroups/{id} · DELETE /v1/targets/{id} · DELETE /v1/product-ads/{id} | Archive - irreversible |
What cannot be changed, and why: what defines a target — its keyword, its ASIN, its match type — is not editable on Amazon, so to change it you create another and archive the previous one. A product ad only takes state: it is the link between a product and an ad group, with no bid or name of its own.
A portfolio's cap limits what all its campaigns spend together. MONTHLY_RECURRING resets every month, DATE_RANGE applies between startDate and endDate and NO_CAP removes it; the currency is the marketplace one and you do not send it. In a PATCH, budget is replaced whole: send the full cap you want, not just the amount. To move a Sponsored Products campaign into or out of a portfolio, change its portfolioId with PATCH /v1/campaigns/{id}.
Two status codes worth telling apart. An entity that does not exist, or belongs to another account, answers 404 — never 403, which would confirm it exists. A rejection from Amazon answers 200 with result: "failed" and the reason: the call did arrive, and what failed was the change.
All three ad products can be written, but not in the same way:
- Sponsored Brands and Sponsored Display are changed and archived with the same routes as Sponsored Products: state, budget, name and bids of campaigns, ad groups, targets and product ads. What you cannot do yet is create them:
POST /v1/campaigns,/v1/campaigns/full,/v1/adgroupsand/v1/product-adsare Sponsored Products only. - Sponsored Brands ad groups have no default bid. A
defaultBidchange on one is rejected with a message that says so. Sponsored Display ad groups do have one. - Targets and negative targets can be created in SB and SD ad groups, with
POST /v1/targets. The acceptedtargetTypedepends on the ad group's ad product (table below). Ad-group level only: SB and SD have no campaign-level negative targets. - Epinium checks the marketplace bid and budget limits only for Sponsored Products, before sending. For Brands and Display it applies no limits of its own: Amazon validates, and its reason comes back in the response, per entity with
result: "failed"or, when creating targets, infailure_details, wherereferenceidentifies the target (keyword, ASIN, SKU or the audience, category or location id).
| Ad product | Accepted targetType |
|---|---|
| Sponsored Products | KEYWORD, PRODUCT, PRODUCT_CATEGORY |
| Sponsored Brands | Those of Sponsored Products plus THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND or KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES) |
| Sponsored Display | KEYWORD; PRODUCT by ASIN or by sku, with productMatchType PRODUCT_EXACT or PRODUCT_SIMILAR; PRODUCT_CATEGORY with refinements (brand, price, rating, age range, Prime eligibility); THEME (INTERESTED_AUDIENCE); PRODUCT_AUDIENCE (ASIN + event PURCHASE or VIEW + lookback of 7, 14, 30, 60, 90, 180 or 365 days); AUDIENCE (audienceId), CONTENT_CATEGORY (contentCategoryId) and LOCATION (locationId) |
The ids for AUDIENCE, CONTENT_CATEGORY and LOCATION come from the Amazon Ads console: the API does not list them yet.
Optimization config
With the same campaigns:write permission, besides writing to Amazon you can read and change the configuration Epinium's optimizer uses: what it chases on each campaign. This is a different surface from the one above, and worth not confusing with it.
It never reaches Amazon. It is Epinium's own configuration, consumed by the optimizer on its nightly run, not a fact about the Amazon account. That is why two rules from "Writing to Amazon" do not apply here: no Idempotency-Key header is needed - there is no round trip to Amazon a retry could duplicate - and the change leaves no row in /v1/advertising-changes, which only records what was sent to Amazon.
It is read with expand, not by default. GET /v1/campaigns and GET /v1/campaigns/{id} only return optimizationConfig if you ask for ?expand[]=optimizationConfig. It is opt-in because very few campaigns have this configuration saved: without the expand, the column would come back null almost every time.
What you can set with PATCH /v1/campaigns/{id}/optimization-config, in business terms:
- The objective: a target ACOS or ROAS, or a volume objective - impressions or orders - with an ACOS ceiling alongside it.
- The bid limits: the floor and ceiling it cannot cross, the placement multiplier cap, and the minimum spend before negativizing a target.
- The monthly budget the optimizer chases - not the campaign's Amazon daily budget, which is changed with
PATCH /v1/campaigns/{id}and is a different field with the same name. - The campaign's harvesting overrides: its discovery level and whether it allows targeting competitor ASINs.
- Which workflows optimize it.
That last point is the one that really matters: assigning workflows is what puts the campaign under optimization, not any other field in this block. linkedWorkflowDefinitionIds force-includes it - the workflow processes it every night even if its own filter would not have picked it - and it is how a workflow moves real bids on Amazon; confirm it with the person before writing it, exactly as you would turning on an automation. A workflow with auto-selection can also pick it up on its own, and workflowsOptOut: true is what declines that automatic selection. The only thing that reliably takes it out is excludedWorkflowDefinitionIds: it always wins, whatever else says otherwise.
aiEnabled is not the optimizer's switch
It is the account holder's consent flag, and it travels to Amazon as the epinium:ai_enabled tag. Setting it to false does not take the campaign out of optimization: that is what excludedWorkflowDefinitionIds is for, or removing it from linkedWorkflowDefinitionIds.
optimizeDate and optimizingSince are read-only - the optimizer itself stamps them - and writing either one gets you a 400.
POST /v1/campaigns/optimization-config/batch applies the same patch to up to 1000 campaigns, and it is not all-or-nothing: it answers with one row per campaign, in the order you sent them, and each one is validated against its own stored state - a ceiling that is mandatory for one objective can be optional for another - so one row can fail without affecting the rest.
Two status codes worth telling apart, just as when writing to Amazon: a validation rejection - an objective out of range, a workflow that is not yours - answers 200 with result: "failed" and the reason in reason. A campaign that does not exist or belongs to another account answers 404 on the single PATCH; in the batch, that same campaign instead comes back as a failed row with reason: "not_found", precisely so one bad row cannot sink the other 999.
| Route | What it does |
|---|---|
PATCH /v1/campaigns/{id}/optimization-config | Change a campaign's optimization config |
POST /v1/campaigns/optimization-config/batch | The same config on up to 1000 campaigns, one row per result |
Writing tasks
With the tasks:write permission the API creates tasks and decides on their suggestions, just as you do in Processes → Tasks. It is the piece that lets an assistant or an integration propose changes and a person review them before they reach Amazon.
Four things worth knowing before your first call:
- Approving does not apply. There are two steps: approve or reject each suggestion, and then
POST /v1/tasks/{id}/apply. At that point campaign changes — daily budget, state and name — go to Amazon straight away, and the response says which ones went in (applied) and which ones it rejected (failed). Product changes are queued (enqueued) and applied in the background: to find out whether they went in, read the suggestions again and look atappliedAtandapplyError. - A suggestion that nothing knows how to apply is a note. Today, product suggestions and campaign suggestions that carry a
fieldPathare applied; those without one, and those for ad groups, targets, product ads and search terms, stay as notes. Approving them records the decision and changes nothing, and the response says so withautoApplySkipped: true. It is not an error. When creating, on the other hand, a campaign suggestion with a field other thandailyBudget,stateorname, or with a value that cannot be applied, is rejected with a400: saving it would promise a change nobody is going to make. - Suggestions come with the task. Up to 50 in
itemswhen you create it, each pointing to an entity in your account; they cannot be added later. An entity that does not exist or belongs to another account rejects the whole task, without creating anything. - Resolving a task is final. Its pending suggestions are not resolved with it: they stay frozen and can no longer be approved. Decide the ones that matter to you first and close the task afterwards. Resolving it does not resume any workflow either.
| Route | What it does |
|---|---|
POST /v1/tasks | Create a task, with its suggestions |
PATCH /v1/tasks/{id} | Title, description, priority and expiry date |
POST /v1/tasks/{id}/resolve | Resolve or discard it |
PATCH /v1/task-items/{id} · POST /v1/task-items/batch | Approve or reject suggestions, optionally with your own value in appliedValue |
POST /v1/tasks/{id}/apply | Apply what was approved |
POST /v1/tasks/listing-optimizations | Ask Epinium's AI to rewrite listings, as suggestions in a task - explained in Rewriting listings with the Epinium AI |
As with Amazon, every write requires Idempotency-Key, and the suggestions batch is not all-or-nothing: it answers with one row per suggestion and applied counts the ones that were recorded. Creating, editing or resolving a task costs a flat charge per call; approving or rejecting is billed per recorded suggestion. Applying is not billed separately: each suggestion was already billed when it was approved.
Rewriting listings with the Epinium AI
With the tasks:write permission, POST /v1/tasks/listing-optimizations asks Epinium's AI to rewrite the title (with its highlights, the Item Highlights), the bullets, the description and the search terms of 1 to 20 products in your catalog. It is the same generation as in the app: it follows each product's keyword clusters, the prompts linked to them and your brand identity. The result changes no listing: it is left as suggestions in a task, the onboarding one, for a person to review.
Five things worth knowing before your first call:
- It answers at once and generates afterwards. The response is a
202with the task id (task) and what is left of the cap (limit). Each suggestion appears in the task when it is ready: read them at/v1/task-itemsfiltered bytask. - Nothing reaches Amazon without you. You approve or reject each suggestion and apply the task (
POST /v1/tasks/{id}/apply), like any other. Applying leaves the changes pending to publish: they reach Amazon when you publish them, from the app or withPOST /v1/pending-listing-changes/publish, which needscatalog:publish. - It does not use your credits, but it has a cap. Epinium pays for the rewrite, up to 20 products per account in total. Every product of every call counts, including one you relaunch or whose generation fails. A call asking for more products than you have left is refused whole with a
403whosecodeislisting_optimization_limit_reached, and nothing is generated;limit(cap,used,remaining) tells you in every response how many you have left. Approving or rejecting the suggestions is billed as in any task. - You choose products and fields.
productsare catalog product ids, Seller or Vendor (/v1/products; advertising ones are not valid).fieldstakestitle,bullets,descriptionandsearch_terms; without it all four are rewritten.titlealso rewrites the highlights. - It requires
Idempotency-Key. Reuse the same key when you retry, or you would spend products of the cap again.
Writing keyword clusters
With the catalog:write permission the API creates and edits your keyword clusters, the same ones you manage in Segmentation → Clusters: a named group of products with the positive keywords they should rank or advertise for and the negative keywords to keep away from. It is the way for an assistant that has found a keyword gap to leave it saved where Epinium's SEO prompts, the optimizer's keyword discovery and the cluster filter of the product charts will pick it up.
Four things worth knowing before your first call:
- Nothing reaches Amazon. A cluster lives in Epinium. That is why these writes leave no row in
/v1/advertising-changes, and why your AI client will not ask you to confirm them. - Editing is by deltas, not by replacement.
PATCH /v1/clusters/{id}takesaddPositiveKeywords,removePositiveKeywords,addNegativeKeywords,removeNegativeKeywords,addProducts,removeProducts,addPrompts,removePromptsandname; send only what changes. Adding a keyword that is already there updates its language, score and purpose, matched by text; removing one that is not there does nothing. A cluster holds up to 100 positive and 50 negative keywords, counted after the change, and a keyword cannot be positive and negative at once. - Keywords follow the app's rules. Lowercased, up to 80 characters, Amazon's character set, no leading
-or.and no trailing-,+or.; duplicates are merged.languageis a code likees-ESoren-GB,epiniumScoregoes from 1 to 5 andpurposeisSEO,PPCor both (both by default). - A protected cluster is refused with
409. Protecting a cluster from the app is a person's decision, and this API cannot undo it: unprotect it in Segmentation → Clusters first. Theprotectedfield in the response tells you before you try.
| Route | What it does |
|---|---|
POST /v1/clusters | Create a cluster, with its keywords, products and prompts if you have them |
PATCH /v1/clusters/{id} | Add or remove keywords, products and prompts, or rename it |
DELETE /v1/clusters/{id} | Delete it, with no way back |
Every prompt you link must belong to your account, or the call is refused with a 400 naming the offending ids. Every product you link must belong to your account — for an agency, to the connections the account shared with you — and be a catalog product (type seller or vendor in /v1/products; advertising products are refused), or the whole call is refused with a 400 naming the offending ids, and nothing is written. The cluster is owned by the person behind the credential, so it shows up in the app's table under their name. Deleting is final - there is no bin - and is refused with a 409 while the cluster is protected or a smart campaign uses it as its base cluster; the error names those smart campaigns, which have to be changed or deleted first. Each write costs a flat charge per call, and the plan's cluster quota applies here as it does in the app.
Writing custom prompts
With the catalog:write permission the API creates and edits your custom prompts, the ones in your prompts library: named instructions that Epinium's AI follows when it writes the content of your listings -tone, structure, words to use or avoid-. Reading them only takes catalog:read, at /v1/prompts, and each cluster returns the ids of its own in prompts; with expand[]=prompts it brings them in full.
Four things worth knowing before your first call:
- A prompt changes nothing on its own. It neither touches Amazon nor rewrites any listing when it is saved: it applies when the content of the products in the clusters you link it to is generated (
addPromptsinPATCH /v1/clusters/{id}). If several prompts from a product's clusters apply to the same field, only one is used, so keep one prompt per field. fieldssays which listing fields it applies to:titleAndHighlights(the title and the item highlights, which are written together),product_description,bullet_pointorgeneric_keyword(the search terms). Withoutfields, or with[], it applies to all of them. An older prompt may still carryitem_name, the title on its own, which is read but no longer accepted on writes.- The instruction has a cap: up to 2,000 characters, the same as in the app. The name needs at least 3.
- When editing, what you send replaces what was there:
PATCH /v1/prompts/{id}takesname,instructionandfields, andfieldsreplaces the whole list.
| Route | What it does |
|---|---|
POST /v1/prompts | Create a prompt |
PATCH /v1/prompts/{id} | Rename it or change its instruction or its fields |
The prompt is owned by the person behind the credential. Deleting prompts is not available through the API. Each write costs a flat charge per call, and the plan's prompt quota applies here as it does in the app: if you have already reached it, creating returns 403.
Writing your brand identity
With the catalog:write permission the API creates and edits your brand identity, the one in Settings → Brand: the brand's name, its sector, its websites, your competitors' websites, your notes (tone, audience, words to use or avoid) and the catalog brands it covers. It is the context Epinium's AI uses when it writes your listings. Reading it only needs catalog:read, at /v1/brand-identities. These are not your catalog brands, which are at /v1/product-brands.
Besides the loose websites in competitor_urls, each competitor can have its own profile in competitors, up to 50:
| Field | What it is |
|---|---|
name | Brand or seller name. Required |
url | Its website or its Amazon store |
asins | The ASINs of its products that compete with yours, up to 20 |
threat | How dangerous it is: level (low, medium or high) and reason, what was seen in the data. The level never goes without its reason; if there is no evidence yet, leave it out |
price_position | Its price compared with yours: below, similar or above |
Four things worth knowing before your first call:
- Competitor profiles are not shown in the app yet. They are saved and read through the API and the MCP; Settings → Brand does not show them yet.
- When editing, a list replaces the stored one.
PATCH /v1/brand-identities/{id}changes only the fields you send, butcompetitors,competitor_urls,brand_urlsandproduct_brand_idsare replaced whole: to add a competitor, send the ones you had plus the new one. The previous values are not kept anywhere. - Profiles do not replace
competitor_urls. They are two independent lists, and the websites you already had stay. A brand identity saved before profiles existed has an emptycompetitors. - Nothing reaches Amazon. The brand identity lives in Epinium: saving it neither touches nor rewrites your listings. Through the API it cannot be deleted, nor its logo uploaded.
| Route | What it does |
|---|---|
POST /v1/brand-identities | Create a brand identity |
PATCH /v1/brand-identities/{id} | Change its fields or its lists |
Like every write, it requires Idempotency-Key.
Changing listings from a file
With the catalog:write permission the API saves changes to the attributes of many Amazon listings at once, from an Excel file or a CSV: any attribute Amazon lets you edit in the product type of each listing, on Seller and on Vendor. It is what the Epinium MCP uses, and that page explains the whole flow from the point of view of the person asking for it.
| Route | Permission | What it does |
|---|---|---|
POST /v1/listing-files | catalog:read | Uploads the file (.xlsx, .xls or .csv) and returns its file_id. It is kept for 7 days |
POST /v1/listing-files/rows | catalog:write | Saves headers and rows you already have as a file, without uploading anything |
POST /v1/listing-updates/prepare | catalog:read | Finds the products in the file by SKU, ASIN or EAN and says which attributes they accept |
POST /v1/listing-updates/validate | catalog:read | Validates the rows against Amazon's rules for each product type, without saving anything |
POST /v1/listing-updates/apply | catalog:write | Saves the valid rows as changes pending to publish, in the background |
GET /v1/listing-updates/apply/{file_id} | catalog:read | The status of that save, what was sent and what it cost |
Five things worth knowing before your first call:
- Nothing reaches Amazon on saving.
applyleaves the changes pending to publish, and they go out to Amazon when someone publishes them from Publish changes in Epinium or withPOST /v1/pending-listing-changes/publish(see Listing new products on Amazon). - Data that go together need a person. A value that forces others to be filled in, such as batteries, is saved only if its
cascade_idarrives inconfirmed_cascades; otherwise it goes to a task to be reviewed. The rest of the row is saved anyway. - It is charged at 5 credits per row. When the file is accepted, 5 per row are reserved, with a
402if the balance falls short. At the end only the rows sent are charged and the rest is refunded, all of it if the save fails. Uploading, preparing, validating and reading the status are free. - Prices go by audience. A column is declared with
offer: { audience, field }(field:price,min,max,sale_price,sale_startorsale_end);clear: truemakes its empty cells clear, anddate_order(dmyormdy) sets the order of ambiguous dates.validatereturns inoffer_clearsthe price columns with empty cells on products that have that value, and the price rules as blockingoffer_*problems. In Vendor no price is edited: those columns come back innot_applicablewith the reasonvendor_price.prepareoffers the price fields inoffer_fields. - A file is applied once. Repeating the call with the same settings returns the status; with different settings, or with a file that has less than 24 hours left, it responds
409. Like every write, it requiresIdempotency-Key.
The parameters of each route are in the catalog reference.
Listing new products on Amazon
With the catalog:write permission the API saves new listings: products that are not in your Amazon account yet. It can be an offer on an ASIN that already exists (Seller only), a new product or a variation family, on Seller and on Vendor. What each one is, what Amazon asks for and how a family is published are in New product listings on Amazon.
| Route | Permission | What it does |
|---|---|---|
GET /v1/amazon-catalog/search | catalog:read | Finds a product in Amazon's catalog by ASIN, EAN, UPC or GTIN, with its restrictions for your account |
GET /v1/amazon-product-types/search | catalog:read | Recommends product types from the name of a new product |
GET /v1/amazon-shipping-templates | catalog:read | The shipping templates of your Seller account, for an offer you ship yourself |
POST /v1/listing-drafts/validate | catalog:read | Validates the new listing against Amazon's rules and with an Amazon preview, without saving anything |
POST /v1/listing-drafts | catalog:write | Saves the new listing as pending to publish |
GET /v1/listing-drafts | catalog:read | Your new listings and their status, with what Amazon answered |
DELETE /v1/listing-drafts/{id} | catalog:write | Discards a pending new listing |
GET /v1/pending-listing-changes | catalog:read | What is pending to publish, as in Publish changes |
POST /v1/pending-listing-changes/publish | catalog:write and catalog:publish | Publishes on Amazon the chosen changes and new listings, the same way as the app's Publish button |
Four things worth knowing before your first call:
- Saving is not publishing. The new listing stays pending until it is published from the app or with
publish, which also requirescatalog:publishand cannot be undone. - The SKU has to be new in that marketplace (on Vendor, under that vendor code): one that already exists, in Epinium or on Amazon, responds
409. - Saving asks Amazon again and responds
400, with what is missing, if Amazon would reject the new listing: validate first. - Validating (1 credit) and saving (5) are charged. Searching, the templates, listing, discarding and publishing are free. Like every write, saving and publishing require
Idempotency-Key.
The parameters of each route are in the catalog reference.
Writing a product's cost
With the own costs:write permission -not catalog:write, which is for clusters, prompts and listings- the API creates or updates a product's unit cost and shipping cost: the same action you take on the product's own page or when uploading the cost CSV template, with the same semantics. For many products at once, use the import.
| Route | What it does |
|---|---|
POST /v1/products/{id}/costs | Creates or updates a product's unit cost (price) and shipping cost (shipping_cost) |
Four things worth knowing before your first call:
- The semantics are the CSV's. An empty field does not touch the value: if you only send
price, the shipping cost it already had stays as it was. A0sets it to zero for real -not the same as not sending the field. At least one ofpriceorshipping_costis required. - A past date recalculates the history.
datedefaults to today; if you send an earlier date, the new cost applies from there and the P&L of the periods already closed after it recalculates on its own. The response says what happened inrecalculation:not_neededwith today's date,queuedif it enqueued the recalculation, orfailedif it could not be enqueued -the cost is saved all the same, it is only the P&L that will take a while to reflect it. - Only on the plans that include product cost. On Free and Guru this route responds with a
403, same as every other write on those plans. Like every write, it requiresIdempotency-Key. - A product with purchases does not accept
price. Its product cost is calculated from the recorded purchases, so it responds409with the codeCOST_FROM_PURCHASES. To change only its shipping, sendshipping_costalone, withoutprice: with both, everything is rejected and the shipping is not saved. To change its product cost, record or correct a purchase (Recording a product's purchases).
Recording a product's purchases
When a product has purchases, its product cost is the average cost of its stock: each purchase recalculates it with the units you had and the ones you buy. It is the same as Record purchases on the product page, with the same calculation. Reading needs catalog:read; recording, correcting and deleting, costs:write. Both only on the plans that include product cost.
| Route | What it does |
|---|---|
GET /v1/products/{id}/purchases | The product's purchases, with the average cost each one left |
GET /v1/products/{id}/stock-group | Which products it shares stock with, or which ones it would be grouped with on its first purchase |
GET /v1/purchases | Your purchases, by account and by dates |
GET /v1/purchases/{id} | One purchase |
POST /v1/products/{id}/purchases | Records a purchase |
PATCH /v1/purchases/{id} | Corrects a purchase: send only what changes |
DELETE /v1/purchases/{id} | Deletes a purchase |
- Shared stock has a single cost. With Pan-European FBA, the same SKU in the EU countries is the same stock, so a purchase changes the cost of all of them (UK and Vendor are separate). The group is created with the first purchase; if those countries have different costs today, that purchase needs
prior_stock_unit_cost, what the stock you already had was worth, or it responds400withPRIOR_STOCK_VALUE_REQUIRED. - The stock before the purchase. Without
stock_on_hand, it takes the latest Amazon FBA stock from the previous 7 days, plus the purchases recorded since then. On FBM it is required. - The order number is not repeated. With
reference, sending the same purchase again responds409withDUPLICATE_PURCHASE_EXTERNAL_IDinstead of duplicating it. - Correcting or deleting recalculates. It changes the average cost of that purchase and of the ones after it, and the P&L of the periods already closed, like a cost with a past date. Deleting cannot be undone; if it was the group's last purchase, the costs from before apply again.
- With several accounts, reading needs one and writing needs all of them. If the stock is shared by accounts the key does not reach, you can read their purchases but not change them:
400withSTOCK_GROUP_OUT_OF_SCOPEwhen recording,404when correcting or deleting. - Each write costs the same as writing a cost, and like every write it requires
Idempotency-Key.
Importing the costs of many products
To load the cost of your catalog, use the import: it is the same as Import costs from a file in the app, with the same template and the same rules, and it recalculates the P&L only once, at the end. With the same costs:write permission.
Do not do it product by product with POST /v1/products/{id}/costs: each cost with a past date recalculates the P&L of the whole account, and while it runs the API rejects the next ones with a 409.
| Route | What it does |
|---|---|
POST /v1/cost-imports/files | Uploads the cost file and returns its file_id, without importing anything. It is kept for 7 days. GET lists the ones you uploaded |
POST /v1/cost-imports/preview | Checks the import without saving anything: which rows would be applied, which would not and why, how many go without a date, how many will only count until a later cost the product already has and what it would cost |
POST /v1/cost-imports | Imports the costs of the products of one account, from uploaded files or from rows |
GET /v1/cost-imports/{id} | The state of the import: how many rows were applied, how many changed nothing and how many were rejected, with the reason for each one |
What is worth knowing:
- Rows come in two ways. With
file_ids, the files you uploaded withPOST /v1/cost-imports/files(.xlsx,.xlsor.csv, up to 8 MB and 200,000 rows per import: a whole catalog fits in one file; an Excel file with many columns may not fit, in which case remove the extra columns or upload it as CSV). Files uploaded for listing changes are not accepted here. Or withheadersandrows, up to 5,000 rows, if you have not uploaded any file. - The columns are the template's (
sellerSku,marketplace,date,cogs,cogsCurrency,shippingCostandshippingCostCurrency) and they are recognized the same way as in the app, also with common names like "sku", "cost" or "date". If one is not recognized, tell it which header each field comes from withcolumns. Each row follows the rules of the app's file. - Check it first, for free.
POST /v1/cost-imports/previewtakes the same body and applies the same rules row by row, the match against your catalog included, but saves and charges nothing. It tells you how many rows would be applied, skipped (empty, or with the same cost the product already had on their date:unchanged) and rejected, with the reason and examples, how many would go without a date and how many credits it would cost. Only when applying can a row still be rejected, if there is no exchange rate for its currency on its date. - A row without a date applies from today. If your rows have no date, pass in
datethe day the costs apply from: it applies to the rows without a date, and the ones that have one keep theirs. - Variation parents are rejected with
parent_product: they do not sell, so their cost would cover no sale. The cost goes on their variations. - It is asynchronous. It responds
202withstatus: "processing". QueryGET /v1/cost-imports/{id}until it saysfinished,finished_with_errorsorerror; querying it costs nothing. Rows with a cell longer than the template allows come back innot_sentand are not imported. - It stays in the app's history, in the History of the cost import of that account, just as if you had uploaded it from the app.
- One account per import. While the P&L of that account is being recalculated because of an earlier cost change, it responds
409without importing anything: wait for it to finish and run it again. - Each applied row costs the same as writing the cost of one product. When it is created, the rows that can be applied are reserved and, if your balance is not enough, it responds
402without importing anything. When it finishes only the applied rows are charged and the rest is returned: rejected rows and rows that changed nothing cost nothing. Only on the plans that include product cost, and it requiresIdempotency-Key. - Purchases too. With
kind: "purchases"it imports purchases with the app's purchases template (sellerSku,marketplace,date,units,currency,productCost,inboundShippingCost,tariffCost,otherCost,stockOnHand,reference), only on Seller accounts. The check of purchases only reviews the format of each row (checks: "format") and already rejects badly formatted rows: the SKU, its stock group and the stock are checked when applying, so a few more rows may be rejected then. Each applied purchase costs the same as recording it on its own.
Writing own expenses
Your own expenses (staff, agency, 3PL, software…) are read with catalog:read and written with the same costs:write permission as product cost. They are the same ones you add in Costs and expenses → Own expenses, and the P&L subtracts them down to net profit.
| Route | What it does |
|---|---|
GET /v1/expenses | Your expenses, filterable by basis, status (active, upcoming or ended) and category |
GET /v1/expenses/{id} | One expense, with its history of amounts by month |
POST /v1/expenses | Creates an expense |
POST /v1/expenses/batch | Creates up to 100 expenses at once, from a list or from an uploaded spreadsheet (file_id), or checks them without creating anything |
POST /v1/expenses/files | Uploads a spreadsheet of expenses and returns its file_id, without creating anything. Kept for 7 days. GET lists the ones you uploaded |
PATCH /v1/expenses/{id} | Changes the concept or the category, or ends it with valid_to (null reopens it). Ending it deletes the amount changes scheduled after that month, and reopening it does not bring them back |
POST /v1/expenses/{id}/amounts | Changes the amount from a given month; earlier months keep theirs |
DELETE /v1/expenses/{id} | Deletes it from the whole history |
GET /v1/expense-categories | The standard categories and yours |
POST, PATCH and DELETE /v1/expense-categories | Creates, renames or deletes one of your categories. A category used by any expense cannot be deleted |
basis says how each expense is calculated: fixed (a fixed amount, with frequency monthly, quarterly, yearly or once and, in the latter, spread_months 1, 3, 6 or 12), per_unit (per net unit sold), pct_net_sales or pct_ad_spend (in points: 5 is 5 %). The three variable ones accept scope to apply only to some connections or countries.
Five things worth knowing before your first call:
- For more than one expense, the batch.
POST /v1/expenses/batchcreates up to 100 at once.dry_runis required: send it first withtrue, which writes nothing and spends no credits, and then withfalse. It is all or nothing: if one expense fails none is created, andfailure_detailssays which ones and why.possible_duplicateswarns about the ones that look like one you already have or like another in the same batch, without blocking them. Only the expenses created are charged. - A spreadsheet of expenses, as a file. Upload it with
POST /v1/expenses/files(.xlsx,.xlsor.csv, up to 8 MB and 1,000 rows) and send itsfile_idto the batch: it is read with the same rules as the app import. If its columns are not named like the template, say which one holds each field withcolumns, and pass intypeandcurrencythe type and currency of the rows without them. A row that cannot be read comes back infailure_detailsasrow N, and then nothing is created. - The P&L subtracts them straight away. Expenses are computed when the P&L is read, so a create, change or delete shows up in the next query, including in months that have already passed.
- Each token touches the expenses of its connections. A token that does not reach every sales connection of the account only sees and changes the expenses of its own, and cannot create account-wide expenses (fixed ones and variable ones without connections in
scope) or rename or delete categories: it responds403, and in the batch that row comes back infailure_details. An expense it cannot see responds404. - Only on the plans that include product cost. On Free and Guru these routes respond with a
403, uploading the file included. Every write except uploading the file requiresIdempotency-Key.
Limits
- Metrics require a date range.
start_dateandend_dateare mandatory on every metrics resource. - The range has a maximum, and it depends on the granularity. With
granularity=daily, 93 days; withtotalor with the calendar periods (weekly,monthly,quarterly,yearly), 366. On targets and search terms, the heaviest resources, those drop to 31 and 93. Asking for more returns an error naming the exact limit. Both dates are included in the range. - Lists paginate in two different ways. Catalog and structure resources use a cursor (
starting_after); metrics resources uselimitandoffset. In both caseshas_moretells you whether another page follows. - There is a request limit per token. If you exceed it you get a
429and simply need to retry more slowly. - There is also a limit on concurrent requests. A
429can mean "too many at once", not just "too many per minute"; a503means the server is momentarily at capacity. Both carryRetry-Afterand both are transient: retry with fewer requests in parallel. - A single response cannot expand more than 5,000 objects.
expandover lists — a cluster's products, a connection's countries — multiplies at every level. Going over returns a400naming how many objects it would have returned: lowerlimit, drop anexpand, or fetch that data from its own endpoint.
Credits
Calls to this API consume credits from your account. What each resource costs is visible in the app, under Settings → Credits.
Every response tells you what you spent:
| Header | What it is |
|---|---|
X-Epinium-Credits-Cost | What this call cost |
X-Epinium-Credits-Remaining | What you have left. It is approximate: if you have other things consuming at the same time, it can drift |
X-Epinium-Credits-Breakdown | The breakdown, per resource and unit price: product=100x1,country=100x0 |
X-Epinium-Credits-Max | The most it could have cost, computed before running it |
Three things worth knowing:
- You are only charged for what is delivered. A call that fails costs nothing, and an
expandthat returns no data — because your token lacks that scope, or the record belongs to another account — costs nothing either. - In metrics, the date range costs too, not just the rows. Asking for a year with
limit=1is not cheap: on top of every row returned you pay for every day of the range, because that is what has to be read to answer, with a 3-day minimum per call. To spend less, shorten the range. - For a total,
group_byinstead of paging. An account total is only a few rows, one per currency, whereas paging through the catalog to add it up pays for every product on every page. On a real account, a month's total sales cost 157 credits withgroup_by=accountand about 17,600 by paging.
If your credits do not cover it you get a 402 before the call runs: you will never be left with half a response. And it does not just say no, it says what to change and to what value:
{
"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 is the same remedy in machine-readable form: limit, end_date or include_total. When it is absent, no parameter change fits the request and you need to top up.
Parameters and responses of each endpoint
The table above says which resources exist. To see the input parameters and the exact shape of each response, there are two routes:
- Browsable reference — every endpoint with its parameters, their types and an example response. Generated from the API itself, so it cannot fall out of date. In English.
- OpenAPI schema — the raw OpenAPI 3.0 document, to import into Postman, Insomnia or a client generator. No token needed.