API docs · v1
Presslane Suppliers API
Live wholesale stock by colour and size, from every supplier in the directory, in one shape. Look up what is in stock, how many and when more arrives; link your own variants; and order from suppliers whose APIs take orders.
https://suppliers.presslane.aiQuickstart
A token and a first call, in two requests.
API reference
Every endpoint, its parameters and answers.
Sandbox
Send real requests from your browser.
Quickstart
JSON over HTTPS, with OAuth 2 client credentials. You need a client ID and secret (see Authentication); to try the API before you use it for real, ask for a sandbox account.
1. Get a token
Send your client ID and secret with HTTP Basic. The token lasts 15 minutes: keep it and ask again shortly before it runs out.
Requestcurl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \ -d grant_type=client_credentials \ -d "scope=catalogue:read stock:read" \ https://suppliers.presslane.ai/oauth/tokenResponse{ "access_token": "eyJhbGciOiJFUzI1NiIs…", "token_type": "Bearer", "expires_in": 900, "scope": "catalogue:read stock:read" }2. Call the API
Send the token as
Authorization: Bearer <token>on every/v1call.Requestcurl -sS https://suppliers.presslane.ai/v1/suppliers?limit=2 \ -H "Authorization: Bearer $TOKEN"Response{ "data": [ { "id": "sup_01m73…", "name": "Uneek Clothing", "slug": "uneek-clothing", … }, { "id": "sup_01m750…", "name": "Ralawise", "slug": "ralawise", … } ], "has_more": true, "next_cursor": "sup_01m750…" }3. Try the rest
The API reference lists every endpoint. The sandbox sends any of them from this page with your credentials and shows the answer, with the same request as curl.
Authentication
Every call carries a Bearer token from POST /oauth/token (client credentials grant). Authenticate with HTTP Basic (preferred) or client_id and client_secret in the form body, not both. The token is a JWT valid for 15 minutes; there is no refresh token. Treat it as opaque.
There are two kinds of client. A partner client (a platform such as Novia) switches its tenants on and off and issues their credentials. An account client belongs to one tenant and reads stock, links variants and orders for that tenant. A client secret is shown once, when it is created: keep it on your server.
Leave scope out to get all of the client’s scopes, or ask for fewer. 120 token requests a minute per client: never get a token per call.
| Scope | What it allows |
|---|---|
| accounts:read | Partner: read accounts, plans and usage. |
| accounts:write | Partner: create, update, suspend and cancel accounts; issue and revoke account credentials; open billing pages. |
| catalogue:read | Account: suppliers, products and variants. |
| inventory:write | Supplier (phase 2): push stock for one supplier. |
| links:read | Account: read links. |
| links:write | Account: create, change and remove links; ask for match suggestions. |
| orders:read | Account: orders placed here, and the supplier's own order history, invoices and live stock. |
| orders:write | Account: place orders with suppliers and manage the account's supplier API connections. |
| stock:read | Account: availability, quantity checks and the changes feed. |
| usage:read | Account: the account's own usage. |
| webhooks:write | Account or partner: manage webhook endpoints and resend deliveries. |
Sandbox accounts
A sandbox account is an ordinary account set aside for trying the API. It reads the real catalogue and stock, so what you build against it behaves as it will in production, but:
- its orders are only ever recorded as tests (status
test, with the exact request the supplier would get) and never sent to a supplier, whatever the supplier’s order mode; - it is never charged;
- its token answer has
"sandbox": true, and every API answer to it carries the headerSandbox: true.
Everything else is real: links, webhook endpoints and deliveries, and connecting a login at a supplier (checked with a read at that supplier). Presslane Suppliers sets accounts up as sandboxes: write to suppliers@noviadigital.io for one, with its client ID and secret.
Requests and responses
- JSON in and out, UTF-8. Send
Content-Type: application/jsonwith a body. Unknown fields in answers will appear over time: ignore what you do not know. - Lists are pages:
limit(up to the endpoint’s maximum) andstarting_after. An answer hasdata,has_moreandnext_cursor; passnext_cursorasstarting_afterfor the next page. - Idempotency: send an
Idempotency-Key(a new UUID per operation) on every POST and PUT. A repeat within 24 hours returns the first answer, even one with a secret shown once. Reuse the key when you retry; never for a different request. - ETags: GET answers carry an
ETag. Send it back inIf-None-Match: if nothing changed the answer is304with no body, and it does not count towards usage. - Request IDs: every answer has
X-Request-Id. Log it, and quote it when you report a problem. - Timeouts: time calls out after 10 seconds. Retry 429 and 5xx answers with exponential backoff and the same
Idempotency-Key; do not retry other 4xx answers.
Errors
Errors are RFC 9457 application/problem+json. Branch on code, never on the wording of title or detail. The OAuth endpoints answer in OAuth’s own shape, { "error", "error_description" }.
{
"type": "https://suppliers.presslane.ai/problems/invalid_request",
"title": "The request is not valid",
"status": 400,
"code": "invalid_request",
"detail": "…",
"errors": [{ "path": "items.0.gtin", "message": "8 to 14 digits" }],
"request_id": "req_01m7…"
}| HTTP | code | What to do |
|---|---|---|
| 400 | invalid_request | Fix the request; errors names each field. |
| 401 | invalid_token | Get a new token. If that fails too, the client was revoked. |
| 403 | insufficient_scope | Ask for the scope when you get the token. |
| 403 | account_suspended | The account is unpaid, cancelled or locked: hide stock, keep links. |
| 403 | allowance_exceeded | Over the plan’s linked variants: change plan or remove links. |
| 403 | forbidden | This kind of client cannot call this (an account token on a partner endpoint). |
| 404 | not_found | The ID or slug does not exist for this client. |
| 409 | conflict | The resource is in a state that does not allow this. |
| 409 | idempotency_conflict | The same Idempotency-Key came with a different body. |
| 409 | supplier_feature_unavailable | The supplier has no API, or not this feature, or ordering from it is off. |
| 409 | supplier_not_connected | Connect the account’s own login at the supplier first. |
| 409 | supplier_auth_failed | The supplier refused the account’s login: connect it again. |
| 410 | cursor_expired | The changes cursor is past the 30 days kept: read again in full. |
| 429 | rate_limited | Wait Retry-After seconds. |
| 502 | supplier_unavailable | The supplier’s API did not answer: retry later. |
| 500, 503 | internal_error | Retry with backoff, and quote request_id if it goes on. |
Rate limits and usage
- Each client may make 20 requests a second. Every answer carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset(seconds); a 429 addsRetry-After. - Past the plan’s monthly request allowance, a client is slowed to 1 request a second until the month resets. It is not charged, and
RateLimit-Policysays “monthly allowance used”. - Every 2xx answer and every 4xx except 401 counts as a request; a 304 does not.
GET /v1/usagegives the account’s period, allowances and daily figures. Batch lookups and checks (up to 500 per call) to stay well inside.
Versioning
/v1 changes only by adding: new fields, endpoints and enum values. Ignore what you do not know, and treat enums as open. The machine-readable description is OpenAPI 3.1, at /v1/openapi.json.