Shop API

Every ShopKollect shop exposes the same public JSON API. The ShopKollect app uses it; you can use it for your own apps or integrations.

Base URL

The shop address (subdomain or the merchant's domain), followed by /api/v1. Example:

https://demo.shopkollect.com/api/v1/products

Language

Accept-Language header (fr, en, es, ar); falls back to the shop's language.

Prices

In cents, taxes included, with a formatted version. The server always re-checks prices, stock, opening hours and compositions.

Authentication

Catalogue and ordering need no account. Customer account: personal token "Authorization: Bearer …" obtained at login, specific to the shop.

Errors and limits

Errors {"message", "errors"} (422 validation, 401 token, 404, 429 too many requests). Rate limited per IP address.

OpenAPI

OpenAPI 3.1 file

Discovery and shop

GET /.well-known/shopkollect.json Shop card: name, logo, colours, languages, currency, modules, API base URL.

GET /api/v1/shop Contact details, open / closed state and message, pages (terms, legal notice…).

GET /api/v1/pickup-slots Today's pickup times (HH:MM); "required" tells whether a time must be chosen.

Catalogue

GET /api/v1/categories Visible categories, with the number of products for sale.

GET /api/v1/products Products for sale: prices incl. tax in cents, sale price, images (320 / 640 / 1024 px), stock, "composable". category category id or slugq search (2 characters min.)sort position, new, price_asc, price_desc, name

GET /api/v1/products/{slug} Full product: description, allergens, product page URL.

GET /api/v1/products/{slug}/composition Smart Kiosk journey of the product (pages, options, prices, min / max rules): same definition as the kiosk.

Cart and orders

POST /api/v1/cart/quote The cart lives in the app: the server returns priced lines (compositions included), the total and per-line errors. lines [{product: id or slug, quantity, selection?: {page_id: {option_id: quantity}}}]

POST /api/v1/orders Places the order (pay on site) → number and tracking token. Same checks as the website: opening hours, stock, pickup time. lines [{product: id or slug, quantity, selection?: {page_id: {option_id: quantity}}}]name stringphone stringemail stringnote stringpickup_time HH:MM, from /pickup-slotsaccept terms accepted (required)

GET /api/v1/orders/{number} Tracking: status (new, preparing, ready, collected, cancelled), pickup time, lines. With the tracking token or the customer token. token order tracking token

POST /api/v1/devices Registers a phone (Firebase token) for "order ready" / "cancelled" notifications, linked to the tracked orders. token stringplatform android | ioslocale stringorders [{number, token}]

DELETE /api/v1/devices Unregisters a phone. token string

Customer account (per shop)

POST /api/v1/auth/register Creates the account → personal token (one per device). A customer who already ordered as a guest keeps their history. name stringemail stringphone stringpassword stringnewsletter booleandevice_name string

POST /api/v1/auth/login Login → personal token. 5 attempts per minute. email stringpassword stringdevice_name string

POST /api/v1/auth/password Forgotten password: sends the same e-mail as the website. email string

DELETE /api/v1/auth/token token Logout: revokes the token used.

GET /api/v1/me token Customer profile.

PUT /api/v1/me token Updates name, e-mail, phone, newsletter, language, password.

GET /api/v1/me/orders token Last 50 orders.

GET /api/v1/me/export token Data export (GDPR), JSON.

DELETE /api/v1/me token Deletes the account (confirm=true); orders stay with the shop, unlinked from the customer. confirm boolean