Developers
API referenceBusiness sign in

Orders

Add a store order to the inbox

POST/orders

Scope orders.write

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

Request body
FieldTypeDescription
storeIdRequiredstringStore public ID (QD-STR-…). The store must be bound to this key's API client.
checkoutSelectionOptionalstringNB16: 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
externalOrderIdRequiredstringYour order number; unique per store, case-insensitive.Pattern ^#?[A-Za-z0-9][A-Za-z0-9._:/ -]{0,63}$
receiverRequiredContact
buyerOptionalContact
serviceCodeRequiredServiceCodeStable product code (NB02).
destinationPointCodeOptionalstringRelay Point / Relay Locker: the buyer's chosen point code.
destinationAddressOptionalobjectExpress and Relay Home: delivery address.
textRequiredstring5–300 characters
placeIdOptionalstring
itemsOptionalarray of OrderItem0–100 items
descriptionOptionalstring3–500 characters
parcelOptionalMeasurements
orderTotalMinorOptionalintegerOrder value in pesewas (information only).0 to ∞
currencyOptional"GHS"
storePaymentStateOptionalenumOne of PAID, PENDING, CASH_ON_DELIVERY, REFUNDED, UNKNOWN
placedAtOptionalstring (date-time)

Response

Success responses
StatusMeaning
200Already in the inbox
201Created

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

Response data
FieldTypeDescription
orderRequiredOrder
replayedRequiredbooleanTrue when this store already had the same order.
environmentOptionalEnvironmentThe key environment. TEST never touches live custody, payments, dispatch or notifications.

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).
404Not 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.
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.