Guides
Picking a Qoene Point
Relay buyers collect their parcel at a Qoene Point. Offer the best points near them, not just the nearest, and pass the chosen point's code to your quote.
Ranked search from your server
GET /locations/search ranks points by distance, opening state, spare space, Relay reach and operations, and lists nearby points that cannot be used with the reason.
const { results, excluded } = await qoene.locations.search({
lat: buyer.lat, lng: buyer.lng, radius: 5000,
purpose: 'PICKUP', product: 'RELAY_POINT', size: 'SMALL', limit: 5,
});
for (const point of results) {
console.log(point.public_code, point.name, point.open.label, point.space.label, Math.round(point.distanceMeters), 'm');
}curl -G https://api.qoenedelivery.com/v1/locations/search \
-H "Authorization: Bearer $QOENE_API_KEY" \
--data-urlencode "lat=5.6502" --data-urlencode "lng=-0.1869" --data-urlencode "radius=5000" \
--data-urlencode "purpose=PICKUP" --data-urlencode "product=RELAY_POINT" --data-urlencode "size=SMALL" --data-urlencode "limit=5"$response = $client->get('locations/search', ['query' => [
'lat' => $buyer['lat'], 'lng' => $buyer['lng'], 'radius' => 5000,
'purpose' => 'PICKUP', 'product' => 'RELAY_POINT', 'size' => 'SMALL', 'limit' => 5,
]]);
$results = json_decode((string) $response->getBody(), true)['data']['results'];response = requests.get(
"https://api.qoenedelivery.com/v1/locations/search",
headers=headers,
params={"lat": buyer["lat"], "lng": buyer["lng"], "radius": 5000,
"purpose": "PICKUP", "product": "RELAY_POINT", "size": "SMALL", "limit": 5},
timeout=30,
)
results = response.json()["data"]["results"]| Parameter | Default | Meaning |
|---|---|---|
lat, lng | required | Where to search around (the buyer's address or shared location) |
radius | 5000 | Metres, 100–50 000 |
purpose | PICKUP | PICKUP (the buyer collects) or DROPOFF (you hand parcels in) |
product | none | RELAY_POINT, RELAY_LOCKER or RELAY_HOME (fallback point). A parcel over the product's limits answers 422 |
size | none | SMALL (2 kg, 35 × 25 × 10 cm), MEDIUM (10 kg, 45 × 35 × 25 cm) or LARGE (20 kg, 60 × 45 × 40 cm) |
weightGrams, lengthMm, widthMm, heightMm | none | The exact parcel; overrides size. Give all three sides or none |
limit | 10 | 1–50 results |
Show each point's name, address, open.label (for example "Open until 18:00") and space.label. Space is a level, never a count. Store the public_code: it is the stable value for destinationLocationCode.
| Excluded reason | Meaning |
|---|---|
TEMPORARILY_UNAVAILABLE | Suspended by Qoene |
NO_PICKUP_SERVICE, NO_DROPOFF_SERVICE | The point does not offer this direction |
NOT_ACCEPTING_PARCELS, NOT_ACCEPTING_DROPOFFS | Paused by the point |
TEMPORARILY_CLOSED, NOT_OPEN_THIS_WEEK | Closed today, or no opening in the next 7 days |
OVER_WEIGHT_LIMIT, OVER_SIZE_LIMIT, NO_FITTING_COMPARTMENT | The parcel does not fit |
NO_SPACE | The point is full |
OUTSIDE_RELAY_NETWORK | No Relay route reaches it yet |
Hosted selector (available now)
If you would rather not build a point picker, open Qoene's hosted selector in a popup from a buyer's click. It needs no API key and returns the buyer's choice to your page.
const qoeneOrigin = 'https://qoenedelivery.com';
const requestId = crypto.randomUUID();
const url = new URL('/checkout-selector', qoeneOrigin);
url.searchParams.set('merchantOrigin', location.origin); // your exact https origin
url.searchParams.set('requestId', requestId);
const popup = window.open(url, '_blank', 'width=900,height=760'); // from a click
function receiveSelection(event) {
if (event.origin !== qoeneOrigin || event.source !== popup) return;
const message = event.data;
if (message?.type !== 'qoene.delivery.selection' || message.version !== 1 || message.requestId !== requestId) return;
window.removeEventListener('message', receiveSelection);
// { service, serviceVariant, destinationLocationCode }: send it to YOUR server,
// which quotes and books with the API key.
saveDeliveryChoice(message.selection);
}
window.addEventListener('message', receiveSelection);- Express returns
serviceVariant: "STANDARD"and no location code: collect the delivery address yourself. - Relay returns
POINT_TO_POINTwith the point code (orPOINT_TO_LOCKERfor a live locker). - The selection is discovery only: re-check it in a fresh quote from your server.
http://localhostorigins are allowed while you develop.
Embedded widget
The checkout widget from js.qoenedelivery.com shows the ranked points (list and map), the five products with your prices and promised dates, and returns a signed selection your server books with. It works inline or as a popup, and replaces the hosted selector for most shops.