De voorraad in je webshop bijhouden

Laat je klanten alleen zien wat je magazijn kan leveren. Lees op vaste momenten het sellable-cijfer van je producten uit Picked en zet dat in je shop.

Wanneer gebruik je dit

Gebruik dit recept als je webshop niet bij de ingebouwde koppelingen staat. Een gekoppelde shop krijgt zijn voorraad vanzelf van Picked.

Je hebt een token nodig met het recht stock:read (zie Authenticatie en rechten).

Welk cijfer je publiceert

GET /api/v1/stock geeft per product vier cijfers, in totaal en per magazijn:

Publiceer sellable. Dat is het cijfer dat Picked zelf naar gekoppelde shops stuurt. Neem het totaal, niet de som van de magazijnen: elk magazijn stopt bij nul, dus de magazijnen tellen er niet altijd precies toe op.

Veel producten tegelijk lezen

Vraag tot 100 SKU's per aanroep op, gescheiden door komma's:

curl "https://picked.nl/api/v1/stock?skus=BEL-ZW-01,BAND-28-622" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "sku": "BEL-ZW-01",
      "quantity": 40,
      "reserved": 4,
      "available": 36,
      "sellable": 30,
      "warehouses": [
        { "code": "UTR", "quantity": 40, "reserved": 4, "available": 36, "sellable": 30 }
      ],
      "_links": { "self": { "href": "/api/v1/stock?sku=BEL-ZW-01" } }
    },
    {
      "sku": "BAND-28-622",
      "quantity": 0,
      "reserved": 0,
      "available": 0,
      "sellable": 0,
      "warehouses": [],
      "_links": { "self": { "href": "/api/v1/stock?sku=BAND-28-622" } }
    }
  ],
  "_links": {
    "self": { "href": "/api/v1/stock?skus=BEL-ZW-01%2CBAND-28-622" }
  }
}

Het antwoord noemt elke SKU één keer, in de volgorde waarin je vroeg. Een SKU die Picked niet kent, komt terug met nullen, dus een tikfout lijkt op een leeg schap. Controleer nieuwe SKU's daarom één keer los; voor een onbekende SKU geeft dat 404.

curl "https://picked.nl/api/v1/stock?sku=BEL-ZW-01" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

HTTP/1.1 200 OK
Content-Type: application/json

{
  "sku": "BEL-ZW-01",
  "quantity": 40,
  "reserved": 4,
  "available": 36,
  "sellable": 30,
  "warehouses": [
    { "code": "UTR", "quantity": 40, "reserved": 4, "available": 36, "sellable": 30 }
  ],
  "_links": {
    "self": { "href": "/api/v1/stock?sku=BEL-ZW-01" }
  }
}

Actueel houden

1. Eerste keer. Loop je assortiment door in groepen van 100 SKU's en publiceer elk sellable-cijfer.
2. Daarna vragen wat er veranderde. Vraag elke minuut of twee naar de producten waarvan sellable sinds je vorige poll veranderd kan zijn, en publiceer die:

curl "https://picked.nl/api/v1/stock?changed_since=2026-10-12T08:59:00Z" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "sku": "BEL-ZW-01",
      "quantity": 40,
      "reserved": 4,
      "available": 36,
      "sellable": 30,
      "warehouses": [
        { "code": "UTR", "quantity": 40, "reserved": 4, "available": 36, "sellable": 30 }
      ],
      "_links": { "self": { "href": "/api/v1/stock?sku=BEL-ZW-01" } }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 100,
    "last_page": 1,
    "total": 1,
    "from": 1,
    "to": 1
  },
  "_links": {
    "self": { "href": "/api/v1/stock?changed_since=2026-10-12T08%3A59%3A00Z&page=1" }
  }
}

Het antwoord bevat elk product waarvan de voorraad veranderde, dat een order claimde of vrijgaf, of dat in een locatie ligt die veranderde, zoals een locatie waaruit je niet meer verkoopt. Volg _links.next tot die ontbreekt, of lees elke page tot current_page gelijk is aan last_page. Een product kan terugkomen met het cijfer dat het al had; het opnieuw publiceren kan geen kwaad. Een changed_since van meer dan 30 dagen terug geeft elk product, als volledige herlaadbeurt.

Noteer het moment waarop je elke poll begint, uit de Date-header van het laatste antwoord van Picked en niet van je eigen klok, en gebruik dat, min een minuut overlap, als changed_since van de volgende poll. De overlap vangt een wijziging op die net werd opgeslagen toen je vroeg.

Gebruik GET /api/v1/stock/changes niet om te kiezen welke producten je bijwerkt. Het toont wat er in de schappen gebeurde, maar een order die voorraad claimt, verlaagt sellable zonder voorraadwijziging. Voorraadwijzigingen doorbladeren legt uit waar dat endpoint wel voor is.

Of laat Picked de wijzigingen pushen

Abonneer in plaats van te pollen een URL op stock.changed in Instellingen → Ontwikkelaars → Webhooks: Picked POST de voorraad van het product, in dezelfde vorm als GET /api/v1/stock?sku=, telkens als het verkoopbare of beschikbare cijfer verandert. Houd een nachtelijke volledige uitlezing als vangnet. Zie Webhooks ontvangen.

Fouten afhandelen

Foutmeldingen noemt alle codes, en Rate limits wat je doet bij een 429.

Testen

Voorraad lezen schrijft niets, dus er valt niets proef te draaien. Laat je synchronisatie eerst op een testshop los, of draai hem één keer en vergelijk een paar producten met het voorraadoverzicht in Picked.