REST interface

In short

The REST interface lives at /api/v1 and answers GET only. Anything else gets 405 before the server even looks at the key.

Access is proven with a header — see the Overview.

Calls

Endpoint	Scope	What it returns
GET /account/connection	stores:read	Diagnostics of this connection: the app, who granted access and when, granted and missing scopes by area, stores and the AI write mode.
GET /account/entitlements	account:read	The client’s plan, features and limits with current usage.
GET /account/team	team:read	The client’s team: names, roles, active accounts, last sign-in and who manages whom; e-mail only with the personal data permission.
GET /affiliate/articles/:key	affiliate:read	One help article with its HTML wording in all or one language; variables not substituted.
GET /affiliate/articles	affiliate:read	Help-centre articles of the partner portal: key, default/custom, enabled, order, per-language status.
GET /affiliate/campaigns/:campaignId	affiliate:read	One affiliate campaign.
GET /affiliate/campaigns	affiliate:read	Affiliate campaigns of a shop with reward, availability and counts.
GET /affiliate/code-requests	affiliate:read	Partner requests for a custom discount code with state and reason; pending first.
GET /affiliate/conversions/:conversionId	affiliate:read	Detail of one conversion: amounts, commission, commission state with reason, order status in the shop, credit note, payout.
GET /affiliate/conversions	affiliate:read	Affiliate conversions of a shop: commission base and order total incl. VAT, commission, commission state with reason, order status in the shop, link to the payout.
GET /affiliate/discount-codes	affiliate:read	Partner discount codes on a shop with usage count and revenue.
GET /affiliate/documents/:key/content	affiliate:read	One legal document of the programme with wording per language (stored text, public wording, version, hashes, source, PDF metadata) and open drafts.
GET /affiliate/documents	affiliate:read	Programme documents (terms, agreements): confirmation policy, signed copy, e-mail attachment, versions per language, readiness and acceptance counts.
GET /affiliate/email-templates	affiliate:read	Partner e-mail templates per language (subject, enabled, body with an event) and automatic attachments of the Account approved e-mail.
GET /affiliate/links/generate	affiliate:read	Tracked affiliate link to the campaign shop home, a product or a category; keeps partner attribution after the click.
GET /affiliate/partners/:partnerId	affiliate:read	One programme partner with the campaigns available to them.
GET /affiliate/partners	affiliate:read	Programme partners with state, performance and commissions; contacts only with personal data.
GET /affiliate/payouts	affiliate:read	Commission payouts to partners with state; without bank and billing data.
GET /affiliate/portal	affiliate:read	Public partner portal: addresses per shop, registration openness with reason, custom domains, contact person, appearance and text status per language.
GET /affiliate/settings	affiliate:read	Affiliate programme settings: commissions, clicks, payout minimum, referrals.
GET /affiliate/signatures/:signatureId	affiliate:read	One electronic signature with the signed wording and value snapshot; an immutable record, the PDF is generated in the app.
GET /affiliate/signatures	affiliate:read	Electronically signed partner documents (who, document, version, language, store, time, method, verification, hashes, state) and partners with a missing signature; read only — a signature is created solely in the portal.
GET /affiliate/statistics	affiliate:read	Affiliate statistics: daily timeline, attribution sources, partner ranking.
GET /affiliate/summary	affiliate:read	Affiliate programme overview of a shop for a period: clicks, conversions, commissions, partners.
GET /affiliate/variables	affiliate:read	Registry of content and e-mail variables of the partner programme: canonical names, aliases, type, surfaces, example; optional text check for unknown variables.
GET /analytics/advertising	reports:read	Advertising: spend, budget, ROAS, cost of sale, CPA, average order value and MER with comparison; Google Ads, Meta Ads and OpenAI Ads, clicks from GA4, 6 months.
GET /analytics/channels	analytics:read	Traffic channels including ChatGPT and other AI sources.
GET /analytics/comparison	reports:read	Revenue with comparison: revenue, orders, AOV, sessions, CR and AI/LLM against the previous period or year.
GET /analytics/daily	reports:read	Revenue and orders by day (up to 92 days), total across shops or one shop.
GET /analytics/funnels/catalog	analytics-funnels:read	Events, parameters and user properties from the shop GA4 for setting up a funnel.
GET /analytics/funnels/:id	analytics-funnels:read	A funnel for a period: step visitors from GA4, purchases and revenue from orders, split by channel, comparison.
GET /analytics/funnels	analytics-funnels:read	GA4 funnels (for example a website quiz): steps, visitor marker, status and last import.
GET /analytics/monthly	reports:read	Revenue, orders and sessions by month (up to 24), for example year over year.
GET /analytics/order-coverage	analytics:read	Order coverage by tracking; without a shop, the total across shops and a per-shop breakdown.
GET /analytics/order-heatmap	reports:read	When orders come in: day of week × hour, busiest day and hour.
GET /analytics/overview	analytics:read	Visits, orders, revenue, conversion rate, AOV, share of AI sources.
GET /analytics/revenue-sources	reports:read	Where revenue came from: channels, AI/LLM, MitoOps and affiliate subtotals, GA4 acquisition breakdown.
GET /analytics/seo	analytics:read	Search Console by query or page.
GET /approvals/pending	approvals:read	What awaits a person’s approval: AI steps in the AI change log and AI suggestions.
GET /automations/catalog	automations:read	Automation catalogue: triggers, condition fields, operators, actions, templates and catalogVersion.
GET /automations/:workflowId	automations:read	One automation with DSL and validation result.
GET /automations	automations:read	The client’s automations with state and shop scope.
GET /automations/options	automations:read	Option list for an automation field (statuses, shipping, payments, templates, claims…): the DSL value and a name.
GET /automations/:workflowId/runs	automations:read	Run history of one automation.
GET /automations/templates	automations:read	Ready-made automation templates with DSL.
GET /campaigns/discount-compute	campaign-rules:read	Real discount off the full price for a sale and a code (they multiply), or the missing part for a target discount; compared with the store limit.
GET /campaigns/discount-rules	campaign-rules:read	Discount rules of the stores: whether the limit is on, the maximum combined discount off the full price, scope, mode and partner commission.
GET /chatbot/conversations/:sessionId	chatbot-conversations:read	Transcript of one web chatbot conversation including the sources of the bot’s answers.
GET /chatbot/conversations	chatbot-conversations:read	Customer conversations with the web chatbot from the most recently active, with the first question; cursor.
GET /chatbot/outcomes	chatbot:read	How web chatbot conversations ended: since when the outcome is measured, measured and unmeasured conversations, known and unknown outcome, resolved, unresolved, bot error and resolution rate with its denominator; N/A with a reason when the denominator is zero. Totals only.
GET /chatbot/stats	chatbot:read	Web chatbot statistics for a period: the teaser funnel from a single measurement (older counts come alongside as historical), chat open rate, conversations, conversation-level outcome, ratings.
GET /chatbot/topics	chatbot:read	What the conversations were about: topic shares from a closed taxonomy, resolution rate and knowledge-gap candidates per topic, the most frequent products, the start page type and a day-by-day trend. Shares are computed from the analysed conversations and that count is returned too. Totals only.
GET /claims/config-drafts/:draftId	claims-settings:read	Status of a proposed claim settings change (pending, written, rejected).
GET /claims/configuration	claims-settings:read	Claim settings: tags, fields, return shipping, the shop form and form types.
GET /claims/deadlines	claims:read	Open claims by deadline: overdue and due soon, most urgent first, with counts per shop.
GET /claims/:code	claims:read	One claim with items, refunds, return shipments, tags, timeline and sent e-mails.
GET /claims	claims:read	Claims and returns of one shop with links to the order.
GET /claims/refund-options	claims-settings:read	Refunds: variable symbol source, refund coupon validity, coupon in the form, when the form asks for an account number.
GET /claims/:code/refund-readiness	claims:read	Claim before a refund: what the customer requests, masked account, variable symbol, mode and whether the claim can be deleted.
GET /claims/refund-settings	claims-settings:read	Claim refunds: mode, bank accounts with payment-order eligibility (masked), default and manual account.
GET /claims/routes	claims-settings:read	Claims return shipping: routes, addresses, carrier profiles with IDs and return support, case types.
GET /claims/settings	claims:read	Claim processes with IDs and names (types, steps, statuses, deadlines), tags; module settings with the claims-settings:read scope.
GET /claims/statistics	claims:read	Claims and returns statistics for a period: counts, resolution times, types, ratings, reasons.
GET /claims/templates	claims-settings:read	Claim e-mail templates (subject, text, when and whether they are sent automatically) and document templates.
GET /content/articles	products:read	Blog articles and shop content from the canonical mirror by title or text.
GET /coupons/activation-link	coupons:read	A link that applies an EXISTING coupon in the customer’s cart. Does not create coupons.
GET /coupons/activation-status	coupons:read	Whether a coupon can be used on the shop via the activation link: coupon mirror + web code status.
GET /coupons/capabilities	coupons:read	What the shop’s platform can do with coupons. Read before creating.
GET /coupons/:code	coupons:read	One coupon by code.
GET /coupons	coupons:read	The shop’s discount coupons with discount type and amount, validity and derived state.
GET /coupons/web-box	coupons:read	Price-after-code boxes next to products on the shop: main switch, coupons, settings and state.
GET /coupons/web-box/stats	coupons:read	Box views, code copies and cart applications by coupon and product.
GET /customers/:customerKey	customers:read	One customer from the directory — identity, shops, lifetime and optional period money, broken down per shop.
GET /customers	customers:read	Customer directory: identity (with personal-data masking), shops, language, lifetime counts and revenue by currency; optional purchase-activity filter for a period.
GET /customers/performance	reports:read	Customers as pseudonyms: orders, revenue, LTV, new and returning.
GET /credit-notes	invoices:read	Search in credit notes.
GET /documents	invoices:read	Accounting documents of one type (invoices, proforma invoices, credit notes) page by page with lifecycle, source state, validity filter and PDF availability.
GET /documents/:documentType/:code/pdf	invoices:read	PDF of an invoice, proforma invoice or credit note (base64 and SHA-256), the same bytes as on screen.
GET /invoices/:invoiceCode	invoices:read	One invoice with document items, credit notes, proforma invoices and the order number.
GET /invoices	invoices:read	Search in invoices; a payment filter (paid, unpaid, overdue) with count and total per shop.
GET /payments/matching	payments:read	Matching of received payments to orders: counts by result and unmatched, ambiguous and failed payments.
GET /inventory/movements	inventory:read	History of stock movements: when, what, how much, kind, origin, order.
GET /inventory/availability	inventory:read	Stock level of several items at once.
GET /inventory/product-statistics	inventory:read	Per product for a period: stock level, units sold, units claimed as faulty and returned, claim rate.
GET /inventory/stock	inventory:read	Stock level of one item including the source of the value.
GET /inventory/sync-status	stock-sync:read	Stock synchronisation status between shops: queue, conflicts, last run and reconciliation, mapping, connection health.
GET /inventory/valuation	inventory:read	Stock value as on screen: purchase and sale value, gross and net potential, below minimum, negative, largest items; without sets and bundles.
GET /messaging/deliveries	messaging:read	Delivery of e-mails about shipments, orders, claims and partners: summary, statuses and errors (bounced, spam, blocked).
GET /notifications	notifications:read	Notifications from the bell: what modules report, severity, status, unread count and the screen that resolves it.
GET /orders/:orderCode	orders:read	One stored order including items.
GET /orders/:orderCode/line-discounts	orders:read	Historical prices and discounts per order line: original price, discount, coupon, amount paid and confidence.
GET /orders	orders:read	Stored orders, newest first; status filter, search, payment, period and the full count in the filter.
GET /orders/packing-queue	orders:read	Packing queue by the statuses the client set as ready to pack: count and orders per shop.
GET /availabilities/drafts/:draftId	products:read	Status of a proposed availability list change: awaiting approval, written with a result, rejected, expired.
GET /availabilities/history	products:read	Availability synchronisation history: what was carried from which shop to which, with the result; period, cursor.
GET /availabilities	products:read	The shop’s availability list: name, description, restock and delivery time, Google meaning, colour, default role.
GET /availabilities/pairing	products:read	Availability matching between shops: rows with each shop’s item, suggestions, unmatched items, synchronisation status.
GET /availabilities/pairing-drafts/:draftId	products:read	Status of a proposed availability matching change: awaiting approval, saved, rejected, expired.
GET /catalog/category-content-drafts/:draftId	category-content:read	Status of a category text proposal: awaiting approval, written, rejected, expired.
GET /categories/:guid/content	category-content:read	A category’s texts (top and bottom description, SEO title and description) with a hash and field writability.
GET /categories/:guid	category-content:read	One category with live state from the shop including visibility (true/false, null = the platform does not track it) and from–to schedules.
GET /categories	products:read	Shop categories with product counts, paged with a full count.
GET /categories/:guid/products	products:read	Products assigned to a category, paginated, live from the shop (during an outage from the mirror with the source marked).
GET /categories/visibility-plans	category-content:read	Category from–to visibility schedules: time, state, original visibility, last write and error.
GET /product-logistics/:code	product-logistics:read	Weight and dimensions of a variant’s sales packaging live from the shop (kg, cm), inherited fields, revision and recent writes.
GET /product-logistics/missing	product-logistics:read	Shop codes without weight or dimensions (or with unverified units); with codes, values from the copy with source and certainty.
GET /products/:code/categories	products:read	All categories of a product per shop, live from the shop: main and additional assignments including hidden categories.
GET /products/changes	products:read	Product card change log: field, shop, when, where from and a preview of the old and new value; prices only with permission.
GET /catalog/product-content-drafts/:draftId	product-content:read	Status of a product text proposal: awaiting approval, written with shop warnings, rejected, expired.
GET /products/:code/content	product-content:read	A product’s texts from the shop (description, short description, SEO title and description) with a hash and field writability.
GET /product-content/policy	product-content:read	Content policy for a shop without calling the shop: what this access may read and propose, which fields the platform writes, the approval mode and autonomous writing, limits and hashes.
GET /products/:code	products:read	One product by code including category and the price from the card.
GET /products/:code/offer	products:read	The product offer in the shop: whether the shop still has it, visibility, orderability, availability and the price with currency, VAT and the price in the shop’s selling currency.
GET /products	products:read	Product search by name, code, EAN or PLU; category, active and below-minimum filters with a full count; shop state, products deleted in the shop only on request.
GET /products/:code/visibility	products:read	Live product state per shop: visibility (including the raw platform state), orderability and indexability read-only, running from–to schedule.
GET /catalog/products/visibility-plans	products:read	Product from–to visibility schedules: time, state, original shop state, last write, error and the last scheduler run.
GET /reports/cost-groups	reports:read	Cost categories and tags and the group layout in Costs.
GET /reports/costs	reports:read	Manual and automatic costs with the amount counted in the period; company-wide and per shop.
GET /reports/financial-summary	reports:read	Financial summary of a period; with purchase-prices:read also cost of goods, gross profit and margin.
GET /reports/history/:runId	reports:read	Status of one export and its files with the REST download address.
GET /reports/history	reports:read	History of generated reports with files, size and SHA256.
GET /reports/layout	reports:read	Report export layout: cover, order and inclusion of sheets and sections, page breaks.
GET /reports/notes	reports:read	The report note that goes into the Word and PDF report.
GET /reports/order-status-rules	reports:read	Which order statuses count towards revenue, per shop, with the count and revenue in each status.
GET /reports/summary-all	reports:read	Summary of several shops as with “All”: total, breakdown per shop, company-wide costs once, computedAt and dataAsOf.
GET /sales/order-performance	reports:read	Revenue per order with totals for the whole period; with purchase-prices:read also cost, profit and margin.
GET /sales/product-performance	reports:read	Sales per product with totals for the whole period.
GET /reviews/:kind/:reviewId	reviews:read	One review with its reply history, the shop’s language, tone and signature, and a pending proposed reply.
GET /reviews	reviews:read	Shop and product reviews of one shop: stars, text, product, the shop’s reply, a pending proposal; filters and period.
GET /reviews/reply-drafts/:draftId	reviews:read	Status of a proposed review reply: awaiting approval, published, rejected, expired.
GET /reviews/statistics	reviews:read	Review statistics of a shop for a period: count, unanswered, average, count by stars and by kind.
GET /reviews/web-display	reviews:read	Review block on the product page (website script): whether it is on, platform support and settings.
GET /search-console/query	search-console:read	Search Console by day, query, page, country and device, with pagination and a content hash.
GET /search-console/status	search-console:read	Search Console status of a shop: connection, property, permission level, sync and archive range.
GET /shipping/carriers	shipping:read	Connected carriers and profiles, without credentials.
GET /shipping/overview	shipping:read	Shipping overview: to pack, awaiting hand-over, in transit, carrier errors, cash on delivery, broken down per shop.
GET /shipping/packing-performance	shipping:read	Packing performance per person: orders packed, packing time (average and median), time to pack and to hand-over, comparison with the team.
GET /shipping/pickups	shipping:read	Courier pickups per carrier: order-by and latest pickup time, what is waiting for pickup and booked pickups.
GET /shipping/returns	shipping:read	Return shipments with status and claim, totals in transit and open per shop.
GET /shipping/shipments/:shipmentId	shipping:read	One shipment with all tracking events.
GET /shipping/shipments	shipping:read	Shipments with carrier, country, hand-over and delivery time, paged.
GET /shipping/stats	shipping:read	Delivery statistics per carrier: counts, success rate, median and p90 delivery time, countries.
GET /stores/integration-status	stores:read	MitoOps web code status per shop: installed, version, modules, readiness of coupon-from-link.
GET /stores	stores:read	The client’s shops with their code.
GET /purchasing/advisor	purchasing:read	Purchase proposal: what to reorder and how much, urgency, stock, minimum and projected need; globally for one warehouse.
GET /suppliers/:supplierId	purchasing:read	One supplier with offers and cost components.
GET /suppliers	purchasing:read	Suppliers with offers and cost components, paged with a full count.
GET /webhooks/endpoints/:endpointId/deliveries	webhooks:read	Delivery log of one endpoint without bodies.
GET /webhooks/endpoints/:endpointId	webhooks:read	One webhook endpoint with the number of pending deliveries.
GET /webhooks/endpoints	webhooks:read	The client’s webhook endpoints without secrets and the queue state.
GET /webhooks/events	webhooks:read	The catalogue of outbound webhook events, envelope and signature.

Endpoint	Scope	What it returns
GET /capabilities	—	what this key is allowed to call
GET /openapi.json	—	the machine-readable contract

GET /capabilities is the fastest way to find out what a key opens — it returns exactly what its scopes allow, not the whole catalogue. The exact parameters and response fields of every call are in openapi.json.

Response shape

Every response has two parts: data and meta.

{
  "data": [ { "market": "sk", "name": "My shop" } ],
  "meta": { "requestId": "…", "count": 1, "hasMore": false, "nextCursor": null }
}

meta.requestId identifies the call. If something goes wrong, it is the value that tells support which call you mean.

Pagination

Ask for the next page by sending the nextCursor from the response back in the cursor parameter. Every other parameter must stay the same — a cursor belongs to the query it came from, and with a different store or period the interface rejects it (400). Tell the end by hasMore, not by the number of records returned. An invalid cursor is an error, not an empty result: an empty response would look like the end of the data and an export would quietly come up short.

There are deliberately no page numbers: when a record is added between two calls, “page 2” no longer points where it did a moment ago.

Listing and searching

For products, invoices and credit notes these are two modes of one address: without query you get a page-by-page listing, newest first (paginated, and it can be restricted by period); with query you get a search ordered by relevance (at most limit records). Search is neither paginated nor restricted by period — combining query with cursor, from or to returns 400 rather than silently ignoring the filter. To read out the whole record set, use the listing without query.

Period

Orders, documents, shipments, statistics, analytics and reports can be restricted with from and to in YYYY-MM-DD form.

• Both bounds are inclusive. to=2026-08-05 covers all of 5 August, not midnight at its start.
• The day is taken as the store sent it — in its own time zone, the same way staff see it in the application.
• Orders are ordered by the date the order was placed, shipments by the date the shipment was created.
• Invoices and credit notes by the tax date; where a document has none, by its issue date. This is the same semantics the application uses to assign documents to periods. Which value placed the document is visible in the businessDate field.
• Sales per product by the document date; here the period is required.
• The longest period is 366 days. Anything longer is rejected.
• Without a period shipments and statistics return the last 30 days, analytics and the financial summary the current month. The response always states the period.
• A reversed period is an error, not an empty result — otherwise a typo would look like a period with no documents.

Orders still accept todayOnly. It cannot be combined with from/to: they are two answers to the same question.

What the financial fields mean

• purchasePriceWithoutVat on an order item is the purchase price at the time of the order, as the shop stored it. It is not the price from today’s product card — that one is purchasePrice in products/{code}.
• cogs in the financial summary is the cost of goods for the period from all orders; null means purchase prices are not known for enough lines (cogsCoverage). Gross profit is then not shown either — nothing rather than a wrong figure.
• grossProfit is revenue without VAT minus cost of goods, grossMargin the same in percent. resultAfterCosts is gross profit minus shipping minus company costs — a management figure, not accounting profit.
• In sales per product, purchaseCostWithoutVat is the purchase cost at document time from matching with the catalogue; unmappedLines says how many lines did not match.
• All report and analytics amounts are in EUR (field currency), converted at the rate at sync time. Orders and documents carry their own currency.

Without the purchase-prices:read scope these fields are absent from the response — not zero, absent.

Delivery time

Delivery statistics (shipping/stats) measure the time from hand-over to the carrier to the first delivery event in the tracking events. Nothing is computed from the order date. A shipment lacking either point is not counted in the median; delivery.measured says how many were. Every shipment carries the same two times in handedOverAt and deliveredAt.

deliveryRate is the share of delivered shipments among those whose fate is settled (delivered, returned, failed). A shipment in transit is neither a success nor a failure yet; a cancelled shipment is your action, not the carrier’s failure, and is not counted at all.

Stock levels

inventory/stock returns quantity and source — which stock model the value comes from (variants, the shop’s balance, the product card). When the shop keeps a balance, physical, available (available for sale) and reserved (reserved in orders) are available too; otherwise they are null. The interface invents no “on hand” figure the application does not keep.

Stock levels (inventory/stock and inventory/availability, scope inventory:read) say how much of a product there is; the availability list (/availabilities, scope products:read) holds the named states a shop shows customers next to a product, such as In stock or Backorder.

Product statistics

GET /inventory/product-statistics?market=sk&from=2026-01-01&to=2026-10-24 (scope inventory:read) returns the products of one shop in data: code, name, ean, active, stockQuantity and stockSource (as in inventory/stock), soldQty (units sold, i.e. stock issued against an order number) and, with the claims:read scope, also claimedQty (units claimed as faulty), claimCases (number of cases), claimRatePercent (claimed / sold × 100, null without sales), claimRateReliable (false below 20 units sold), returnedQty (returned without a defect), claimedRestockedQty and claimedNotRestockedQty. meta.totals cover the whole filter and also carry unmatchedClaimedQty and unmatchedReturnedQty, units in cases that could not be matched to a product.

A claimed unit is an item of a case of the claim type, or an item returned because it is faulty or damaged in transit. An ordinary withdrawal from the purchase, a return or an exchange without a defect is a returned unit. A rejected item is not counted, and a case belongs to the period by the date it was created. Without the claims:read scope the claim fields are absent from the response (not zero) and the withClaimsOnly=true filter returns an error. Without a period the current year applies and the window is at most 366 days; paging uses limit and cursor.

Availability list

GET /availabilities?market=sk returns the entries of one shop’s list in data: id, name, description, onStockHours, deliveryHours, meaning (the Google Shopping meaning: in_stock, backorder, preorder, out_of_stock), color, system, defaultRoles (the default role in the shop) and pairingRows (in how many availability matching rows the entry appears). meta carries market, manageable and reason: whether the list can be changed from MitoOps and, if not, why (PLATFORMA, BEZ_ROZSIRENIA, PROSTREDIE).

The list cannot be changed over REST. Only an assistant over MCP can prepare a change, as a proposal under the sensitive availabilities:draft scope, and a person writes it to the shop by approving it in the app. You can read the status of such a proposal over REST: GET /availabilities/drafts/:draftId returns the status (pending, writing, executed, partial, failed, rejected, expired), the preview and, after approval, the per-item result. Details are in the MCP interface.

Customer directory

Customers have two different reads, and mixing them up means reading a different number than you expect:

• /customers and /customers/{customerKey} (scope customers:read) are the directory: the same projection the staff sees on the Customers screen and the one that goes into the export — identity, shops, country, language, counts and dates.
• /customers/performance (scope reports:read) is analytics over raw orders: the customer is only a pseudonym, with no name or contact in it at all.

From outside, market is required for both. Without it the read would span every shop of the client, including the ones this access does not cover.

Who sees what

customers:read on its own returns the pseudonym (customerKey), shops, country, language, order counts and the dates of the first and last order. On top of that:

• name, company, e-mail, phone and marketing gender only with personal-data:read,
• revenue, average order and LTV only with reports:read.

Fields you have no scope for are removed, not zeroed. A null where the e-mail sits would mean “this customer has no e-mail”, which is not true — a missing key means “you have no right to it”.

customerKey is the SHA-256 of the normalised e-mail. It is the same pseudonym that documents carry (customerEmailHash) and that /customers/performance uses, so the three views can be joined without sending an e-mail address anywhere.

Lifetime versus period

The directory has an optional purchaseFrom / purchaseTo filter (YYYY-MM-DD, both bounds inclusive). It means purchase activity in the period: the customer has at least one order in that interval. It is not a filter on the date of the first or last purchase.

With a period, the fields periodFrom, periodTo, periodOrdersCount and periodRevenueByCurrency appear next to the lifetime ones (ordersCount, revenue, lifetimeRevenue, firstOrderAt, lastOrderAt) — never instead of them. Lifetime values do not change with the period.

Money is always per currency

Revenue, average order and LTV are an array per currency, never a single number. A customer with orders in both EUR and CZK has two entries; adding them into one scalar would mean adding korunas to euros. The same holds for /customers/performance: a row is a (customer, currency) pair and the filter totals are totals.revenueByCurrency.

Language and marketing gender

• language is the language of the shop the customer ordered from (source: "store_locale"), not their own choice. The application does not record an explicit language preference of the customer today.
• marketingGender (male / female / unknown) is an inference from the first name, not something the customer stated. The origin is always in genderSource — today exclusively name_inference or unknown — and the confidence in genderConfidence. A company customer does not have the field. Anyone displaying it further should say “inferred from the name”, never “the customer stated”. It sits behind personal-data:read just like the name itself.

Shop

Calls over a single shop’s data require its code in the market parameter. GET /stores returns the list of codes.

When the key has no scope for that shop the answer is 403 — not an empty list. An empty list could not be told apart from a shop with no orders. A record of another shop (for example a shipment) is 404.

Errors

An error response always has the same shape and carries a code. The list of statuses is in the Overview.

Examples

# Orders for a period, paged
curl -H "Authorization: Bearer <your key>" \
  "https://<your address>/api/v1/orders?market=sk&from=2026-08-01&to=2026-08-31&limit=50"

# Delivery statistics for August
curl -H "Authorization: Bearer <your key>" \
  "https://<your address>/api/v1/shipping/stats?market=sk&from=2026-08-01&to=2026-08-31"

# Financial summary of August (with the purchase-price right also gross profit)
curl -H "Authorization: Bearer <your key>" \
  "https://<your address>/api/v1/reports/financial-summary?market=sk&from=2026-08-01&to=2026-08-31"

# Stock levels of three items
curl -H "Authorization: Bearer <your key>" \
  "https://<your address>/api/v1/inventory/availability?market=sk&codes=A100,A101,A102"

# The shop's availability list
curl -H "Authorization: Bearer <your key>" \
  "https://<your address>/api/v1/availabilities?market=sk"

Related

• Overview
• MCP interface