Orderwijzigingen volgen

Houd je eigen systeem bij met elke order die je naar Picked stuurde: elke keer dat een order een status krijgt, en elke keer dat een zending ervan wordt aangemaakt, een label krijgt, aan de vervoerder wordt meegegeven, of wordt bezorgd, mislukt of terugkomt. Eén aanroep leest alles wat er sinds je vorige keer veranderd is.

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

Lees de wijzigingen na een cursor

De eerste keer vraag je de wijzigingen na cursor 0: GET /api/v1/orders/changes?after=0. Ze komen oudste eerst, hooguit per_page tegelijk (standaard 50, hooguit 200).
Verwerk ze en bewaar de next_cursor uit het antwoord.
Zolang _links.next er staat, volg je die meteen. Staat hij er niet meer, dan heb je alles tot nu toe; wacht tot je volgende ronde en vraag opnieuw met after op de cursor die je bewaarde.

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

{
    "data": [
        {
            "cursor": "771042",
            "type": "shipment.dispatched",
            "occurred_at": "2026-10-12T15:48:09+02:00",
            "status": null,
            "order": {
                "id": 48211,
                "external_id": "WS-2026-104233",
                "status": "packed",
                "shipped_short": false,
                "fulfilment_method": "carrier",
                "warehouse_id": 12,
                "shipments": [
                    {
                        "id": 30554,
                        "carrier": "postnl",
                        "tracking_number": "3SPCKD0104233",
                        "tracking_url": "https://postnl.nl/tracktrace/?B=3SPCKD0104233&T=C",
                        "status": "handed_over",
                        "dispatched_at": "2026-10-12T15:48:09+02:00",
                        "parcels": []
                    }
                ],
                "updated_at": "2026-10-12T15:48:09+02:00",
                "_links": { "self": { "href": "/api/v1/orders/48211" } }
            },
            "_links": { "order": { "href": "/api/v1/orders/48211" } }
        }
    ],
    "next_cursor": "771042",
    "has_more": true,
    "_links": {
        "self": { "href": "/api/v1/orders/changes?after=771000&per_page=1" },
        "next": { "href": "/api/v1/orders/changes?after=771042&per_page=1" }
    }
}

Wat een wijziging zegt

`type`	Wanneer
`order.status_changed`	De order kreeg een status; `status` zegt welke.
`shipment.created`	Het magazijn maakte een zending voor de order aan.
`shipment.carrier_changed`	Hij ging naar een andere vervoerder, voordat het label gekocht was.
`shipment.label_created`	Het label is gekocht: vanaf hier is `tracking_number` bekend.
`shipment.dispatched`	De zending is aan de vervoerder meegegeven.
`shipment.delivered`	De vervoerder heeft hem bezorgd.
`shipment.failed`	De vervoerder kon hem niet bezorgen.
`shipment.returned`	Hij is terug in het magazijn.

Elke wijziging bevat de order zoals hij nu is, met zijn zendingen en tracking, en _links.order leest de hele order met zijn regels. Een order die intussen verder is, toont dus ook bij zijn oudere wijzigingen zijn nieuwste status: lees status bij een order.status_changed voor de status waar die wijziging over ging.

Cursors en timing

Elke wijziging komt één keer, in de volgorde waarin hij gebeurde. Is er niets nieuws, dan is next_cursor 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 voorgoed geldig. Een wijziging komt ongeveer vijf seconden nadat hij is opgeslagen in de feed; door dat wachten komen wijzigingen die vlak na elkaar zijn opgeslagen op volgorde binnen. Een wijziging van een order die intussen verwijderd is, wordt overgeslagen.

Elke minuut of twee pollen blijft ruim binnen de rate limit.