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
| Name | In | Type | Description |
|---|---|---|---|
AuthorizationRequired | header | string | Bearer <API key> |
Idempotency-KeyRequired | header | string | 8–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
| Field | Type | Description |
|---|---|---|
parcelRequired | object | The parcel as packed. |
actualWeightGramsRequired | integer | 1 to 100000 |
lengthMmRequired | integer | 1 to 5000 |
widthMmRequired | integer | 1 to 5000 |
heightMmRequired | integer | 1 to 5000 |
originRequired | object | Where the parcel starts: a drop-off point for Relay and/or a pickup address for Express. |
pointCodeOptional | string | Your drop-off Qoene Point (Relay products). |
addressOptional | object | Address text, a place, or coordinates. |
textOptional | string | 3–300 characters |
latitudeOptional | number | |
longitudeOptional | number | |
placeIdOptional | string | From GET /checkout/places. |
serviceCodesOptional | array of ServiceCode | Products to offer (default: all five). Products you cannot use are still shown as unavailable. |
payOnPickupOptional | boolean | Price the Relay offers for payment when the receiver collects (default false). |
orderReferenceOptional | string | Your order reference; booked with the selection unless the booking sends its own.Pattern ^[A-Za-z0-9][A-Za-z0-9._:/ -]{2,99}$ |
expiresInMinutesOptional | integer | Session lifetime (default 30).5 to 120 |
requestedPickupAtOptional | string (date-time) | Planned pickup or drop-off time; the promise counts from it. |
prefillOptional | object | Shown in the widget's address field. |
addressTextOptional | string | 0–300 characters |
Response
| Status | Meaning |
|---|---|
200 | Replay |
201 | Created |
The body is { "status": "success", "data": … }. Fields of data (CheckoutSessionResult):
| Field | Type | Description |
|---|---|---|
sessionRequired | CheckoutSession | |
replayedRequired | boolean |
Errors
Errors use the error envelope { "status": "error", "message", "code"?, "details"? }.
| Status | When |
|---|---|
400 | The request is not valid. A field is missing or invalid, or the Idempotency-Key header is missing or malformed. |
401 | Missing, invalid, expired or revoked API key. The API key is missing, invalid, expired or revoked. |
403 | The 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). |
409 | Idempotency 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. |
422 | Eligibility 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). |
429 | Too many requests. See the RateLimit headers. Too many requests. Wait for Retry-After, then retry with the same idempotency key. |