Orders
Add a store order to the inbox
POST/orders
Idempotent by store and external order ID: resending the same order returns it (200, replayed: true); different details return 409 COMMERCE_ORDER_CONFLICT. No Idempotency-Key is needed. The store must be bound to this key's API client. Orders created with a TEST key stay in the inbox and are never shipped. Orders in a WooCommerce store are recorded with source WOOCOMMERCE. Send checkoutSelection (NB16) to attach the shopper's signed widget choice: CHECKOUT_SELECTION_MISMATCH (400) when a field disagrees with it, CHECKOUT_SELECTION_USED (409) when it is used or attached to another order, CHECKOUT_SELECTION_EXPIRED (422) for a new order with an expired token (a resend of the same order still replays).
Request
Body OrderCreateRequest
| Field | Type | Description |
|---|---|---|
storeIdRequired | string | Store public ID (QD-STR-…). The store must be bound to this key's API client. |
checkoutSelectionOptional | string | NB16: the signed selection token from the checkout widget. Verified for this Business and environment and attached to the order once; it fixes the product, the pickup point and the parcel (fields you also send must match). The ship run books its quote, at the price the shopper saw, while it is still valid, and quotes afresh after that.0–8000 characters |
externalOrderIdRequired | string | Your order number; unique per store, case-insensitive.Pattern ^#?[A-Za-z0-9][A-Za-z0-9._:/ -]{0,63}$ |
receiverRequired | Contact | |
buyerOptional | Contact | |
serviceCodeRequired | ServiceCode | Stable product code (NB02). |
destinationPointCodeOptional | string | Relay Point / Relay Locker: the buyer's chosen point code. |
destinationAddressOptional | object | Express and Relay Home: delivery address. |
textRequired | string | 5–300 characters |
placeIdOptional | string | |
itemsOptional | array of OrderItem | 0–100 items |
descriptionOptional | string | 3–500 characters |
parcelOptional | Measurements | |
orderTotalMinorOptional | integer | Order value in pesewas (information only).0 to ∞ |
currencyOptional | "GHS" | |
storePaymentStateOptional | enum | One of PAID, PENDING, CASH_ON_DELIVERY, REFUNDED, UNKNOWN |
placedAtOptional | string (date-time) |
Response
| Status | Meaning |
|---|---|
200 | Already in the inbox |
201 | Created |
The body is { "status": "success", "data": … }. Fields of data (OrderCreateResult):
| Field | Type | Description |
|---|---|---|
orderRequired | Order | |
replayedRequired | boolean | True when this store already had the same order. |
environmentOptional | Environment | The key environment. TEST never touches live custody, payments, dispatch or notifications. |
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). |
404 | Not found for this Business and environment. IDs from another Business or environment are always 404. Not found for this Business and environment. IDs from another Business or the other environment are always 404. |
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. |