Skip to content

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 ​

  1. Go to Settings → API Keys
  2. Click Create API key and give it a name that reminds you what it is for
  3. Tick the permissions it needs
  4. Copy the key and store it somewhere safe
  5. Use it in the Authorization header 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.

PermissionGives access to
catalog:readProducts, 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:readCampaigns, portfolios, ad groups, targets, product ads and search terms
workflows:readYour workflows, their configuration and which campaigns they reach
connections:readYour account's connections: Amazon, Shopify and WooCommerce
tasks:readEpinium tasks and their items
skills:readEpinium's catalog of validated marketing playbooks
platform:readWhat 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:writeCreate, 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:writeCreate 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:writeCreate and change campaigns, portfolios, ad groups, targets and product ads on Amazon, and configure what the optimizer chases on each one
platform:writeCreate, 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:writeCreate 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:writeCreate, copy, edit, switch on, pause, delete and restore workflows, and run or simulate them
catalog:publishPublish 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 ​

EndpointWhat it returns
/v1/productsYour unified products
/v1/amazon-seller-productsThe Seller Central view of each product, and the category of its rank with expand=salesRanks
/v1/amazon-vendor-productsThe Vendor Central view, the category of the rank with expand=salesRanks and the reviews with expand=customerFeedback
/v1/amazon-advertising-productsThe Advertising view
/v1/seller-product-metricsSales, sessions, Buy Box, rank, Amazon fees, margin, returns, stock, B2B and days of coverage per product
/v1/vendor-product-metricsVendor sales per product, with manufacturing and sourcing, returns, sell-in with Amazon, inventory and days of coverage
/v1/product-brandsYour brands
/v1/countriesCountries and marketplaces
/v1/clustersYour 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/promptsYour custom prompts; with catalog:write you can also create and edit them
/v1/brand-identitiesYour brand identity, with a profile per competitor; with catalog:write you also create and edit it - explained in Writing your brand identity
/v1/listing-filesThe 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-updatesPrepare 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-draftsYour 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-imagesWith 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-changesWhat is pending to publish on Amazon, changes and new listings; with catalog:write and catalog:publish, publish it
/v1/publicationsEach publication to Amazon and how it is going per country, like the Publications panel of the app

Advertising — campaigns:read ​

EndpointWhat it returns
/v1/campaignsYour Amazon Advertising campaigns
/v1/campaigns/budget-usageHow much of its daily budget each campaign has spent today, as Amazon counts it, at most half an hour behind
/v1/campaign-metricsSpend, sales, ACOS and ROAS per campaign
/v1/portfoliosYour portfolios and the budget cap each one puts on its campaigns
/v1/portfolios/budget-usageHow 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/adgroupsThe ad groups of each campaign
/v1/adgroup-metricsPerformance per ad group
/v1/targetsKeywords and product targets
/v1/target-metricsPerformance per target, with its keyword and match type
/v1/product-adsThe link between an ad group and the product it advertises
/v1/product-ad-metricsPerformance per advertised product, with its ASIN
/v1/search-termsThe actual shopper queries
/v1/search-term-metricsPerformance per query, with the text and the target that matched it
/v1/campaigns/{id}/optimization-historyWhat the automation changed on a campaign, with the net effect
/v1/advertising-changesEvery change Epinium has pushed to Amazon, whatever set it off

Automation — workflows:read ​

EndpointWhat it returns
/v1/workflowsYour 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}/campaignsWhich campaigns it actually reaches, and why each one is in
/v1/workflows/{id}/performanceThe 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 ​

EndpointPermissionWhat it returns
/v1/connectionsconnections:readYour connections: Amazon, Shopify and WooCommerce
POST /v1/platform-requestplatform:read, and platform:write to writeA 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:readThat platform's API version, its reference and the fields your store has right now
/v1/taskstasks:readEpinium tasks
/v1/task-itemstasks:readThe items of each task
/v1/skillsskills:readEpinium'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.
  • null is not 0. null means Amazon did not report that figure; 0 means an actual zero. An acos of null is a campaign that spent without selling, not free advertising. And new_to_brand_sales arrives as null on 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 sales includes it where it applies: do not subtract one from the other. margin_before_ads is 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_coverage is 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 is null with any granularity other than total, when the product sold nothing or, when grouping, if group_by does not include the country. With order_by=days_of_coverage&order=asc you 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=salesRanks tells you which category each Best Seller Rank position belongs to, and on Vendor expand=customerFeedback returns 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_by adds up across entities. account gives the account total; country and connection break it down by country or by connection, and they combine by repeating the parameter (group_by[]=connection&group_by[]=country). account does not combine with anything. Rows are still split by currency, since amounts are never converted, and, in advertising, by ad type (SP, SB, SD).
  • granularity splits the range into calendar periods. Besides total and daily it accepts weekly, monthly, quarterly and yearly, and each row carries in date the 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 with monthly returns January from the 15th to the 31st, all of February, and March from the 1st to the 10th.
  • cluster narrows 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=cluster gives one row per cluster. On the same three metrics, group_by=cluster returns the figures of each of your clusters in a single call, with its id in cluster and its name in cluster_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 with country and connection, and with the cluster filter 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.

EndpointWhat it returns
/v1/pnl/cascadeThe 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/productsOne 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/clustersOne row per cluster, with its contribution margin, its cost coverage and how many products it has
/v1/pnl/channelsOne row per sales channel (Seller, Vendor…), with its advertising broken down by platform
/v1/pnl/ads-matrixCross advertising spend: which sales channel each platform advertises on
/v1/pnl/freshnessThe 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-leaksThe 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-mediansWhat 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/inventoryThe 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 currency and 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 the variable_expenses section, before contribution margin, and own_expenses.periods[].variable breaks them down by category. Fixed ones (fixed) are subtracted afterwards, down to net_profit. Since they belong to the whole account, with connection, country or cluster, or with a token that does not reach every sales connection, fixed and net_profit come back null and fixed_unavailable says why: filtered or partial_access. If the account has no fixed expenses nothing is missing, and net_profit comes back even with filters or with a token that does not reach every connection. In the per-product table, the own_expenses column is each product's share of the variable expenses.
  • coverage tells 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_sales over coverage.total_sales tells you what proportion of the figure you can trust. In coverage, estimated_sales is the part of covered_sales with 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 back null -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.
  • cluster narrows /v1/pnl/cascade, /v1/pnl/products, /v1/pnl/clusters, /v1/pnl/freshness, /v1/pnl/margin-leaks, /v1/pnl/category-medians and /v1/pnl/inventory to 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/clusters a product that is in two clusters counts in both, and what is in no cluster does not show.
  • /v1/pnl/margin-leaks returns the products in all three statuses by default, like the screen; status keeps the ones you choose. In the same call, summary gives 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 carries main_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_sales is false: the empty list means there is nothing to compare against, not that there are no leaks.
  • /v1/pnl/inventory is today's stock, with no period: one row per stock, and in the EU a pan-European SKU comes once, with all its countries, so do not add rows up across countries. summary gives the tied-up capital of the whole scope and its split by rotation, without paging and unaffected by rotation and search. currency is 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. The cost field carries cogs and shipping, each with the unit amount, its currency, valid_from and source, or null if it has none. With cost_state you keep the active products with (with cost), missing (no cost) or missing_with_sales (no cost and sales in the last 30 days, the ones that inflate the margin the most), and with include_total you get how many there are. It is the same as what you see in Costs and expenses. On Free and Guru cost comes as null and cost_state responds 403.

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 in error. 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 PAUSED unless you ask for ENABLED explicitly, 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 a state value 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, use state: "PAUSED", which is reversible.
  • Every write requires an Idempotency-Key header. 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>/batch takes up to 1000 entities and answers with one row per entity, in the order you sent them. applied is 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 PATCH changes state and budget and Amazon accepts the first and rejects the second, that entity comes back failed with the reason — calling it applied is how you end up believing a bid moved when it did not.
RouteWhat it does
POST /v1/campaignsCreate a campaign
POST /v1/campaigns/fullCampaign + ad group + targets + product ads in one call
PATCH /v1/campaigns/{id} · POST /v1/campaigns/batchState, daily budget, name and portfolio (the portfolio, Sponsored Products only)
POST /v1/adgroups · PATCH /v1/adgroups/{id} · POST /v1/adgroups/batchCreate; state, default bid and name
POST /v1/targets · PATCH /v1/targets/{id} · POST /v1/targets/batchCreate 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/batchAdvertise 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/adgroups and /v1/product-ads are Sponsored Products only.
  • Sponsored Brands ad groups have no default bid. A defaultBid change 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 accepted targetType depends 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, in failure_details, where reference identifies the target (keyword, ASIN, SKU or the audience, category or location id).
Ad productAccepted targetType
Sponsored ProductsKEYWORD, PRODUCT, PRODUCT_CATEGORY
Sponsored BrandsThose of Sponsored Products plus THEME (themeMatchType KEYWORDS_RELATED_TO_YOUR_BRAND or KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES)
Sponsored DisplayKEYWORD; 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.

RouteWhat it does
PATCH /v1/campaigns/{id}/optimization-configChange a campaign's optimization config
POST /v1/campaigns/optimization-config/batchThe 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 at appliedAt and applyError.
  • A suggestion that nothing knows how to apply is a note. Today, product suggestions and campaign suggestions that carry a fieldPath are 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 with autoApplySkipped: true. It is not an error. When creating, on the other hand, a campaign suggestion with a field other than dailyBudget, state or name, or with a value that cannot be applied, is rejected with a 400: saving it would promise a change nobody is going to make.
  • Suggestions come with the task. Up to 50 in items when 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.
RouteWhat it does
POST /v1/tasksCreate a task, with its suggestions
PATCH /v1/tasks/{id}Title, description, priority and expiry date
POST /v1/tasks/{id}/resolveResolve or discard it
PATCH /v1/task-items/{id} · POST /v1/task-items/batchApprove or reject suggestions, optionally with your own value in appliedValue
POST /v1/tasks/{id}/applyApply what was approved
POST /v1/tasks/listing-optimizationsAsk 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 202 with 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-items filtered by task.
  • 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 with POST /v1/pending-listing-changes/publish, which needs catalog: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 403 whose code is listing_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. products are catalog product ids, Seller or Vendor (/v1/products; advertising ones are not valid). fields takes title, bullets, description and search_terms; without it all four are rewritten. title also 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} takes addPositiveKeywords, removePositiveKeywords, addNegativeKeywords, removeNegativeKeywords, addProducts, removeProducts, addPrompts, removePrompts and name; 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. language is a code like es-ES or en-GB, epiniumScore goes from 1 to 5 and purpose is SEO, PPC or 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. The protected field in the response tells you before you try.
RouteWhat it does
POST /v1/clustersCreate 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 (addPrompts in PATCH /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.
  • fields says which listing fields it applies to: titleAndHighlights (the title and the item highlights, which are written together), product_description, bullet_point or generic_keyword (the search terms). Without fields, or with [], it applies to all of them. An older prompt may still carry item_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} takes name, instruction and fields, and fields replaces the whole list.
RouteWhat it does
POST /v1/promptsCreate 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:

FieldWhat it is
nameBrand or seller name. Required
urlIts website or its Amazon store
asinsThe ASINs of its products that compete with yours, up to 20
threatHow 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_positionIts 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, but competitors, competitor_urls, brand_urls and product_brand_ids are 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 empty competitors.
  • 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.
RouteWhat it does
POST /v1/brand-identitiesCreate 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.

RoutePermissionWhat it does
POST /v1/listing-filescatalog:readUploads the file (.xlsx, .xls or .csv) and returns its file_id. It is kept for 7 days
POST /v1/listing-files/rowscatalog:writeSaves headers and rows you already have as a file, without uploading anything
POST /v1/listing-updates/preparecatalog:readFinds the products in the file by SKU, ASIN or EAN and says which attributes they accept
POST /v1/listing-updates/validatecatalog:readValidates the rows against Amazon's rules for each product type, without saving anything
POST /v1/listing-updates/applycatalog:writeSaves the valid rows as changes pending to publish, in the background
GET /v1/listing-updates/apply/{file_id}catalog:readThe status of that save, what was sent and what it cost

Five things worth knowing before your first call:

  • Nothing reaches Amazon on saving. apply leaves the changes pending to publish, and they go out to Amazon when someone publishes them from Publish changes in Epinium or with POST /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_id arrives in confirmed_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 402 if 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_start or sale_end); clear: true makes its empty cells clear, and date_order (dmy or mdy) sets the order of ambiguous dates. validate returns in offer_clears the price columns with empty cells on products that have that value, and the price rules as blocking offer_* problems. In Vendor no price is edited: those columns come back in not_applicable with the reason vendor_price. prepare offers the price fields in offer_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 requires Idempotency-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.

RoutePermissionWhat it does
GET /v1/amazon-catalog/searchcatalog:readFinds a product in Amazon's catalog by ASIN, EAN, UPC or GTIN, with its restrictions for your account
GET /v1/amazon-product-types/searchcatalog:readRecommends product types from the name of a new product
GET /v1/amazon-shipping-templatescatalog:readThe shipping templates of your Seller account, for an offer you ship yourself
POST /v1/listing-drafts/validatecatalog:readValidates the new listing against Amazon's rules and with an Amazon preview, without saving anything
POST /v1/listing-draftscatalog:writeSaves the new listing as pending to publish
GET /v1/listing-draftscatalog:readYour new listings and their status, with what Amazon answered
DELETE /v1/listing-drafts/{id}catalog:writeDiscards a pending new listing
GET /v1/pending-listing-changescatalog:readWhat is pending to publish, as in Publish changes
POST /v1/pending-listing-changes/publishcatalog:write and catalog:publishPublishes 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 requires catalog:publish and 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.

RouteWhat it does
POST /v1/products/{id}/costsCreates 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. A 0 sets it to zero for real -not the same as not sending the field. At least one of price or shipping_cost is required.
  • A past date recalculates the history. date defaults 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 in recalculation: not_needed with today's date, queued if it enqueued the recalculation, or failed if 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 requires Idempotency-Key.
  • A product with purchases does not accept price. Its product cost is calculated from the recorded purchases, so it responds 409 with the code COST_FROM_PURCHASES. To change only its shipping, send shipping_cost alone, without price: 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.

RouteWhat it does
GET /v1/products/{id}/purchasesThe product's purchases, with the average cost each one left
GET /v1/products/{id}/stock-groupWhich products it shares stock with, or which ones it would be grouped with on its first purchase
GET /v1/purchasesYour purchases, by account and by dates
GET /v1/purchases/{id}One purchase
POST /v1/products/{id}/purchasesRecords 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 responds 400 with PRIOR_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 responds 409 with DUPLICATE_PURCHASE_EXTERNAL_ID instead 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: 400 with STOCK_GROUP_OUT_OF_SCOPE when recording, 404 when 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.

RouteWhat it does
POST /v1/cost-imports/filesUploads 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/previewChecks 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-importsImports 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 with POST /v1/cost-imports/files (.xlsx, .xls or .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 with headers and rows, up to 5,000 rows, if you have not uploaded any file.
  • The columns are the template's (sellerSku, marketplace, date, cogs, cogsCurrency, shippingCost and shippingCostCurrency) 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 with columns. Each row follows the rules of the app's file.
  • Check it first, for free. POST /v1/cost-imports/preview takes 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 date the 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 202 with status: "processing". Query GET /v1/cost-imports/{id} until it says finished, finished_with_errors or error; querying it costs nothing. Rows with a cell longer than the template allows come back in not_sent and 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 409 without 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 402 without 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 requires Idempotency-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.

RouteWhat it does
GET /v1/expensesYour 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/expensesCreates an expense
POST /v1/expenses/batchCreates 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/filesUploads 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}/amountsChanges the amount from a given month; earlier months keep theirs
DELETE /v1/expenses/{id}Deletes it from the whole history
GET /v1/expense-categoriesThe standard categories and yours
POST, PATCH and DELETE /v1/expense-categoriesCreates, 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/batch creates up to 100 at once. dry_run is required: send it first with true, which writes nothing and spends no credits, and then with false. It is all or nothing: if one expense fails none is created, and failure_details says which ones and why. possible_duplicates warns 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, .xls or .csv, up to 8 MB and 1,000 rows) and send its file_id to 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 with columns, and pass in type and currency the type and currency of the rows without them. A row that cannot be read comes back in failure_details as row 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 responds 403, and in the batch that row comes back in failure_details. An expense it cannot see responds 404.
  • 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 requires Idempotency-Key.

Limits ​

  • Metrics require a date range. start_date and end_date are mandatory on every metrics resource.
  • The range has a maximum, and it depends on the granularity. With granularity=daily, 93 days; with total or 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 use limit and offset. In both cases has_more tells you whether another page follows.
  • There is a request limit per token. If you exceed it you get a 429 and simply need to retry more slowly.
  • There is also a limit on concurrent requests. A 429 can mean "too many at once", not just "too many per minute"; a 503 means the server is momentarily at capacity. Both carry Retry-After and both are transient: retry with fewer requests in parallel.
  • A single response cannot expand more than 5,000 objects. expand over lists — a cluster's products, a connection's countries — multiplies at every level. Going over returns a 400 naming how many objects it would have returned: lower limit, drop an expand, 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:

HeaderWhat it is
X-Epinium-Credits-CostWhat this call cost
X-Epinium-Credits-RemainingWhat you have left. It is approximate: if you have other things consuming at the same time, it can drift
X-Epinium-Credits-BreakdownThe breakdown, per resource and unit price: product=100x1,country=100x0
X-Epinium-Credits-MaxThe 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 expand that 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=1 is 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_by instead 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 with group_by=account and 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:

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_credits",
    "message": "insufficient credits: needs up to 366 (campaignMetrics=1x1,campaignMetrics:window=365x1), 120 available. Shorten the date range to 119 days or less.",
    "param": "end_date"
  }
}

param 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.

Epinium Documentation