Skip to content

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.

Base URLhttps://suppliers.presslane.ai

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

    Request
    curl -sS -u "$CLIENT_ID:$CLIENT_SECRET" \
      -d grant_type=client_credentials \
      -d "scope=catalogue:read stock:read" \
      https://suppliers.presslane.ai/oauth/token
    Response
    {
      "access_token": "eyJhbGciOiJFUzI1NiIs…",
      "token_type": "Bearer",
      "expires_in": 900,
      "scope": "catalogue:read stock:read"
    }
  2. 2. Call the API

    Send the token as Authorization: Bearer <token> on every /v1 call.

    Request
    curl -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. 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.

Scopes
ScopeWhat it allows
accounts:readPartner: read accounts, plans and usage.
accounts:writePartner: create, update, suspend and cancel accounts; issue and revoke account credentials; open billing pages.
catalogue:readAccount: suppliers, products and variants.
inventory:writeSupplier (phase 2): push stock for one supplier.
links:readAccount: read links.
links:writeAccount: create, change and remove links; ask for match suggestions.
orders:readAccount: orders placed here, and the supplier's own order history, invoices and live stock.
orders:writeAccount: place orders with suppliers and manage the account's supplier API connections.
stock:readAccount: availability, quantity checks and the changes feed.
usage:readAccount: the account's own usage.
webhooks:writeAccount 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 header Sandbox: 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/json with 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) and starting_after. An answer has data, has_more and next_cursor; pass next_cursor as starting_after for 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 in If-None-Match: if nothing changed the answer is 304 with 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" }.

A 400 answer
{
  "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…"
}
Error codes
HTTPcodeWhat to do
400invalid_requestFix the request; errors names each field.
401invalid_tokenGet a new token. If that fails too, the client was revoked.
403insufficient_scopeAsk for the scope when you get the token.
403account_suspendedThe account is unpaid, cancelled or locked: hide stock, keep links.
403allowance_exceededOver the plan’s linked variants: change plan or remove links.
403forbiddenThis kind of client cannot call this (an account token on a partner endpoint).
404not_foundThe ID or slug does not exist for this client.
409conflictThe resource is in a state that does not allow this.
409idempotency_conflictThe same Idempotency-Key came with a different body.
409supplier_feature_unavailableThe supplier has no API, or not this feature, or ordering from it is off.
409supplier_not_connectedConnect the account’s own login at the supplier first.
409supplier_auth_failedThe supplier refused the account’s login: connect it again.
410cursor_expiredThe changes cursor is past the 30 days kept: read again in full.
429rate_limitedWait Retry-After seconds.
502supplier_unavailableThe supplier’s API did not answer: retry later.
500, 503internal_errorRetry 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-Remaining and RateLimit-Reset (seconds); a 429 adds Retry-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-Policy says “monthly allowance used”.
  • Every 2xx answer and every 4xx except 401 counts as a request; a 304 does not. GET /v1/usage gives 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.