Voorraadwijzigingen doorbladeren

GET /api/v1/stock/changes toont de wijzigingen in je voorraad: correcties, en reserveringen die zijn gemaakt en vrijgegeven. Deze pagina legt uit hoe je erdoor bladert, en hoe je hem pollt zonder een wijziging te missen.

Hoe een pagina eruitziet

De wijzigingen komen nieuwste eerst, 50 per pagina, tenzij je om een andere per_page vraagt (maximaal 200). Het object pagination zegt waar je bent:

curl "https://picked.nl/api/v1/stock/changes?per_page=100&page=1" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

{
    "data": [
        {
            "id": 90211,
            "occurredAt": "2026-10-10T06:42:17+00:00",
            "eventType": "stock_adjusted",
            "productSku": "BEL-ZW-01",
            "warehouseCode": "UTR",
            "locationName": "A-03-2",
            "quantity": -2,
            "reason": "damaged",
            "movementUuid": "9b2f6c1e-4d7a-4f0b-8c3e-2a5d7e9f1b40"
        }
    ],
    "pagination": {
        "currentPage": 1,
        "perPage": 100,
        "lastPage": 1,
        "total": 1,
        "from": 1,
        "to": 1
    },
    "_links": {
        "self": { "href": "/api/v1/stock/changes?per_page=100&page=1" }
    }
}

Volg _links.next tot die ontbreekt, of vraag steeds de volgende page op tot currentPage gelijk is aan lastPage. De sleutels van dit endpoint zijn camelCase, anders dan in de rest van de API; v1 houdt dat zo.

eventType is stock_adjusted, stock_reserved of stock_reservation_released. Bij stock_adjusted heeft quantity een teken: een negatief getal is voorraad die eruit ging. Bij de twee reserveringstypen is het altijd positief.

Filters

Een filter dat niets oplevert, geeft een lege pagina, geen fout.

Pollen zonder iets te missen

Paginanummers zijn om door te bladeren. Omdat de nieuwste wijziging bovenaan staat, schuift een wijziging die binnenkomt terwijl je bladert alles één plek op, en lees je één wijziging dubbel of sla je er één over. Wil je een systeem bijhouden, lees dan met een cursor:

1. Vraag de eerste keer de wijzigingen na cursor 0 op: GET /api/v1/stock/changes/feed?after=0. Ze komen oudste eerst, maximaal per_page tegelijk.
2. Verwerk ze en bewaar daarna de nextCursor uit het antwoord.
3. Zolang hasMore true is, volg je meteen _links.next: die vraagt opnieuw met after op die cursor en je filters erin. Is het false, dan heb je alles tot nu toe; wacht op je volgende poll en vraag dan opnieuw vanaf de cursor die je bewaarde.

curl -G "https://picked.nl/api/v1/stock/changes/feed" \
  --data-urlencode "after=0" \
  --data-urlencode "per_page=200" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

{
    "data": [
        {
            "id": 90211,
            "occurredAt": "2026-10-10T06:42:17+00:00",
            "eventType": "stock_adjusted",
            "productSku": "BEL-ZW-01",
            "warehouseCode": "UTR",
            "locationName": "A-03-2",
            "quantity": -2,
            "reason": "damaged",
            "movementUuid": "9b2f6c1e-4d7a-4f0b-8c3e-2a5d7e9f1b40"
        }
    ],
    "nextCursor": "184467",
    "hasMore": false,
    "_links": {
        "self": { "href": "/api/v1/stock/changes/feed?after=0&per_page=200" }
    }
}

Een wijziging die binnenkomt terwijl je leest, valt na je cursor, dus je slaat hem niet over en leest hem niet dubbel. Is er niets nieuws, dan is nextCursor de cursor die je stuurde. Behandel de cursor als een ondoorzichtige tekst: bewaar hem en stuur hem terug, maar vergelijk of reken er niet mee. Hij blijft altijd geldig. Een wijziging bereikt de cursor ongeveer vijf seconden nadat ze is opgeslagen; door dat wachten komen wijzigingen die vlak na elkaar zijn opgeslagen in volgorde binnen. De feed neemt dezelfde filters als de pagina's.

Elke minuut of twee pollen blijft ruim binnen de rate limit van de voorraad-endpoints.

Wijzigingen of niveaus?

Voorraadwijzigingen vertellen je wat er met de voorraad in de stellingen gebeurde. Wat orders vastleggen, zit er niet in: een geaccepteerde order verlaagt het getal sellable van een product zonder dat er een voorraadwijziging bij komt. Bepaal dus niet aan de hand van de wijzigingen welke producten je in een webshop bijwerkt. Vraag in plaats daarvan GET /api/v1/stock?changed_since=<moment>: dat geeft de niveaus van elk product waarvan de voorraad, de orderclaims of de locaties sindsdien veranderden, sellable inbegrepen. De voorraad in je webshop bijhouden laat zien hoe.