# Fluit Headless Commerce API

> The commerce API behind Fluit's own storefront, available for your own front end.
> Catalogue, search, pricing, cart, checkout and the signed-in customer's pages — the same
> endpoints our storefront calls, reading the same ERP that runs the warehouse and the
> ledger. There is no separate commerce database to keep in sync: stock is the stock, the
> price is the price a salesperson would quote, and an order placed here is an order in
> Fluit.

- Base URL: `https://api.erp.fluit.cloud` — the paths listed below already include the `/ecom` prefix.
- Authentication: send the tenant in the `X-Tenant-Id` header and the storefront in `X-Channel` on every request, plus a session token from GET /ecom/session as `Authorization: Bearer` on everything that concerns a visitor.
- Version: `v1`.
- OpenAPI document, with the complete request and response schemas: https://api.erp.fluit.cloud/swagger/ecom/swagger.json
- Reference documentation for humans: https://fluit.se/api-docs/commerce-reference
- Contact: info@fluit.se

## Getting started

Three calls get you from a domain name to a product listing.

**1. Resolve the domain to a tenant and a channel.** This is the only call that needs no
headers — it runs above tenant context and exists to establish it.

```bash
curl "https://api.erp.fluit.cloud/ecom/session/resolve?domain=shop.acme.com"
# { "tenantId": "…", "channelCode": "web", "channelName": "Acme Web" }
```

You can skip this call and configure the tenant id and channel code directly if you know
them. It exists for the multi-domain case, where one deployment serves several storefronts
and the domain decides which.

**2. Open a session.** The response carries the token you send from here on, plus the
channel's full configuration: currency, language, feature flags, branding, navigation and
SEO settings.

```bash
curl "https://api.erp.fluit.cloud/ecom/session" \
  -H "X-Tenant-Id: $FLUIT_TENANT_ID" \
  -H "X-Channel: web"
# { "token": "…", "expiresAt": "…", "isAuthenticated": false, "cartItemCount": 0, "channel": { … } }
```

**3. Call everything else** with the tenant, the channel and the session token.

```bash
curl "https://api.erp.fluit.cloud/ecom/catalog/products?pageSize=20" \
  -H "X-Tenant-Id: $FLUIT_TENANT_ID" \
  -H "X-Channel: web" \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

## Tenants and channels

Two headers scope every request.

`X-Tenant-Id` selects the company. It is a GUID, and it is not a secret: this surface only
ever returns what the channel has published, so knowing the id gets you the same catalogue
a visitor sees in the browser. Everything that is not public — cost prices, other
customers, the ledger — lives behind endpoints this API does not have.

`X-Channel` selects the storefront within that company. A channel owns its assortment,
price list, currency, language, VAT display and branding, so the same item can be
published in two channels at different prices under different names. **Omitting the header
falls back to the first active channel**, which is convenient in a single-channel tenant
and a silent source of wrong prices in a multi-channel one. Send it explicitly.

Channel codes come from the domain resolution above, or from the channel settings in Fluit.

`X-Language` selects the language for translated content, as an ISO 639-1 code (`sv`,
`en`). It is optional and forgiving: omit it, or send a language the channel does not
publish, and you get the channel's default — never an error. The channel decides which
languages exist, and the session response lists them in `channel.languages` alongside the
resolved `channel.language`.

It applies to the endpoints that actually return translated text — the session, the
category tree, filters, product lists, product detail, search, type-ahead and the shopping
assistant. Each operation's parameter list says whether it takes the header. Note that
every cacheable response varies on it regardless, so a shared cache in front of us can
never mix languages between visitors.

## Sessions

`Authorization: Bearer` carries an `EcomSession` token. It is an opaque handle, not a JWT
— do not try to decode it, and do not expect claims inside it.

A session is not a login. `GET /ecom/session` issues one to an anonymous visitor, and that
anonymous session carries a cart. Signing in through `POST /ecom/auth/login` or the
one-time-code endpoints upgrades the session in place, so the cart survives the login and
prices switch to the customer's agreement prices in the same moment. `isAuthenticated` on
the session response tells you which state you are in.

Anonymous is not the same as tokenless. The cart belongs to the session, so every cart,
checkout and customer-portal call needs that token even before anyone has signed in —
without it they answer `401`. The sign-in endpoints need one too, because signing in
upgrades a session that must already exist. Get the token first, then use it throughout.

Three groups work without a token: catalogue and content read the same for everyone, and
`GET /ecom/session/resolve` runs before there is a session to have. Two more take one when
offered and answer anyway without it: `GET /ecom/catalog/prices` and
`GET /ecom/catalog/stock` fall back to list prices and channel-level stock. Each
operation's `security` says which case it is.

Sessions live for seven days and extend themselves as they are used. `POST
/ecom/auth/logout` ends one early, and ending it is the only thing that makes the token
stop working — dropping your copy of it stops *you* from sending it, but the token stays
valid for whoever else has one until it expires on its own. On a shared device, or after
a token has been anywhere you did not intend, that difference is the whole point. Call it
before you clear your cookie or your token store, because afterwards you no longer have
the token the call needs.

It is idempotent: a token that is already ended, expired or simply unknown answers `204`
too, so a retry after a lost response, or two browser tabs signing out at once, needs no
special handling. Only a request with no `Authorization` header at all is an error.

The cart hangs off the session and goes with it. The next session starts empty whether or
not the visitor signs back in — which is what you want on a shared device, and worth
knowing if you meant to keep something.

Requests from crawlers are recognised by user agent and served without persisting a
session, so indexing a catalogue does not fill the session table.

## Accounts

There is no `POST /ecom/auth/register`, and its absence is a design decision rather than
a gap. A customer in Fluit is a record in the ERP that a salesperson may hold an agreement
and a price list against — not a row a visitor creates by filling in a form.

Accounts come into being two ways:

- **At checkout.** Send `createAccount: true` and a `password` on
  `POST /ecom/checkout/place`. The order creates the customer if the e-mail is new, and
  the account is attached to it. The two fields work only together: `createAccount`
  without a password creates no account and reports no error — and on a channel with
  `guestCheckout: false` the order is then rejected as a guest order, which is the
  confusing way to discover it. Send both or neither.
- **In the ERP.** A salesperson creates the customer and invites the contact. This is the
  normal path in B2B, where the account follows an agreement that was negotiated
  somewhere other than a web form.

Three channel settings decide what your checkout must offer, and all three are on the
session response under `channel.features`:

| Setting | When true |
| --- | --- |
| `requireLogin` | Only signed-in customers can order. Neither guests nor `createAccount` get through — offer sign-in, not a registration form |
| `guestCheckout` | Ordering without an account is allowed. When false, the visitor must either sign in or pass `createAccount` |
| `showPricesWithoutLogin` | Prices are visible to anonymous visitors at all |

`GET /ecom/checkout/data` returns `requireLogin` and `guestCheckout` too, so the checkout
page does not have to carry them from the session.

A customer who has an account but no password — invited from the ERP, or simply someone
who forgot — signs in with a one-time code: `POST /ecom/auth/request-code` followed by
`POST /ecom/auth/one-time-login`. That is the way back in, and it is worth offering
alongside the password field rather than only behind a "forgot password" link.

## Architecture: calling from your own server

The intended shape is server to server. Your front end calls your own backend, and your
backend calls Fluit — holding the tenant id, the session token and any customer
credentials on your side, and exposing to the browser only what that page needs.

This is how our own storefront is built. It is a SvelteKit app whose pages load through
server routes, with a thin set of proxy endpoints under its own origin for the calls that
have to happen after hydration. The browser never talks to this API directly.

**CORS does not stand in your way.** Browser requests are accepted from any origin — no
allow-list, nothing to ask us for. That costs nothing to give: this surface is already
callable anonymously from any server, and returns only what the channel has published, so
CORS was never what protected it. It only ever constrained browsers, which meant it only
constrained the clients doing what we recommend.

Because authentication is a bearer header and never a cookie, the policy sends no
credentials. Do not expect cookies to ride along on a cross-origin call, and do not put
anything in one.

Five response headers are exposed for JavaScript to read: `ETag` (without it you cannot
revalidate — see *Caching*), `Retry-After`, `Location`, `Idempotency-Replayed` and
`Content-Disposition`. Everything outside that set and the CORS safelist is invisible to a
browser client, whatever the server sent.

Server to server is still the shape we recommend, for the reasons above rather than
because the browser path is blocked.

Two practical consequences of proxying:

- Forward the visitor's address in `X-Forwarded-For`, and prove that you may by sending a
  storefront key in `X-Fluit-Storefront-Key`. Create the key under *Settings → API keys*
  with the storefront permission; a full-access key does not carry it. With the key, the
  rate limiter partitions on the forwarded address. Without it, the header is ignored and
  every visitor shares your server's quota, because anyone can call this API and anyone
  could otherwise pick a fresh address per request. Keep the key on your server; it never
  belongs in a browser.
- Cache what does not change per visitor — but you do not have to work out which is which.
  Every response says so itself in `Cache-Control`. See *Caching* below.

## Pages, website mode and forms

**Website mode.** A channel can be a plain website without a shop. The session response
says so in `features.commerceEnabled`. When it is `false`, every commerce surface answers
`404` with a problem body — catalog, products, cart, checkout, payment callbacks,
accounts, the portal, postal-code lookup and the shopping assistant — so a website cannot
take an order through the API either. Pages, the home page, navigation, forms, the
newsletter and articles work as usual.

**Pages live at the root.** A content page's address is its parents' slugs plus its own —
`/about`, `/services/tyre-change` — and the home page is `/`. Resolve an incoming path with
`GET /ecom/pages/resolve?path=/services/tyre-change`: the page, or `404`. The last segment
identifies the page, so a stale path — a page moved under another parent, or the old
`/pages/{slug}` address — still finds it; compare the response's `canonicalPath` with the
requested path and redirect permanently when they differ. A renamed slug leaves a URL
redirect behind, like a renamed product. `navigation.reservedSlugs` in the session lists
the first path segments that are never pages (`cart`, `checkout`, `products`, `blog`, …),
so a router can send those to the shop before asking the page API.

**Sections.** A page and the home page are lists of sections with a `type`. Every section
has the same heading fields (`eyebrow`, `title`, `subtitle`, `buttons`, `tone`, `spacing`,
`alignment`, `anchor`) plus fields for its own type. Button targets are resolved to
addresses on the server. Reusable section collections are expanded in place — a client
never sees a collection reference. Treat an unknown `type` as "skip this section": new
types are added without a version change.

**Products in a section.** The product sections (`FeaturedProducts`, `ProductsByCategory`,
…) and `ProductSpotlight` carry ids, not product data: fetch them with
`GET /ecom/products/{id}` so that price, stock and documents are the ones this visitor
should see rather than a copy cached with the page. A `ProductSpotlight` section names one
product and says how to show it; when its `documents` is `Selected` or `Category`, list the
matching entries from that product's `documents`.

**Embeds.** An `Embed` section names an external https page (`url`), the frame's
accessible name (`title`) and its `height` in pixels. Render it as a sandboxed `iframe`
and allow the url's origin in your page's `frame-src`. `embed` is null when the stored
address cannot be embedded — skip the section then.

**Forms.** A `Form` section carries the whole form: fields, labels, options, whether a
field is required, the consent text and a `formToken`. Submit it with
`POST /ecom/forms/{formToken}/submissions`, as JSON or as `multipart/form-data` when it
has file fields. Send `formLoadedAtUnixMs` (when the form was rendered), the honeypot
field empty, `consentGiven` when the form has a consent text, and `sourceUrl`. A
submission without `formLoadedAtUnixMs`, with the honeypot filled in, or sent faster than
a person can type is accepted with the same response as a real one and then dropped.
A missing required field or consent comes back as a `400` problem. A form that has been
deactivated is left out of the page response, so a page never shows a form that cannot be
sent.

## Custom blocks

A channel can define its own blocks: fields plus an HTML template, written in Fluit by a
developer and filled in by editors like any other block. A section with `type: "Custom"`
carries the block in `custom`:

```json
"custom": {
  "blockKey": "prislista",
  "blockVersion": 4,
  "useShell": true,
  "html": "<ul class=\"prislista\">…</ul>",
  "css": "[data-block=\"prislista\"] .rad{…}",
  "fields": {
    "rader": [{ "tjanst": "Tyre change", "pris": 495, "fran": false,
                "lank": { "url": "/services/tyres", "openInNewTab": false } }],
    "fotnot": "All prices include VAT."
  }
}
```

**Render the HTML, or build your own from `fields`.** The template is rendered on the
server, so the HTML is what the channel's own storefront shows. It is sanitized on the
server already — no scripts, event attributes or `javascript:` links — but sanitize it again
before you insert it, as you would any HTML from an API. Put it in an element with
`data-block="{blockKey}"`: the CSS is scoped to that attribute and does not reach the rest
of the page. When `useShell` is `true`, draw the section's heading fields around it as for
any section; when it is `false`, the HTML draws everything itself.

**Add the CSS once per page.** Every section with the same block carries the same `css`.
Deduplicate on `blockKey` and `blockVersion` and put it in one `<style>` element.

**`fields` is data.** Keys are the block's field keys. Text is a string, formatted text
sanitized HTML, a number a number, a choice `{ key, label }`, a date ISO 8601, an image
`{ url, alt, width, height }` and a link `{ url, openInNewTab }` — a link to a page already
has the page's current address. A list is an array of objects with the same shapes. A
block whose definition is missing, or that cannot be rendered, is left out of the page.
A new version of a block changes every page that uses it at once, without the pages being
republished.

## Catalog and search

Products are addressed by slug or id — `GET /ecom/catalog/products/{idOrSlug}` accepts
either, so a URL can carry the readable one. Lists take `category`, `search`, `sort`,
`page` and `pageSize`, plus attribute filters as `attr_{code}=value1,value2`.

`GET /ecom/catalog/filters` returns the facets available for a given category or search,
with counts, so the filter panel reflects what is actually in the result rather than the
full attribute vocabulary. `GET /ecom/catalog/suggest` powers type-ahead.

Search is index-backed with relevance ranking, synonyms and typo tolerance — not a
substring match — so results are ordered by relevance unless you pass an explicit `sort`.

## Prices, stock and VAT

Prices come from the channel's price list, and from the customer's agreement prices when
the session is signed in. The same product therefore has no single price: it has the price
for this channel and this visitor. Fetch prices for a set of items in one call with
`GET /ecom/catalog/prices?itemIds=…` rather than reading them off cached product payloads.

**`unitPrice` is what the customer pays.** Two things can lower a price: the price list
hierarchy, and discount rules — campaign rules that apply to everyone, and agreement
discounts bound to one customer. `unitPrice` carries both. The price before any line
discount is `unitPriceBeforeDiscount`, and `discountAmount`, `discountPercent` and
`discountName` say what the difference was and what it is called. The cached catalog
payloads (`listPrice` on a product or a list row) carry the same net price for an
anonymous visitor.

> **Changed 2026-09-16.** `unitPrice` previously carried the price *before* discount
> rules, so a storefront that displayed it showed a higher price than the cart charged.
> If you were reading `unitPrice` you now get the right number and need no change; if you
> were relying on it as a pre-discount reference, read `unitPriceBeforeDiscount` instead.

**`isCustomerSpecific` decides what you may claim.** It is true when the price or the
discount is bound to this customer — an agreement price list, a blanket agreement, a
customer discount, or a rule conditioned on the customer or their group. Such a price is
that customer's own terms, not a reduction the shop advertised, so it must never be
presented against `lowestPrice30Days` as a price drop. Do not infer this from `source`:
a customer discount lowers the price without changing where the price came from.
Cart lines (`GET /ecom/cart`) carry the same flag with the same meaning: when a line's
`isCustomerSpecific` is true, its `discountAmount` is the customer's agreement, not a
reduction to strike through.

`quantityBreaks` lists the quantities where the unit price changes, from price list tiers
and from discount rules with a minimum quantity alike, with the unit price at each tier
already net of discounts.

Whether amounts include VAT is a channel setting, and some channels let the visitor toggle
it. Read `channel.features.showPricesIncludingVat` and `allowCustomerVatToggle` from the
session response and render accordingly — the numbers on the wire follow the channel, and
a front end that assumes one convention will be wrong on the other.

Stock is available separately through `GET /ecom/catalog/stock?itemIds=…`, aggregated
according to the channel's `stockAggregation` setting. `showStock` and
`showOutOfStockProducts` decide whether a storefront is supposed to display it at all.

Both endpoints take at most **100 ids per request**, and both have a `POST` variant that
takes the same ids in a JSON body:

```bash
curl -X POST "https://api.erp.fluit.cloud/ecom/catalog/prices" \
  -H "X-Tenant-Id: $FLUIT_TENANT_ID" -H "X-Channel: web" \
  -H "Content-Type: application/json" \
  -d '{ "itemIds": ["…", "…"] }'
```

The `POST` exists because of URL length, not because of the limit: with GUIDs a typical
URL budget runs out around 50 ids, well before the 100 the server actually allows. Same
handler, same response body, so you can switch without touching your parser. The limit is
the same on both — it protects response time, since the price engine runs per item — so
chunk into batches of 100 either way. One difference worth knowing: the `GET` silently
skips ids it cannot parse, while a malformed id in the JSON array fails the whole request
with `400`.

Neither variant is cacheable. Both answer `no-store`, because the price depends on the
signed-in customer's agreement.

## From cart to order

The cart hangs off the session, so there is no cart id to carry:

1. `POST /ecom/cart/items` with an item id and a quantity.
2. `GET /ecom/checkout/data` for the shipping and payment methods this channel offers, plus
   the known customer details when signed in.
3. `POST /ecom/checkout/sessions` to start payment with the channel's provider.
4. `POST /ecom/checkout/place` to place the order.
5. `GET /ecom/checkout/sessions/{sessionId}/confirmation` on the return page.

Step 3 is provider-agnostic. The response carries a `renderMode` and exactly one of
`htmlSnippet`, `redirectUrl` or `clientSecret`, and your front end acts on the mode rather
than on the provider's name. That is what lets a tenant change payment provider without a
front-end release.

`POST /ecom/checkout/apply-code` takes both discount coupons and gift cards; the response
says which it was and what it did to the total.

**Pickup.** A shipping method with `isPickup` in `GET /ecom/checkout/data` is collected
by the buyer. When the channel has pickup locations, `POST /ecom/checkout/pickup-locations`
lists them with the cart's availability at each (`InStock`, `AvailableFrom` with a date, or
`Unavailable`), and the buyer chooses one instead of entering a shipping address. Send its
`warehouseId` as `pickupWarehouseId` on `POST /ecom/checkout/place`. The order is placed on
that location, stock is checked there rather than across the channel, and the location's
address becomes the delivery address, which is also what decides the VAT. A billing
address is still required when the buyer is a company or pays by invoice. A channel
without pickup locations handles a pickup method exactly as before.

> The endpoints under `/ecom/kco/*` are the Klarna-specific predecessor of the same flow.
> They still work and our own storefront still uses them, but new builds should use
> `/ecom/checkout/sessions`. The KCO endpoints will not gain features.

## Payment provider callbacks

`POST /ecom/checkout/webhooks/{provider}` and `POST /ecom/kco/push` are **inbound**. The
payment provider calls them when a payment settles; you never do. They are documented
because you may need to configure their URLs in the provider's dashboard, and because
seeing them here explains how an order can change state without your front end doing
anything.

## Customer portal

Everything under `/ecom/portal/*` is the signed-in customer's own record: orders,
invoices, shipments, quote requests, returns, support tickets, addresses and profile. All
of it requires a session that has been authenticated, and all of it is scoped to that
customer — there is no way to read another customer's data through these endpoints.

This is not the same thing as Fluit's partner portal, which lives under `/portal` and has
its own API. The names are close; the surfaces are unrelated.

## Idempotency

A timeout on `POST /ecom/checkout/place` is the one failure that a storefront cannot
reason its way out of on its own: the order may or may not exist, and asking again
without protection either places a second one or answers that the cart is already
converted — which tells you the order exists but not what it was called.

Send an `Idempotency-Key` header to close that gap. Use a unique value per logical
attempt, a UUID is the obvious choice, and reuse the *same* value on every retry of that
attempt:

```bash
curl -X POST "https://api.erp.fluit.cloud/ecom/checkout/place" \
  -H "X-Tenant-Id: $FLUIT_TENANT_ID" \
  -H "X-Channel: web" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ … }'
```

The first call runs normally. A retry with the same key replays the original response —
the same status, the same body and the same `Location` — with `Idempotency-Replayed:
true` added, and without the handler running again. Other response headers are not
replayed, so read the outcome from the body rather than from them. Keys are scoped to
the session and kept for 24 hours.

**The header is optional here.** That is a deliberate difference from the Fluit Public
API, where it is required on every POST: this surface already has clients, and making it
mandatory would have broken all of them at once. Omit it and the call behaves exactly as
it did before.

Two responses exist only when you send the header:

- `422` — the key was already used for a *different* request, meaning another endpoint or
  the same endpoint with a different body. Use a new key for new requests; reuse a key
  only when retrying the same one.
- `503` with `Retry-After` — a request with the same key is still in flight. Retry with
  the same key once it finishes.

A `5xx` is never replayed. Server errors are not a final answer to your request, so the
key is released and a retry genuinely runs the operation again.

**A `4xx` is a final answer, and it is replayed.** Once a call with a key has been
rejected (out of stock, an expired cart, a validation error), that attempt is over. The
shopper's next try, typically after changing the cart, is a new request and needs a new
key. Reuse the old one and you get the old error back for 24 hours. Keep a key only while
the outcome is unknown: no response, a network error or a `5xx`.

**When you cannot simply retry.** If the response to `POST /ecom/checkout/place` was lost
and the page has since been reloaded, the cart may already be an order, and sending the
request again would only answer that the cart is converted. Ask
`GET /ecom/checkout/attempts/{key}` instead, with the same session: it tells you whether
the attempt is still running, failed, or created an order, and if so which one, so you
can show the confirmation the shopper missed.

Honoured on `POST /ecom/checkout/place` and `POST /ecom/checkout/sessions`.
**`POST /ecom/cart/items` deliberately does not honour it**, and that is not an
oversight: adding the same item twice is a thing shoppers legitimately do, and
suppressing the second add would silently drop a real one.

## Pagination

List endpoints return a fixed envelope:

```json
{
  "items": [],
  "totalCount": 0,
  "page": 1,
  "pageSize": 20,
  "totalPages": 0,
  "hasPreviousPage": false,
  "hasNextPage": false
}
```

`page` is 1-based. Page sizes are clamped per endpoint; ask for more than the maximum and
you get the maximum, not an error.

## Caching

Every response carries a `Cache-Control` header, and following it is better than inventing
your own TTLs. There are two kinds.

**Channel-wide responses** — the catalogue, search, categories, brands, filters, content
pages, widgets and the redirect table — answer `public, max-age=…` with an `ETag`:

| Response | max-age |
| --- | --- |
| Category tree | 3600 |
| Product detail | 600 |
| Product feed | 3600 |
| Product lists, search, filters, brands | 300 |
| Content pages, widgets, redirects | 300 |
| Type-ahead suggestions | 300 |

Those numbers are not advice — they are the same TTLs the API uses for its own internal
cache. Honouring them therefore adds no staleness that we do not already have.

Revalidation is cheap: send the `ETag` back as `If-None-Match` and an unchanged response
answers `304` with no body.

```bash
curl -H "If-None-Match: $ETAG" \
     -H "X-Tenant-Id: $FLUIT_TENANT_ID" -H "X-Channel: web" \
     "https://api.erp.fluit.cloud/ecom/catalog/categories"
```

**Everything else answers `no-store`** and carries no `ETag`. That is the default for the
whole surface, not a list we maintain: the cart, checkout, the customer portal, prices and
stock all fall under it, and so does any endpoint we add tomorrow. Prices in particular
depend on the signed-in customer's agreement, so there is no shared version of them to
keep. Caching those per authenticated customer inside your own layer is fine — that is a
distinction only you can draw.

> **If you put a shared cache or CDN in front of this API, you must vary on
> `X-Tenant-Id`, `X-Channel` and `X-Language`.** All three are headers, none appears in
> the URL, and each decides what the response contains. We send
> `Vary: X-Tenant-Id, X-Channel, X-Language` on every cacheable response for exactly this
> reason — a cache keyed on the URL alone would serve one tenant's catalogue to another,
> and one visitor's language to the next.

Images and documents under `/ecom/catalog/assets/*` are immutable for practical purposes
and answer `public, max-age=86400` and `3600` respectively.

## Errors

| Status | Means |
| --- | --- |
| `400` | The request is malformed, or a value is invalid |
| `401` | The endpoint needs a session and none was sent, or the token has expired |
| `403` | The session exists but is not allowed to see this record |
| `404` | No such product, page, channel or record in this channel |
| `409` | The record is not in a state where this makes sense — a cancelled order, a used coupon |
| `429` | Rate limit — see below |

**Do not assume one body shape.** This surface predates the reference and carries three,
and a client that parses every failure as RFC 7807 will throw on two of them:

- Most `400`, `403`, `404`, `409` and `500` responses are `application/problem+json` per
  RFC 7807, with `type`, `title`, `status` and `detail`, plus an `errors` object on
  validation failures.
- Some endpoints — mainly the channel-`404` on catalogue, content and blog reads, and the
  `400` on the id-list endpoints — answer `application/json` with a flat
  `{ "error": "…" }` instead. Each operation's documented response schema is the truth;
  where it says `ProblemDetails` you get RFC 7807, otherwise expect the flat shape.
- `401` has **no body at all**. The status code is the whole message.
- `429` is `application/json` with problem-like fields, but not the problem media type.

Branch on the status code and the `Content-Type`, not on the assumption. Consolidating
these onto one shape would break clients that read the current one, so it will happen as
an announced change rather than quietly.

A `404` from a catalogue endpoint usually means "not published in this channel" rather
than "does not exist". That distinction is deliberate: an unpublished product should be
indistinguishable from a missing one.

## Rate limiting

Every endpoint is rate limited. Quotas are per tenant and channel, and then per visitor —
by client IP for anonymous traffic and by session token once there is one — so one busy
visitor cannot spend the channel's budget.

| Traffic | Limit |
| --- | --- |
| Catalogue and search | 300 / minute per IP |
| Session | 60 / minute per IP anonymous, 120 with a token, 600 for recognised crawlers |
| Cart | 60 / minute |
| Checkout | 10 / minute |
| Sign-in | 5 / minute per IP |
| Request a login code | 3 / 15 minutes per IP |
| Verify a login code | 10 / minute per IP |
| Help articles | 120 / minute per IP, 600 for recognised crawlers |
| Page-view and funnel tracking | 120 / minute per IP |
| Shopping assistant | 20 / minute |
| Submit a review | 5 / hour per IP |
| Newsletter sign-up | 10 / hour per IP; one confirmation email per address every 10 minutes, at most 3 a day |
| Newsletter unsubscribe | 20 / hour per token |
| Form submission | 10 / hour per IP |
| Domain resolution | 30 / minute per IP |
| Payment webhooks | 30 / minute per tenant, endpoint and sender IP |

**There are no `X-RateLimit-*` headers on this API.** You discover the quota by hitting it:
a rejected request returns `429` with `Retry-After` in seconds and a problem-shaped
`application/json` body. Honour `Retry-After` rather than retrying on a fixed delay.

The per-IP partitions use `X-Forwarded-For` only from a caller with a storefront key. See
*Architecture* above. A storefront that resolves its domain or relays a payment provider's
webhook should forward the visitor's or the provider's address the same way. Otherwise
every such call counts against the storefront server's own address.

A newsletter sign-up above the per-address limit answers exactly like any other sign-up
but sends no email. A different answer would reveal which addresses are on the list.

## Status and stability

This is the API behind our own storefront, and it moves with it. Additive changes — new
endpoints, new optional fields, new enum members — happen without notice, so read
defensively and ignore fields you do not recognise. Changes that break an existing
contract are announced in the Fluit changelog before they ship.

It is a different promise from the Fluit Public API, which is versioned for third-party
integrations. If you are synchronising an external system rather than building a
storefront, that is the surface you want.

## Endpoints

113 endpoints. Each one is listed with its query parameters, the request body examples from the OpenAPI document and the status codes it can return. Field-level schemas for request and response bodies are in the OpenAPI document linked above.

### Ecom.Session

Establishing context: map a domain to a tenant and channel, then open a session. The session response also carries the channel's whole configuration — currency, language, feature flags, branding, navigation and SEO — so a storefront can render its shell from one call.

#### `GET /ecom/session` — Get or create session

Returns a session token and full channel context including branding, features, and analytics. Creates an EcomSession entity on first visit and reuses it on subsequent visits.

Headers: `X-Channel` (string), `X-Language` (string)

Responses: `200`, `404`, `429`

#### `GET /ecom/session/resolve` — Resolve domain to tenant

Maps a domain (e.g., shop.acme.com) to tenant and channel IDs. Returns routing info only — full channel data comes from GET /ecom/session. When `canonicalHost` is set, the domain is an old address of the channel: redirect the visitor there permanently (301) instead of serving the shop on the old host. The answer depends only on the query, so it is cacheable and carries an ETag; follow the Cache-Control header instead of picking your own lifetime for it.

Query parameters: `domain` (string), `channel` (string)

Headers: `If-None-Match` (string)

Responses: `200`, `304`, `404`, `429`

### Ecom.Channels

The storefronts a tenant runs, and the home page each one presents. A channel owns its assortment, price list, currency and branding, so the same item can be published in two channels at different prices.

#### `PATCH /ecom/branding` — Update channel branding

Updates the custom CSS and theme fields (colors, fonts, border radius) for the current channel's branding. Only fields present in the body are changed; null clears a field. Requires the X-Channel header and a valid X-Admin-Preview token for the same tenant and channel. The CSS is sanitised before it is stored, so the value in the response is what was actually saved and may differ from what was sent.

Headers: `X-Channel` (string)

Request body: `application/json`, `application/merge-patch+json` (required)

Responses: `200`, `400`, `401`, `404`, `415`, `429`

#### `POST /ecom/branding/ai-suggest` — Suggest branding CSS for an element

Proposes custom CSS for one element of the storefront, given the channel's current branding and a description of what to change, and streams the suggestion as server-sent events. It only proposes — PATCH /ecom/branding is what stores anything. Part of the in-store admin overlay and gated by the same admin preview token, so it is not an endpoint a storefront calls on a visitor's behalf.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `429`

#### `GET /ecom/homepage` — Get home page configuration

Returns the channel's home page: its visible sections (banners filtered by date, section collections expanded, forms with their fields) and its SEO fields. The home page is also available as the page at path / through GET /ecom/pages/resolve.

Headers: `X-Channel` (string)

Responses: `200`, `404`, `429`

### Ecom.Catalog

Products, categories, brands, search, facets and type-ahead. Products are addressed by slug or id, and only what is published in the current channel is visible. Includes the product feed for Google Merchant and the binary endpoints that serve images and documents.

#### `GET /ecom/assets/{tenantId}/{id}` — Get product image

Serves a public product image. No authentication required. Tenant resolved from URL. Pass ?w= with one of the supported widths to get a resized WebP variant for responsive srcset.

Query parameters: `w` (integer)

Headers: `X-Channel` (string)

Responses: `200`, `400`, `404`, `429`

#### `GET /ecom/assets/{tenantId}/{id}/download` — Get product document

Serves a public product document (datasheet, manual, firmware). No authentication required. Tenant resolved from URL. PDFs are served inline, everything else as a download.

Headers: `X-Channel` (string)

Responses: `200`, `404`, `429`

#### `GET /ecom/catalog/brands` — Get brands (suppliers) by id

Returns display data for the suppliers referenced by a Brands section.

Query parameters: `ids` (string)

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `429`

#### `GET /ecom/catalog/categories` — Get category tree

Returns the hierarchical category tree for navigation.

Query parameters: `parentId` (string), `ids` (string)

Headers: `X-Channel` (string), `X-Language` (string), `If-None-Match` (string)

Responses: `200`, `304`, `429`

#### `GET /ecom/catalog/filters` — Get catalog filters

Returns filterable attributes with available values and product counts. Counts are scoped to the channel, the optional category and the optional search term.

Query parameters: `category` (string), `search` (string)

Headers: `X-Channel` (string), `X-Language` (string), `If-None-Match` (string)

Responses: `200`, `304`, `429`

#### `GET /ecom/catalog/list-widgets` — Get product list page widgets

Returns active ProductList_Banner and ProductList_Sidebar widgets matching the current channel and optional category.

Query parameters: `categoryCode` (string)

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `404`, `429`

#### `GET /ecom/catalog/product-feed` — Product feed rows

Returns feed-ready product rows (identifiers, prices, availability, Google product category) for building Google Shopping and Meta catalog feeds. Page size is clamped to 1-1000.

Query parameters: `page` (integer; default `1`), `pageSize` (integer; default `500`)

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `429`

#### `GET /ecom/catalog/products` — List products

Returns a paginated list of products with optional filtering by category, product tag (tag=slug) and search term. Pass ids=guid,guid to fetch a hand-picked set; without an explicit sort they are returned in the order given. With a category, sort=category returns the products in the order they were assigned to that category; products only in a subcategory follow, in the default order. Pass onSale=true to list only products that are reduced right now: priced by a campaign price list or a public discount rule below the item's regular price, for an anonymous visitor in the channel's currency (customer-specific prices never count). Only includes products active on the current channel.

Query parameters: `category` (string), `search` (string), `page` (integer; default `1`), `pageSize` (integer; default `20`), `sort` (string), `ids` (string), `tag` (string), `onSale` (boolean; default `false`)

Headers: `X-Channel` (string), `X-Language` (string), `If-None-Match` (string)

Responses: `200`, `304`, `429`

#### `GET /ecom/catalog/products/{idOrSlug}` — Get product details

Returns complete product information including stock status, images, and attributes. Only shows products active on the current channel. A variant (looked up by slug, item number or id) returns its variant master with `selectedVariantId` set to the variant. `canonicalSlug` is the page's canonical slug: the master's, except in channels that list variants as products of their own. A client that received the response on another slug should redirect to `/products/{canonicalSlug}?variant={variant seoSlug}`. `defaultVariantId` is the first purchasable variant in axis order.

Headers: `X-Channel` (string), `X-Language` (string), `If-None-Match` (string)

Responses: `200`, `304`, `404`, `429`

#### `GET /ecom/catalog/products/{idOrSlug}/configuration` — Get the configuration schema for a product

Returns what the shopper has to choose before a made-to-order product can be added to the cart: the fields, grouped for display, and the options for each field with their price impact and an image when one is set. Fields without a group come first in a single unnamed group, so a product that was never grouped renders as a flat list. Calculated fields are left out — they are derived from the others. Pair this with POST .../configuration/price to price the choices as they are made. 404 when the product is not published on the channel, has no configurable features, or requires an on-site measurement: those products are sold through quote and order, not self-service, and are deliberately indistinguishable from a product that does not exist.

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `404`, `429`

#### `POST /ecom/catalog/products/{idOrSlug}/configuration/price` — Price a product configuration

Prices a set of choices without saving anything, so a storefront can show the price updating as the shopper chooses. POST rather than GET because the choices do not fit a query string; the call has no side effects and is never cached. Returns the unit and total price together with isValid, which is false while a required field is missing or a value falls outside its range — the errors name the field so they can be shown next to the right input. The breakdown into base price and configuration surcharge is deliberately not part of this response: it describes how the merchant prices, not what the shopper pays.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `404`, `429`

#### `GET /ecom/catalog/related-products` — Get related products by type

Returns up to 8 unique related product summaries for the given item IDs and relation type. Types: Related, Accessory, CrossSell, UpSell, SparePart.

Query parameters: `itemIds` (string; required), `type` (required)

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `400`, `429`

#### `GET /ecom/catalog/search` — Search products

Full-text product search with relevance ranking, synonym expansion, typo tolerance and zero-result fallbacks.

Query parameters: `q` (string), `category` (string), `page` (integer; default `1`), `pageSize` (integer; default `24`), `sort` (string)

Headers: `X-Channel` (string), `X-Language` (string), `If-None-Match` (string)

Responses: `200`, `304`, `429`

#### `GET /ecom/catalog/stock` — Get stock status for items

Returns aggregated stock status for a batch of items. Returns nothing when the storefront hides stock, or when it hides stock from visitors who are not logged in and the request carries no customer session. Maximum 100 item ids per request; ids that cannot be parsed are skipped. With GUIDs the URL runs out before that limit does — use POST /ecom/catalog/stock for longer lists.

Query parameters: `itemIds` (string; required)

Headers: `X-Channel` (string)

Responses: `200`, `400`, `404`, `429`

#### `POST /ecom/catalog/stock` — Get stock status for items (ids in body)

Identical to GET /ecom/catalog/stock — same handler, same response body — but takes the item ids in a JSON body, for id lists long enough to strain the URL. Both variants enforce the same limit of 100 ids per request. Returns nothing when the storefront hides stock, or when it hides stock from visitors who are not logged in and the request carries no customer session.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `404`, `429`

#### `GET /ecom/catalog/suggest` — Search suggestions

Type-ahead suggestions for the storefront search field: matching products, term completions and categories.

Query parameters: `q` (string), `limit` (integer; default `6`)

Headers: `X-Channel` (string), `X-Language` (string), `If-None-Match` (string)

Responses: `200`, `304`, `429`

#### `GET /ecom/catalog/tags` — List product tags

Returns the product tags that have at least one product listed in the current channel, with the number of products per tag, sorted by name. Each tag is a landing page: list its products with GET /ecom/catalog/products?tag={slug}. Pass slug to look up a single tag — an empty list means no such tag page exists in this channel. Tags are shared by all channels, but the counts and the selection are channel-specific.

Query parameters: `slug` (string)

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `429`

#### `GET /ecom/products/{itemId}/widgets` — Get matching product widgets for a product

Returns active HTML widgets that match the given product based on category, supplier, item group, price range, etc.

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `404`, `429`

### Ecom.Pricing

Prices for a set of items in one call. The answer depends on the channel and on whether the session is signed in, because a signed-in customer gets their agreement prices. Do not cache the result across visitors.

#### `GET /ecom/catalog/prices` — Get prices for items

Returns calculated prices for a batch of items. Supports customer-specific pricing for authenticated B2B sessions via the session token. Respects channel price lists, campaigns, and quantity breaks. Maximum 100 item ids per request; ids that cannot be parsed are skipped. With GUIDs the URL runs out before that limit does — use POST /ecom/catalog/prices for longer lists.

Query parameters: `itemIds` (string; required)

Headers: `X-Channel` (string)

Responses: `200`, `400`, `404`, `429`

#### `POST /ecom/catalog/prices` — Get prices for items (ids in body)

Identical to GET /ecom/catalog/prices — same handler, same response body — but takes the item ids in a JSON body. Use it when the id list is long enough to strain the URL: with GUIDs a typical URL budget runs out around 50 ids, well below the limit of 100 that both variants enforce. Respects channel price lists, campaigns and quantity breaks, and returns the customer's agreement prices when the session is signed in.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `404`, `429`

### Ecom.Redirects

The channel's URL redirect table, for a storefront that handles its own routing. Read once and cache — it is channel-wide and changes rarely.

#### `GET /ecom/redirects` — Get active URL redirects for the current channel

Returns the channel's whole active redirect table in one call: source path, target path and the HTTP status to answer with (301 or 302). Intended to be read once and held in memory by the storefront, not called per request — the table is channel-wide and changes only when someone edits it in Fluit.

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `404`, `429`

### Ecom.ContentPages

CMS pages: the navigable list and a page by slug, with its sections. Used for terms, about, delivery information and anything else the tenant edits without a deploy.

#### `GET /ecom/custom-blocks/preview/{token}` — Get a custom block preview rendered by the block editor

Admin preview only: returns the rendered HTML and scoped CSS of an unsaved custom block draft. Requires a valid admin preview token for the channel in X-Admin-Preview. Tokens expire after 30 minutes.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

#### `POST /ecom/forms/{formToken}/submissions` — Submit a form shown on a page

Submits the answers to a form that a page section carries (section type Form; the section's form has the token, the fields and the consent text). Send the answers as 'data': a JSON string of an object keyed by field id. File fields need multipart/form-data, with the files as parts and the other properties as fields of the same name. 'formLoadedAtUnixMs' is required — when the form was shown — and so is consentGiven=true when the form has consent text. A submission that looks automated gets the same 200 as a real one and is dropped; the response never tells a bot it was caught. What happens next — a deal or a ticket, notification emails, a receipt — is set on the form in Fluit, not by the storefront.

Headers: `X-Channel` (string)

Request body: `application/json`, `multipart/form-data` (required)

Responses: `200`, `400`, `404`, `409`, `429`

#### `GET /ecom/pages` — Get published content pages for navigation

Returns every published page in the channel as a flat list, in the tenant's own sort order. Each entry carries its storefront path (pages live at the root, nested under their parent: /about, /services/tyres; the home page is /), its parentPageId and whether it is hidden from search engines. The menu itself comes from the session's navigation, not from this list. Read the page body with GET /ecom/pages/resolve?path= or GET /ecom/pages/{slug}.

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `404`, `429`

#### `GET /ecom/pages/resolve` — Resolve a storefront path to a content page

Looks up the published page for a storefront path such as /about or /services/tyres; / is the channel's home page. The last segment identifies the page (slugs are unique per channel), so a stale path still finds it: compare the response's canonicalPath with the requested path and redirect permanently when they differ. That covers pages that moved under another parent and the old /pages/{slug} addresses. The first segment of a page path is never one of the storefront's own routes — see reservedSlugs in the session for the list.

Query parameters: `path` (string)

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `404`, `429`

#### `GET /ecom/pages/{slug}` — Get a published content page by slug

Returns a published page with its SEO fields and its sections in display order. Sections are typed — text, image, testimonial, feature cards, forms, FAQ — and a storefront renders each kind its own way, so treat an unfamiliar section type as something to skip rather than fail on. Section collections are already expanded and forms carry their fields. An unpublished or missing page both return 404; the two are deliberately indistinguishable.

Headers: `X-Channel` (string), `If-None-Match` (string)

Responses: `200`, `304`, `404`, `429`

### Ecom.Blog

Blog and news posts for the channel, with tag filtering and related-post lookup.

#### `GET /ecom/blog` — List published blog posts / news

Returns the channel's published posts, newest first, with their tags and cover images. Filter with ?tag= and choose the kind with ?type=BlogPost (default) or ?type=NewsPost; an unrecognised type falls back to BlogPost. Page is 1-based, default pageSize is 12 and the maximum is 50. Scheduled posts appear on their publish date, so the response is time-dependent and cached for a short while.

Query parameters: `page` (integer), `pageSize` (integer), `tag` (string), `type` (string)

Headers: `X-Channel` (string)

Responses: `200`, `404`, `429`

#### `GET /ecom/blog/related` — Get related articles for an article

Returns other published posts related to the one identified by ?slug=, ranked by how many tags they share with it and falling back to the most recent when nothing overlaps. Candidates are of the same kind as the source post, so a news post never suggests a blog post. Default ?take= is 3 and the maximum is 12. The article itself is never included, and an unknown slug returns an empty list rather than 404.

Query parameters: `slug` (string; required), `take` (integer)

Headers: `X-Channel` (string)

Responses: `200`, `404`, `429`

### Ecom.Help

Knowledge base articles: browse by category, read by slug, search, and look up the articles attached to a specific product.

#### `GET /ecom/help/articles` — List published FAQ / knowledge articles

Returns published knowledge articles grouped by category, with locale-aware translations.

Query parameters: `category` (string), `locale` (string)

Headers: `X-Channel` (string)

Responses: `200`, `429`

#### `GET /ecom/help/articles/by-item/{itemId}` — Get knowledge articles for a specific item

Returns published knowledge articles linked to the given item ID, each with its content rendered as sanitized HTML.

Query parameters: `locale` (string)

Headers: `X-Channel` (string)

Responses: `200`, `429`

#### `GET /ecom/help/articles/{slug}` — Get a knowledge article by slug

Returns a single published knowledge article with its Markdown content, the same content rendered as sanitized HTML, and the products it applies to that are published on the channel.

Query parameters: `locale` (string)

Headers: `X-Channel` (string)

Responses: `200`, `404`, `429`

#### `GET /ecom/help/search` — Search knowledge articles

Full-text search across published knowledge articles. Returns up to 10 results.

Query parameters: `q` (string; required), `locale` (string)

Headers: `X-Channel` (string)

Responses: `200`, `429`

### Ecom.Cart

The cart hangs off the session, so there is no cart id to pass around. Anonymous sessions have carts too, and the cart survives signing in.

#### `GET /ecom/cart` — Get shopping cart

Returns the current shopping cart contents with product details.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `429`

#### `DELETE /ecom/cart` — Clear shopping cart

Removes all items from the shopping cart.

Headers: `X-Channel` (string)

Responses: `204`, `401`, `404`, `429`

#### `POST /ecom/cart/items` — Add item to cart

Adds an item to the shopping cart, or increases the quantity when the same item is already there. A configurable product must be sent with selections: its price comes from the choices, and a made-to-order product without them cannot be manufactured. Two lines of the same product merge only when their configuration is identical — two differently configured curtains are two different goods and stay two lines, each addressable by its own cart item id.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `429`

#### `PATCH /ecom/cart/items/{itemId}` — Update cart item quantity

Updates the quantity of an item in the shopping cart. Answers 409 Cart.AmbiguousItem when the item lies on several lines (a configurable item with different configurations); address the line through /ecom/cart/lines/{cartItemId} instead.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `404`, `409`, `429`

#### `DELETE /ecom/cart/items/{itemId}` — Remove item from cart

Removes an item from the shopping cart. Answers 409 Cart.AmbiguousItem when the item lies on several lines (a configurable item with different configurations); address the line through /ecom/cart/lines/{cartItemId} instead.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `409`, `429`

#### `POST /ecom/cart/lines` — Add several lines to the cart

Adds several items to the cart for the signed-in customer, as quick order and reorder do. Each line passes the same checks as POST /ecom/cart/items: publication, stock limit, backorder rule and price. A line that fails does not stop the others; it is returned in 'failed' with its error code. The same item on two lines is added as one line with the sum.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `403`, `429`

#### `PATCH /ecom/cart/lines/{cartItemId}` — Update cart line quantity

Updates the quantity of one cart line, addressed by its cartItemId from GET /ecom/cart. Use this rather than PATCH /ecom/cart/items/{itemId}: a configurable item can lie on several lines with different configurations.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `404`, `429`

#### `DELETE /ecom/cart/lines/{cartItemId}` — Remove cart line

Removes one cart line, addressed by its cartItemId from GET /ecom/cart. Use this rather than DELETE /ecom/cart/items/{itemId}: a configurable item can lie on several lines with different configurations.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

#### `POST /ecom/portal/quick-order/resolve` — Resolve quick order lines

Looks up quick order lines for the signed-in customer without adding anything to the cart. One line per item: a reference followed by a quantity, separated by space, tab or semicolon. The reference can be the customer's own item number, our item number, a barcode or a cross reference; the customer's item number wins and its unit is converted. Lines that cannot be ordered are returned in 'rejected' with a reason. Add the resolved lines with POST /ecom/cart/lines.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `403`, `429`

#### `POST /ecom/portal/quick-order/resolve-file` — Resolve quick order lines from a file

Same as POST /ecom/portal/quick-order/resolve, from an uploaded file in the 'file' field: CSV or text in the same line format, or Excel (.xlsx) with the columns Artikelnummer and Antal. At most 2 MB and 500 lines.

Headers: `X-Channel` (string)

Request body: `multipart/form-data` (required)

Responses: `200`, `400`, `401`, `403`, `429`

### Ecom.Checkout

Checkout from available methods to placed order, including discount coupons, gift cards, shipping price calculation and postal code lookup. Payment runs through a provider-agnostic session: the response says how to render it, not which provider produced it.

#### `POST /ecom/checkout/apply-code` — Apply code

Validates a gift card or discount code for checkout use.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `404`, `429`

#### `GET /ecom/checkout/attempts/{key}` — Get the outcome of a place-order attempt

Returns what became of a `POST /ecom/checkout/place` sent with the given `Idempotency-Key`, within the caller's own session. Use it when the response to place-order was lost, for example after a timeout followed by a page reload: the order may already exist and the cart is then converted, so sending the request again would only answer that the cart is already converted. `Completed` carries the order id and number, `Pending` means the original request is still running, and `Failed` means it got a final error and no order was created. Attempts are kept for 24 hours.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

#### `GET /ecom/checkout/data` — Get checkout data

Returns available shipping methods, payment methods and pre-filled customer data for the checkout page.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `429`

#### `POST /ecom/checkout/pickup-locations` — List pickup locations for the cart

Returns the channel's pickup locations (warehouses the channel offers for pickup), in the channel's order, with whether the session's cart can be picked up at each. `InStock`: everything is there today. `AvailableFrom`: something is on its way there (purchase, transfer or production) and everything is there from `availableFrom`. `Unavailable`: something is missing and not on its way within the channel's horizon; the location cannot be chosen. `lines` tells which item decides it. Call it when the buyer chooses a shipping method with `isPickup`, and again when the cart changes. The answer depends on the cart and is never cached, which is why it is a POST. An empty list means the channel has no pickup locations; a pickup method then works as before, without `pickupWarehouseId`.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `429`

#### `POST /ecom/checkout/place` — Place order

Completes checkout and creates a sales order from the shopping cart. Send an Idempotency-Key header and a retry after a timeout replays the original response instead of placing a second order, or answering that the cart is already converted. The header is optional; without it the call behaves as it always has. Pickup: when the shipping method has `isPickup` and the channel has pickup locations, send `pickupWarehouseId` from `POST /ecom/checkout/pickup-locations` instead of a shipping address. The order is then placed on that location, which becomes its delivery address. A billing address is required when the buyer is a company or pays by invoice. Without `pickupWarehouseId` a pickup order behaves as before and is placed on the channel's default warehouse.

Headers: `X-Channel` (string), `Idempotency-Key` (string)

Request body: `application/json` (required)

Responses: `201`, `400`, `401`, `422`, `429`, `503`

#### `POST /ecom/checkout/sessions` — Create checkout session

Creates a checkout session at the channel's configured payment provider. Send an Idempotency-Key header and a retry after a timeout returns the original session instead of opening a second one at the provider. The header is optional.

Headers: `X-Channel` (string), `Idempotency-Key` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `403`, `422`, `429`, `503`

#### `PATCH /ecom/checkout/sessions/{sessionId}` — Update checkout session

Refreshes an existing checkout session at its payment provider when the cart has changed. For providers that return shippingOptions, send shippingOptionId to change the shipping the payment charges for.

Headers: `X-Channel` (string)

Request body: `application/json`

Responses: `200`, `400`, `401`, `404`, `429`

#### `GET /ecom/checkout/sessions/{sessionId}/confirmation` — Get checkout confirmation

Returns the payment provider's confirmation view, the resulting order number and the order's totals. The totals are null until the order exists; use them to report the purchase to your own analytics.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

#### `PATCH /ecom/checkout/sessions/{sessionId}/review-invitation` — Set the buyer's review invitation choice on a checkout session

For checkouts at a payment provider: the buyer's opt-out from the review invitation after delivery is stored on the session and carried to the order when payment completes. Only while the session is pending.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `204`, `400`, `401`, `404`, `429`

#### `POST /ecom/checkout/shipping-prices` — Calculate shipping prices

Calculates shipping prices for all enabled shipping methods based on destination country and cart weight using FreightPriceList.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `401`, `429`

#### `POST /ecom/checkout/webhooks/{provider}` — Payment provider webhook

Callback from a payment provider when a checkout completes. Creates the sales order. Idempotent.

Headers: `X-Channel` (string)

Responses: `200`, `429`, `503`

#### `GET /ecom/postal-codes/lookup` — Verify a postal code and get its city

Status is NoRegister, Verified, CityMismatch, UnknownCode or InvalidFormat. Advisory only — never blocks an order from being placed.

Query parameters: `country` (string; required), `code` (string; required), `city` (string)

Headers: `X-Channel` (string)

Responses: `200`, `429`

#### `GET /ecom/postal-codes/suggest` — Prefix search on postal code or city

Terms shorter than two characters return an empty list.

Query parameters: `country` (string; required), `q` (string; required), `take` (integer)

Headers: `X-Channel` (string)

Responses: `200`, `429`

### Ecom.Kco

Klarna Checkout, the provider-specific predecessor of the checkout session endpoints. Still supported, but new builds should use Ecom.Checkout instead. The push endpoint here is an inbound callback from Klarna, not something a storefront calls.

#### `POST /ecom/kco/push` — KCO push callback

Webhook called by Kustom when checkout is completed. Creates a SalesOrder and acknowledges to Kustom. Idempotent.

Headers: `X-Channel` (string)

Responses: `200`, `429`, `503`

#### `POST /ecom/kco/sessions` — Create KCO session

Creates a Kustom Checkout session and returns an HTML snippet for embedding the checkout widget. Deprecated alias for POST /ecom/checkout/sessions.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `403`, `429`

#### `PUT /ecom/kco/sessions/{sessionId}` — Update KCO session

Updates an existing Kustom Checkout session when the cart has changed. Deprecated alias for PATCH /ecom/checkout/sessions/{sessionId}.

Headers: `X-Channel` (string)

Responses: `200`, `400`, `401`, `404`, `429`

#### `GET /ecom/kco/sessions/{sessionId}/confirmation` — Get KCO confirmation

Returns the Kustom Checkout confirmation HTML snippet and order details. Deprecated alias for GET /ecom/checkout/sessions/{sessionId}/confirmation.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

### Ecom.Account

Signing in: password, one-time code by email, and password reset. All of them upgrade the existing session rather than replacing it, so the cart carries over.

#### `POST /ecom/auth/login` — Login

Authenticates a customer contact using email and password. Associates the session with the customer.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `429`

#### `POST /ecom/auth/logout` — Log out

Ends the session behind the bearer token, server-side. The token stops working immediately, for this endpoint and every other one. Idempotent: a token that is already ended, expired or unknown also answers 204, so a retry after a lost response needs no special handling. Deleting your own cookie or clearing your token store is not a substitute — until this call lands, the token remains valid for the rest of its seven days, including the signed-in customer's orders and invoices. Call it before you drop the token. The cart hangs off the session, so it goes with it — the next session starts empty, signed in or not. That is the intended behaviour on a shared device; carry anything the visitor should keep on your own side before calling this.

Headers: `X-Channel` (string)

Responses: `204`, `401`, `429`

#### `POST /ecom/auth/one-time-login` — One-time code login

Authenticates a customer contact using a one-time email code. Associates the session with the customer.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `429`

#### `POST /ecom/auth/request-code` — Request auth code

Sends a 6-digit verification code to the specified email address. Used for password reset and one-time login.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `429`

#### `POST /ecom/auth/reset-password` — Reset password

Resets the customer password using a verified 6-digit code. Auto-logs in the customer on success.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `429`

#### `POST /ecom/auth/verify-code` — Verify auth code

Validates a 6-digit code without consuming it. Returns validity status and remaining attempts.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `429`

#### `GET /ecom/portal/context` — Get portal context

Returns portal modules and permissions for the authenticated customer contact.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `429`

### Ecom.Profile

The signed-in customer's own contact details.

#### `GET /ecom/portal/profile` — Get profile

Returns profile details for the authenticated customer contact.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `429`

#### `PATCH /ecom/portal/profile` — Update profile

Updates the authenticated contact's profile details.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `204`, `400`, `401`, `429`

### Ecom.Addresses

The signed-in customer's delivery addresses, including which one is the default.

#### `GET /ecom/portal/addresses` — List addresses

Returns delivery addresses for the authenticated customer.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `429`

#### `POST /ecom/portal/addresses` — Create address

Creates a new delivery address for the authenticated customer.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `403`, `429`

#### `PATCH /ecom/portal/addresses/{id}` — Update address

Updates an existing delivery address for the authenticated customer.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `204`, `400`, `401`, `404`, `429`

#### `DELETE /ecom/portal/addresses/{id}` — Delete address

Deletes a delivery address for the authenticated customer.

Headers: `X-Channel` (string)

Responses: `204`, `401`, `404`, `429`

#### `POST /ecom/portal/addresses/{id}/set-default` — Set default address

Sets a delivery address as the default for the authenticated customer.

Headers: `X-Channel` (string)

Responses: `204`, `401`, `404`, `429`

### Ecom.Orders

The signed-in customer's order history and order details, with line level fulfilment status.

#### `GET /ecom/portal/orders` — List orders

Returns a paginated list of orders for the authenticated customer.

Query parameters: `page` (integer; default `1`), `pageSize` (integer; default `20`), `status` (string)

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `429`

#### `GET /ecom/portal/orders/{id}` — Get order detail

Returns the full detail of a specific order for the authenticated customer.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

#### `GET /ecom/portal/orders/{id}/reorder` — Preview reorder

Returns the lines of an earlier order with last time's and today's unit price, and the lines that can no longer be ordered with a reason. Nothing is added to the cart; lines are always added at today's price with POST /ecom/cart/lines.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `404`, `429`

### Ecom.Invoices

The signed-in customer's invoices.

#### `GET /ecom/portal/invoices` — List invoices

Returns invoices for the authenticated customer.

Query parameters: `page` (integer; default `1`), `pageSize` (integer; default `20`), `status` (string)

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `429`

### Ecom.Shipments

Deliveries against the signed-in customer's orders, with carrier tracking where the carrier provides it.

#### `GET /ecom/portal/shipments` — List shipments

Returns a paginated list of shipments for the authenticated customer. trackingUrl links to the carrier's tracking page for trackingNumber when the shipping method has a tracking-link template, and is null otherwise.

Query parameters: `page` (integer; default `1`), `pageSize` (integer; default `20`), `status` (string)

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `429`

#### `GET /ecom/portal/shipments/{id}` — Get shipment detail

Returns the full detail of a specific shipment for the authenticated customer. trackingUrl links to the carrier's tracking page for trackingNumber when the shipping method has a tracking-link template, and is null otherwise. Each package carries its own trackingUrl: the same template applied to the package's tracking number.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

### Ecom.Quotes

Quote requests: a signed-in customer asks for a price on a set of items, then accepts or declines what comes back. An accepted quote becomes a sales order in the ERP.

#### `GET /ecom/portal/quotes` — List quotes

Returns a paginated list of quotes for the authenticated customer.

Query parameters: `page` (integer; default `1`), `pageSize` (integer; default `20`), `status` (string)

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `429`

#### `POST /ecom/portal/quotes/request` — Request a quote

Creates a new quote request from the customer portal.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `201`, `400`, `401`, `403`, `429`

#### `GET /ecom/portal/quotes/{id}` — Get quote detail

Returns the full detail of a specific quote for the authenticated customer.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

#### `POST /ecom/portal/quotes/{id}/accept` — Accept a quote

Accepts a sent quote on behalf of the authenticated customer.

Headers: `X-Channel` (string)

Responses: `204`, `400`, `401`, `404`, `429`

#### `POST /ecom/portal/quotes/{id}/decline` — Decline a quote

Declines a sent quote on behalf of the authenticated customer.

Headers: `X-Channel` (string)

Request body: `application/json`

Responses: `204`, `400`, `401`, `404`, `429`

### Ecom.Returns

Customer-initiated returns: check what an order is eligible to return, register the return, print the label and follow it. Registering moves no stock — receiving at the warehouse does.

#### `GET /ecom/portal/orders/{orderId}/return-eligibility` — Check return eligibility

Checks whether an order is eligible for return and returns returnable line details.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

#### `GET /ecom/portal/returns` — List returns

Returns a paginated list of returns for the authenticated customer.

Query parameters: `page` (integer; default `1`), `pageSize` (integer; default `20`), `status` (string)

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `429`

#### `POST /ecom/portal/returns` — Submit return

Creates a new return request from the customer portal.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `201`, `400`, `401`, `403`, `429`

#### `POST /ecom/portal/returns/orderless` — Submit return without order

Creates a return request for a product that was not bought through an order in the shop. Always reviewed manually.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `201`, `400`, `401`, `403`, `429`

#### `GET /ecom/portal/returns/products` — Search products for a return without order

Searches sellable products (including discontinued) by item number or name. Needs at least two characters.

Query parameters: `search` (string)

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `429`

#### `GET /ecom/portal/returns/{id}` — Get return detail

Returns the full detail of a specific return for the authenticated customer.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `404`, `429`

#### `POST /ecom/portal/returns/{id}/attachments` — Upload return attachment

Uploads one file to the return while it is being reviewed. Multipart form data with the file in the 'file' field.

Headers: `X-Channel` (string)

Request body: `multipart/form-data` (required)

Responses: `201`, `400`, `401`, `403`, `404`, `429`

#### `POST /ecom/portal/returns/{id}/cancel` — Cancel return

Cancels a return request that has not yet been received.

Headers: `X-Channel` (string)

Responses: `204`, `400`, `401`, `404`, `429`

#### `GET /ecom/portal/returns/{id}/label` — Get return label

Downloads or redirects to the return shipping label for a return.

Headers: `X-Channel` (string)

Responses: `302`, `401`, `404`, `429`

### Ecom.Tickets

Support cases the customer opens from their own pages, with the message thread and attachments. Cases land in the same queue as those created inside the ERP and from the support mailbox.

#### `GET /ecom/portal/tickets` — List tickets

Returns the authenticated contact's tickets. Contacts with the ViewAllTickets permission see every ticket belonging to their company.

Query parameters: `page` (integer; default `1`), `pageSize` (integer; default `20`), `status` (string), `openOnly` (boolean; default `false`), `search` (string)

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `429`

#### `POST /ecom/portal/tickets` — Create ticket

Creates a support ticket for the authenticated customer and contact. Order and order line are optional; when given they are verified against the session's customer and the item is taken from the order line.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `201`, `400`, `401`, `403`, `429`

#### `GET /ecom/portal/tickets/{id}` — Get ticket

Returns one ticket with its attachments and customer-visible messages. Internal notes are never included.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `404`, `429`

#### `POST /ecom/portal/tickets/{id}/attachments` — Upload ticket attachment

Uploads one file to the ticket. Multipart form data with the file in the 'file' field.

Headers: `X-Channel` (string)

Request body: `multipart/form-data` (required)

Responses: `201`, `400`, `401`, `403`, `404`, `429`

#### `GET /ecom/portal/tickets/{id}/attachments/{attachmentId}` — Download ticket attachment

Downloads one attachment from a ticket the contact is allowed to see.

Headers: `X-Channel` (string)

Responses: `200`, `401`, `403`, `404`, `429`

#### `POST /ecom/portal/tickets/{id}/comments` — Reply on ticket

Adds a customer-visible message to the ticket thread.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `201`, `400`, `401`, `403`, `404`, `429`

#### `PATCH /ecom/portal/tickets/{id}/product` — Supply product details on ticket

Lets the customer fill in serial number, firmware and hardware revision. The completion is added to the ticket thread so the agent sees it arrive.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `204`, `400`, `401`, `403`, `404`, `429`

### Ecom.Reviews

Product reviews: read the approved ones, submit a new one. Submissions are anonymous-capable and go through moderation before they appear.

#### `GET /ecom/catalog/products/{idOrSlug}/reviews` — Get product reviews

Returns a page of approved reviews plus a rating summary (average and distribution) covering all approved reviews for the product on this channel.

Query parameters: `page` (integer; default `1`), `pageSize` (integer; default `10`), `sort` (string)

Headers: `X-Channel` (string)

Responses: `200`, `404`, `429`

#### `POST /ecom/catalog/products/{idOrSlug}/reviews` — Submit product review

Submits a review for a product on the current channel. The review is always created as pending and is not visible until a moderator approves it.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `404`, `409`, `429`

### Ecom.Newsletter

Newsletter sign-up with double opt-in, and one-click unsubscribe per RFC 8058. The unsubscribe endpoint is quota'd per token rather than per IP, because mail providers share addresses across many recipients.

#### `POST /ecom/newsletter/confirm` — Confirm newsletter subscription

Confirms a pending newsletter subscription using the token from the confirmation email. The token is consumed and cannot be reused.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `404`, `409`, `429`

#### `POST /ecom/newsletter/subscribe` — Subscribe to newsletter

Signs an email address up for the channel newsletter. Always double opt-in: a confirmation email is sent and the subscription is not mailable until the link is followed.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `404`, `429`

#### `POST /ecom/newsletter/unsubscribe` — Unsubscribe from newsletter

Withdraws newsletter consent using the token from an email, passed as a query parameter. Requires no login — one-click unsubscribe per RFC 8058. Idempotent; any request body is ignored.

Query parameters: `token` (string)

Headers: `X-Channel` (string)

Responses: `200`, `400`, `404`, `429`

### Ecom.Chat

The shopping assistant: a server-sent event stream that answers product questions against the channel's own catalogue and content.

#### `POST /ecom/chat/stream` — Ask the shopping assistant

Answers a shopper's question against the channel's own catalogue and content, and streams the reply as server-sent events rather than returning a body. Each event is a `data:` line carrying a JSON fragment; concatenate the text fragments as they arrive and stop at the terminating event. Because the response is a stream, the 200 has no schema to document — read the event format from the frames themselves. Requires a session, and is enabled per channel through the enableChatAssistant feature flag. Tool results carry only product cards (id, name, slug, image, and price and stock when the channel shows them), and an error event carries a generic message rather than the underlying one.

Headers: `X-Channel` (string), `X-Language` (string)

Request body: `application/json` (required)

Responses: `200`, `400`, `401`, `429`

### Ecom.Analytics

Page-view ingestion for the tenant's own storefront reporting, feeding the SEO and traffic views inside Fluit. It records what your storefront tells it; it is not a public analytics service.

#### `POST /ecom/analytics/event` — Track a purchase funnel step

Records that a visitor took a step in the purchase funnel, named as the GA4 e-commerce event: view_item, add_to_cart, begin_checkout, add_shipping_info, add_payment_info or purchase. Cookie-free; ignored when the channel's analytics is off or the visitor is a bot. Called server-side from ecom-frontend.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `204`, `400`, `429`

#### `POST /ecom/analytics/pageview` — Track page view

Records a page view for analytics. Called server-side from ecom-frontend.

Headers: `X-Channel` (string)

Request body: `application/json` (required)

Responses: `204`, `429`