Orders doorsturen vanuit je ERP of webshop

Stuur elke nieuwe order naar Picked zodra je systeem hem accepteert. Picked houdt de voorraad er meteen voor vast en zet de order klaar voor het magazijn.

Wanneer gebruik je dit

Gebruik dit recept als je webshop of ERP niet bij de ingebouwde koppelingen staat, of als je eigen systeem bepaalt welke orders naar het magazijn gaan.

Je hebt nodig:

een token met het recht orders:write, en orders:read om de order te volgen (zie Authenticatie en rechten);
het id van het magazijn dat de order verstuurt: GET /api/v1/warehouses geeft je magazijnen met hun warehouse_id (zie Aan de slag).

Stuur de order

POST /api/v1/orders neemt één order aan. external_id is je eigen ordernummer. Elke regel noemt het product met product_external_ref, het id dat je eigen systeem het artikel geeft, plus de SKU en barcode als je die hebt. product_external_ref wordt vergeleken met de Externe referentie van de producten die je in Picked beheert. Een product dat een gekoppeld ERP of een gekoppelde webshop heeft geïmporteerd, draagt het id van dat systeem als referentie en wordt daarom op SKU of barcode gevonden: stuur die mee als je ze hebt.

curl -X POST "https://picked.nl/api/v1/orders" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "warehouse_id": 12,
    "external_id": "WS-2026-104233",
    "customer_name": "Sanne de Vries",
    "shipping_method": "postnl-standaard",
    "ordered_at": "2026-10-13T21:47:00+02:00",
    "sla_due_at": "2026-10-14T17:00:00+02:00",
    "lines": [
      { "product_external_ref": "art-10021", "product_sku": "BEL-ZW-01", "quantity_ordered": 2 },
      { "product_external_ref": "art-55102", "product_sku": "BIDON-750", "quantity_ordered": 1 }
    ]
  }'

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/orders/48211

{
  "id": 48211,
  "external_id": "WS-2026-104233",
  "status": "pending",
  "shipped_short": false,
  "warehouse_id": 12,
  "line_count": 2,
  "provisioned_products": [
    { "external_ref": "art-55102", "product_id": 9135, "sku": "BIDON-750" }
  ],
  "_links": {
    "order": { "href": "/api/v1/orders/48211" }
  }
}

Een order heeft 1 tot 500 regels. De API-referentie noemt alle optionele velden: customer_ref, notes, priority, currency, en per regel unit_price_cents, dat nodig is voor een zending over een douanegrens.

Veilig opnieuw proberen

Picked herkent een order aan zijn external_id. Geeft een aanroep een time-out, stuur dan precies hetzelfde verzoek nog een keer. Heeft de eerste aanroep de order toch gemaakt, dan krijg je hem terug met 200 OK in plaats van een tweede order. Bewaar in beide gevallen het id uit het antwoord dat je krijgt. Idempotentie legt het precies uit.

Wat er daarna in het magazijn gebeurt

De order verschijnt in Picked onder Orders, met de status pending.
Picked houdt meteen de voorraad vast die er voor de order is, dus die stuks tellen niet meer mee in het sellable-cijfer dat je voorraadsynchronisatie leest. Een order voor meer dan er op voorraad is, wordt toch aangenomen.
Een product dat Picked nog niet kent, houdt de order niet tegen. Picked maakt er een voorlopig product voor aan en noemt het onder provisioned_products. Je managers vinden het bij de producten die op controle wachten (/wms/products/provisional), zodat iemand het kan aanvullen.
Daarna volgt de order de werkvloer: pending → assigned → picking → picked → packing → packed → shipped. Een order die de klant ophaalt, gaat via ready_for_pickup naar shipped. Tot shipped kan een order altijd cancelled worden, behalve zolang hij ready_for_pickup is.
Twee stappen gaan terug:
- Stopt de pickronde die aan een order werkt voor het einde, dan gaat de order van picking terug naar pending om opnieuw te worden ingepland. Wat al gepickt is, blijft staan (picked_quantity); alleen de rest wordt in de volgende ronde gepickt.
- Corrigeert een inpakker een inpakfout, dan gaat een packed order terug naar packing en wordt hij opnieuw ingepakt.

Volg de order tot hij verzonden is

Lees de order terug met GET /api/v1/orders/{id}, het id uit het antwoord op de import: de Location-header en _links.order wijzen ernaar. Daarvoor heb je een token met het recht orders:read nodig. Direct na de import is hij nog pending, en is er nog niets geteld:

curl "https://picked.nl/api/v1/orders/48211" \
  -H "Authorization: Bearer $PICKED_TOKEN" \
  -H "Accept: application/json"

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

{
  "id": 48211,
  "external_id": "WS-2026-104233",
  "status": "pending",
  "shipped_short": false,
  "fulfilment_method": "carrier",
  "warehouse_id": 12,
  "lines": [
    { "sku": "BEL-ZW-01", "quantity": 2, "picked_quantity": null, "shipped_quantity": null, "closed_short_quantity": 0 },
    { "sku": "BIDON-750", "quantity": 1, "picked_quantity": null, "shipped_quantity": null, "closed_short_quantity": 0 }
  ],
  "shipments": [],
  "created_at": "2026-10-12T09:14:03+02:00",
  "updated_at": "2026-10-12T09:14:03+02:00",
  "_links": {
    "self": { "href": "/api/v1/orders/48211" }
  }
}

Een zending verschijnt in shipments zodra het magazijn hem aanmaakt; zijn tracking_number en tracking_url blijven null tot het label gekocht is, en bij een vervoerder waar Picked niet aan gekoppeld is. Daarna opent tracking_url de trackingpagina van de vervoerder, en noemt een zending die in meerdere pakketten de deur uitging elk pakket met zijn eigen tracking onder parcels. Die URL is null voor een vervoerder die geen trackinglink publiceert, en voor een zending via een aggregator. PostNL en DPD vragen op hun pagina om de postcode, omdat de API het adres van de ontvanger nooit deelt. Is de order de deur uit, dan ziet het er zo uit:

"status": "shipped",
"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": []
  }
]

Per regel rekenen shipped_quantity en closed_short_quantity een korte levering af: wat nog openstaat is quantity min die twee. picked_quantity en shipped_quantity blijven null zolang het magazijn voor de order niets telt: voordat het picken begint, en in een werkwijze die verzendt zonder te tellen. Null betekent niet geteld, nooit geen. De naam en het adres van de klant staan nooit in het antwoord. Wil je de wijzigingen van al je orders horen zonder ze een voor een te lezen, poll dan de feed met orderwijzigingen.

Of laat Picked het pushen

Abonneer in plaats van te pollen een URL op order.shipped in Instellingen → Ontwikkelaars → Webhooks: Picked POST de order, met trackingnummer, zodra hij het pand verlaat. Houd de poll als nachtelijk vangnet. Zie Webhooks ontvangen.

Fouten afhandelen

Status	Wat je doet
`422` `validation_failed`	Verbeter het verzoek: `errors` noemt elk veld, zoals een onbekend `warehouse_id` of een regel zonder `quantity_ordered`. Opnieuw sturen helpt niet.
`403` `missing_ability`	Het token mist het recht `orders:write`, of `orders:read` om de order terug te lezen.
`404` `not_found`	Bij teruglezen: geen order van jou heeft dat `id`. Gebruik het `id` uit het antwoord op de import, niet je `external_id`.
`503` of een andere `5xx`	Stuur hetzelfde verzoek na een pauze opnieuw. Door de `external_id` ontstaat er geen tweede order.

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

Probeer het met een proefrun

Zet de header Picked-Dry-Run: true op hetzelfde verzoek om de order te controleren tegen je echte producten en magazijnen, zonder iets te schrijven. Het antwoord is 200 met would: created, of already_exists voor een external_id die Picked al kent. Proefruns loopt een ordervoorbeeld helemaal door.