List or search products

List products, or search with q.

Without q, products are ordered by name; page with cursor. With q, results are ranked by relevance and paged with offset; limit is capped at 250. A q that looks like a barcode (at least 8 letters, digits, - or _, including a digit) matches barcode and barcodeAliases exactly instead of searching text.

Search results carry a reduced set of fields: id, name, price, barcode, supplier, category, externalId, taxCategory, margin, imageUrl, allowStore, hideStore, the sale fields, deactivated, ageRestriction, showOnScreen, openInput and showOnScale. Fetch a product by id for the full record.

GET/products

Authorization

AuthorizationBearer token (API key) · headerrequired

Organization API key.

Query parameters

qstring

Search text. Switches to search: offset paging, limit capped at 250.

limitinteger

Page size (1–5000, default 100). With q, values above 250 are reduced to 250; meta.limit shows the applied value.

min 1 · max 5000 · default: 100

offsetinteger

Number of search hits to skip. Only with q; ignored otherwise.

min 0 · max 10000 · default: 0

storestring

Only products visible in this store (store id). Works with and without q. With q, meta.total then counts the filtered page instead of estimating all matches.

min length 1

cursorstring

meta.nextCursor from the previous page. Only without q (sending both returns 400). Do not parse it; an unknown cursor starts again at the first page.

min length 1

Responses

200

List of products with meta.

dataProduct[]required

Show properties

Array of Product

idstringrequired

Product document id

externalIdstring

Optional external identifier

namestring

priceinteger

Price in cents.

supplierstring

Supplier id

taxCategorystring

Swiss VAT category code

Allowed:8.12.63.80

categorystring

Category id

declarationsstring

barcodestring

barcodeAliasesobject[]

Optional additional EANs. Absent when unused. Empty array is not persisted. Available when the barcode aliases feature is enabled for the organization.

Show properties

Array of object

codestringrequired

Additional EAN, lowercased like barcode

quantitynumber

Base units represented by this code. Defaults to 1.

priceinteger

Optional pack price in cents

labelstring

externalIdstring

Optional external article ID

depositProductinteger

Deposit in cents.

depositProductLabelstring

descriptionstring

salePriceinteger

Sale price in cents.

salePercentagenumber

salePriceDateFromstring<date-time>

salePriceDateTostring<date-time>

costPriceinteger

Cost price in cents.

marginnumber

showOnScreenboolean

ageRestrictionboolean

showOnScaleboolean

saleStopboolean

deactivatedboolean

openInputboolean

imageUrlstring

Image URL. Set via product create/update or POST /products/{productId}/image. Empty string on update clears the field and deletes org-owned storage.

indexinteger

allowStorestring[]

Allowed store ids (read-only).

hideStorestring[]

Hidden store ids (read-only).

deletedboolean

Soft-deleted when true.

createdatestring<date-time>

lastupdatestring<date-time>

instancestring

Organization id when present

metaListMetarequired

List metadata. returned is the length of data. Soft-deleted catalog rows are omitted from list results, so returned may be less than limit even when more active items exist. When nextCursor is present, more pages may exist — keep paging until nextCursor is absent.

Show properties

totalintegerrequired

With product search (q) without store: estimated match count. With store: equals returned after store visibility filtering. Otherwise equals returned. Soft-deleted items are omitted, so a page may be shorter than limit even when more active items exist.

returnedintegerrequired

Number of items in data. With includeDeleted=true (orders), deleted orders count too.

limitintegerrequired

Applied page size.

offsetinteger

Only for product search with q.

nextCursorstring

Opaque cursor for the next page; pass it unchanged as cursor. Present when more results may exist. Soft-deleted rows are filtered out after reading, so a page can be shorter than limit while nextCursor is set. Never returned for categories, suppliers and stores, which are not paginated.

400

Invalid query parameters.

errorValidationErrorrequired

Validation details.

Show properties

formErrorsstring[]required

fieldErrorsobjectrequired

403

Missing, unknown or inactive API key, or a Read key on a write operation.

statusCodeintegerrequired

HTTP status code

messagestringrequired

Human-readable error message

timestampstring<date-time>required

When the error occurred (UTC).

pathstringrequired

Request URL (path and query string).

503

Product search is temporarily unavailable.

errorstringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (API key)Remember on this deviceInclude my values in samples

Parameters

qquerySearch text. Switches to search: `offset` paging, `limit` capped at 250.limitqueryPage size (1–5000, default 100). With `q`, values above 250 are reduced to 250; `meta.limit` shows the applied value.offsetqueryNumber of search hits to skip. Only with `q`; ignored otherwise.storequeryOnly products visible in this store (store id). Works with and without `q`. With `q`, `meta.total` then counts the filtered page instead of estimating all matches.cursorquery`meta.nextCursor` from the previous page. Only without `q` (sending both returns 400). Do not parse it; an unknown cursor starts again at the first page.

Request

curl -X GET 'https://dashboard.scango.ch/api/v1/products' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response = await fetch("https://dashboard.scango.ch/api/v1/products", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://dashboard.scango.ch/api/v1/products",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://dashboard.scango.ch/api/v1/products',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_TOKEN',
    'Accept: application/json',
  ],
]);

$response = curl_exec($curl);

Response

{
  "data": [
    {
      "id": "a1b2c3",
      "name": "Mineral water 50cl",
      "price": 120,
      "barcode": "7610800001234",
      "taxCategory": "2.6",
      "category": "cat_01",
      "supplier": "sup_01",
      "showOnScreen": true
    }
  ],
  "meta": {
    "total": 1,
    "returned": 1,
    "limit": 1,
    "nextCursor": "a1b2c3"
  }
}

{
  "data": [
    {
      "id": "a1b2c3",
      "name": "Mineral water 50cl",
      "price": 120,
      "barcode": "7610800001234",
      "taxCategory": "2.6"
    }
  ],
  "meta": {
    "total": 42,
    "returned": 20,
    "limit": 20,
    "offset": 0
  }
}

{
  "error": {
    "formErrors": [],
    "fieldErrors": {
      "limit": [
        "Number must be less than or equal to 5000"
      ]
    }
  }
}

{
  "statusCode": 403,
  "message": "Unknown Error",
  "timestamp": "2024-04-20T12:00:00.000Z",
  "path": "/api/v1/products"
}

{
  "error": "Product search failed"
}