The flow
1
Search points near the shopper
GET /pickup-points with the shopper’s country and postal code, or with
coordinates. You get the closest points, ordered by distance.2
Let the shopper pick one
Render the list at checkout. Keep the
pudoId of the point they choose.3
Create the order with that point
POST /orders with the same pudoId, alongside the shopper’s own delivery
address as usual.Search for points
countryCode + postalCode, or by lat + lng. Everything else is
optional: city, street, state, maxResults, maxDistanceKm, and types.
totalFound counts the points near that address; when it exceeds the number of
points returned, maxResults truncated the list.
Which id do I send?
AlwayspudoId — it goes straight through to the order field of the same
name, unchanged. Treat it as an opaque string: store it as-is and don’t parse or
derive anything from its shape, which can change.
carrierPudoId is the delivering carrier’s own identifier for that same
physical point (a DHL or PostNL location code, say). It is informational: send
it as the order’s pudoId and the order will not route. It’s there for one job —
matching. If your webshop plugin already let the shopper pick a point and stored
the carrier’s id, search this endpoint for that address, find the point whose
carrierPudoId matches, and order with its pudoId. Match within one carrier:
these ids are unique per carrier, not across them.
Filtering by kind
types narrows the search. Repeat the parameter for several kinds, or leave it
off to search all of them:
type a point comes back with:
Create the order
SetpudoId on the order. The delivery address stays the shopper’s own
address — the pickup point is identified by its id, not by using its address
as the destination.
What makes a point available
Two separate things decide whether pickup point delivery works, and they can disagree — always handle the rejection below rather than assuming a searchable point is an orderable one.1
The search reflects the pickup point network
GET /pickup-points returns whatever points exist near the address you
searched. It is not scoped to your account, your location, or your delivery
areas — the same address returns the same points for everyone.2
Creating the order depends on your delivery areas
An order with a
pudoId is only accepted when the delivery address falls in
a delivery area that both is served by our pickup point carrier and has the
pickup point capability enabled. That capability is set per delivery
area, so pickup point delivery is effectively switched on per location — the
locations linked to those areas. You can see which capabilities an area has
on the location’s page in the dashboard, under its delivery areas.pickupPoint: true to
POST /orders/check/{locationId} — it answers the same
question the create call would, and reports missingCapabilities.pickupPoint
when the address can’t be served.
An order that names a pickup point is never quietly delivered to the door
instead: a locker id means nothing to another carrier, so we reject the order
rather than fall back.
Empty results
An emptypoints list is a normal answer, not an error. It means one of:
- there are no pickup points near that address,
- the country isn’t covered by the pickup point network,
- the search radius (
maxDistanceKm) ortypesfilter excluded everything, - the lookup itself failed — we return an empty list rather than an error so checkout keeps working.