Developers
API referenceBusiness sign in

Checkout

Start a checkout session for the widget

POST/checkout/sessions

Scope checkout.writeIdempotency-Key required

Call from your server when the buyer reaches checkout. The session fixes the parcel, the origin (drop-off point for Relay, pickup address for Express), the products you offer and the payment terms, so the buyer's browser cannot change what is priced. Pass clientSecret to QoeneCheckout.mount() / open() with your publishable key. A session lasts 30 minutes by default (5–120). Retrying with the same Idempotency-Key returns the same session and secret.

Request

Headers

Request headers
NameInTypeDescription
AuthorizationRequiredheaderstringBearer <API key>
Idempotency-KeyRequiredheaderstring8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409. See Idempotency.Pattern ^[A-Za-z0-9._:-]{8,160}$

Body CheckoutSessionRequest

Request body
FieldTypeDescription
parcelRequiredobjectThe parcel as packed.
actualWeightGramsRequiredinteger1 to 100000
lengthMmRequiredinteger1 to 5000
widthMmRequiredinteger1 to 5000
heightMmRequiredinteger1 to 5000
originRequiredobjectWhere the parcel starts: a drop-off point for Relay and/or a pickup address for Express.
pointCodeOptionalstringYour drop-off Qoene Point (Relay products).
addressOptionalobjectAddress text, a place, or coordinates.
textOptionalstring3–300 characters
latitudeOptionalnumber
longitudeOptionalnumber
placeIdOptionalstringFrom GET /checkout/places.
serviceCodesOptionalarray of ServiceCodeProducts to offer (default: all five). Products you cannot use are still shown as unavailable.
payOnPickupOptionalbooleanPrice the Relay offers for payment when the receiver collects (default false).
orderReferenceOptionalstringYour order reference; booked with the selection unless the booking sends its own.Pattern ^[A-Za-z0-9][A-Za-z0-9._:/ -]{2,99}$
expiresInMinutesOptionalintegerSession lifetime (default 30).5 to 120
requestedPickupAtOptionalstring (date-time)Planned pickup or drop-off time; the promise counts from it.
prefillOptionalobjectShown in the widget's address field.
addressTextOptionalstring0–300 characters

Response

Success responses
StatusMeaning
200Replay
201Created

The body is { "status": "success", "data": … }. Fields of data (CheckoutSessionResult):

Response data
FieldTypeDescription
sessionRequiredCheckoutSession
replayedRequiredboolean

Errors

Errors use the error envelope { "status": "error", "message", "code"?, "details"? }.

Error responses
StatusWhen
400The request is not valid. A field is missing or invalid, or the Idempotency-Key header is missing or malformed.
401Missing, invalid, expired or revoked API key. The API key is missing, invalid, expired or revoked.
403The key lacks the scope, or the operation needs a LIVE key. The key lacks the scope, or this call needs a LIVE key (LIVE_KEY_REQUIRED), or the Business owner is not verified (SENDER_VERIFICATION_REQUIRED).
409Idempotency key reused with another body, or the resource changed state. The idempotency key was used with a different body, a reference is already taken, or the resource changed state.
422Eligibility or business rule refused the request; details.reason explains why. A business rule refused the request. details.reason.code says why (for example OVER_PRODUCT_WEIGHT_LIMIT or a point exclusion reason).
429Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key.