01Authentication
- Scope
api:read- Header
Authorization: Bearer YOUR_API_KEYorX-API-Key: YOUR_API_KEY- Plan
Your plan must include API access. The key binds the request to your account.
02Query parameters
| Parameter | Behaviour |
|---|---|
limit | Default 50. Values are clamped to 1 through 200. |
cursor | Pass the previous response’s nextCursor unchanged. Omit it for the first page. A malformed cursor returns 400. |
03Request
curl "https://api.test.stockisto.com/api/public/v1/retailers?limit=50" \
-H "Authorization: Bearer $STOCKISTO_API_KEY"
04Response
A brand sees active linked retailers with an eligible, publicly visible location. A retailer sees its own active record. Results follow retailer id order. Continue until nextCursor is null. A 200 response has this envelope; data contains the available records:
{ "data": [], "nextCursor": null }
| Field | Type and meaning |
|---|---|
data[].id | UUID. Retailer id. |
data[].name | String. Retailer name. |
data[].website | String or null. |
data[].city | String or null. |
data[].country | String or null. |
nextCursor | Opaque string or null. Return it as cursor. |
GET /api/public/v1/locations uses the same pagination and key. It returns visible locations: id, retailerId, address, contact details, coordinates and opening hours. Supplier results also respect relationship country scopes.
curl "https://api.test.stockisto.com/api/public/v1/locations?limit=50" \
-H "Authorization: Bearer $STOCKISTO_API_KEY"
05Errors and limits
| Response | Your next step |
|---|---|
| 400 | Use the exact nextCursor returned. |
| 401 | Check expiry and revocation. Verify the key with /api/public/v1/ping. |
402 | Read feature_key in the response and choose a plan with that feature on Pricing. Pricing |
| 403 | Use a key with api:read. |
| 429 | Wait for Retry-After; check the rate and monthly quota. |
| 503 | The limit check is unavailable. Retry after Retry-After. |
Default 300 requests per minute per key. Global limits and your monthly quota also apply. Ask us to raise the key limit.