Developers
API referenceBusiness sign in

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.

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"]
Search parameters
ParameterDefaultMeaning
lat, lngrequiredWhere to search around (the buyer's address or shared location)
radius5000Metres, 100–50 000
purposePICKUPPICKUP (the buyer collects) or DROPOFF (you hand parcels in)
productnoneRELAY_POINT, RELAY_LOCKER or RELAY_HOME (fallback point). A parcel over the product's limits answers 422
sizenoneSMALL (2 kg, 35 × 25 × 10 cm), MEDIUM (10 kg, 45 × 35 × 25 cm) or LARGE (20 kg, 60 × 45 × 40 cm)
weightGrams, lengthMm, widthMm, heightMmnoneThe exact parcel; overrides size. Give all three sides or none
limit101–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.

Exclusion reasons
Excluded reasonMeaning
TEMPORARILY_UNAVAILABLESuspended by Qoene
NO_PICKUP_SERVICE, NO_DROPOFF_SERVICEThe point does not offer this direction
NOT_ACCEPTING_PARCELS, NOT_ACCEPTING_DROPOFFSPaused by the point
TEMPORARILY_CLOSED, NOT_OPEN_THIS_WEEKClosed today, or no opening in the next 7 days
OVER_WEIGHT_LIMIT, OVER_SIZE_LIMIT, NO_FITTING_COMPARTMENTThe parcel does not fit
NO_SPACEThe point is full
OUTSIDE_RELAY_NETWORKNo 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.

In your checkout page (browser)
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_POINT with the point code (or POINT_TO_LOCKER for a live locker).
  • The selection is discovery only: re-check it in a fresh quote from your server.
  • http://localhost origins 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.