{"openapi":"3.1.0","info":{"title":"Qoene Delivery API","version":"1.0.0","summary":"Quote, book, track and label Qoene Express and Qoene Relay parcels; manage store orders and webhooks.","description":"Merchant API v1 for Qoene Delivery (Ghana). Authenticate every request with `Authorization: Bearer <key>`. Keys are `qd_test_…` (simulated: no live custody, payments, dispatch or notifications) or `qd_live_…`, each with explicit scopes (`x-qoene-scopes` on each operation). Never put a key in browser or mobile code.\n\nThe checkout widget (NB15, `js.qoenedelivery.com`) runs in the buyer's browser with a **publishable key** (`qd_pk_…`) locked to your website's origins, and a checkout session your server creates. Its browser-only operations carry `x-qoene-browser: true` and are not part of the server SDK.\n\nResponses are `{ \"status\": \"success\", \"data\": … }`; errors are `{ \"status\": \"error\", \"message\", \"code\"?, \"details\"? }`. Money is integer pesewas. IDs from another Business or environment return 404.\n\nWrites that create things take an `Idempotency-Key` header: a retry with the same key and body returns the original result; another body returns 409. Orders are idempotent by store and external order ID instead.\n\nList endpoints page with an opaque `cursor` and return `nextCursor` (null on the last page).\n\nClaims (`/claims`, `claim.*` events) cover loss, damage, missing items, delays and wrong deliveries on LIVE parcels.\n\nReturns (`/returns`, `return.*` events): start, approve, reject and follow e-commerce returns. Customers drop returns off with a paperless code; Qoene reports `return.received` and `return.inspected`, and you refund from your own system.","contact":{"name":"Qoene Delivery developers","url":"https://developers.qoenedelivery.com"}},"servers":[{"url":"https://api.qoenedelivery.com/v1","description":"Production (TEST and LIVE keys use the same host)"},{"url":"https://api-staging.qoenedelivery.com/v1","description":"Staging"},{"url":"{origin}/api/v1","description":"Any Qoene API origin (the original path keeps working)","variables":{"origin":{"default":"https://qoenelogistics.com"}}}],"security":[{"ApiKey":[]}],"tags":[{"name":"Markets"},{"name":"Services"},{"name":"Locations"},{"name":"Quotes"},{"name":"Checkout"},{"name":"Shipments"},{"name":"Tracking"},{"name":"Payments"},{"name":"Labels"},{"name":"Manifests"},{"name":"Orders"},{"name":"Claims"},{"name":"Returns"},{"name":"Analytics"},{"name":"Webhooks"},{"name":"Meta"}],"paths":{"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"This OpenAPI document","tags":["Meta"],"description":"This OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/markets":{"get":{"operationId":"listMarkets","summary":"Live markets","tags":["Markets"],"description":"Public, no key needed. Each live market with its currency (amounts are integers in its minor unit), time zone, phone format, identity documents, address fields and the products sold there. Ghana (GH) is the only live market; every market is a separate domestic network and parcels never cross markets.","security":[],"responses":{"200":{"description":"Live markets","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/MarketList"}},"required":["status","data"]},"example":{"status":"success","data":{"markets":[{"code":"GH","name":"Ghana","status":"LIVE","timezone":"Africa/Accra","currency":{"code":"GHS","minorUnit":2,"symbol":"GH₵"},"locales":["en-GH"],"defaultLocale":"en-GH","phone":{"countryCode":"233","nationalLength":9,"trunkPrefix":"0","example":"024 123 4567"},"identityDocuments":[{"type":"GHANA_CARD","name":"Ghana Card"}],"address":{"fields":["line1","area","city","region"],"postcode":{"name":"Ghana Post GPS","required":false}},"support":{"email":"support@qoenedelivery.com","phone":null,"whatsapp":null,"hours":"Mon–Sat 08:00–18:00"},"products":["EXPRESS_STANDARD","EXPRESS_PRIORITY","RELAY_POINT","RELAY_LOCKER","RELAY_HOME"]}]}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/services":{"get":{"operationId":"listServices","summary":"Products this Business can use","tags":["Services"],"description":"The NB02 product catalog, filtered by the Business's contract in force (NB10): each usable product with its parcel limits and promise rule (including the promise if booked now). Products that are switched off or outside the contract are listed in `unavailable` with a reason.\n\nScope: `services.read`.","x-qoene-scopes":["services.read"],"x-qoene-live-only":false,"responses":{"200":{"description":"Usable and unavailable products","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ServicesResult"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/locations":{"get":{"operationId":"listLocations","summary":"Active points (and live lockers)","tags":["Locations"],"description":"Up to 200 active staffed points; lockers only once real locker hardware is live. Prefer the ranked search for checkout.\n\nScope: `locations.read`.","x-qoene-scopes":["locations.read"],"x-qoene-live-only":false,"responses":{"200":{"description":"Locations","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/LocationList"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/locations/search":{"get":{"operationId":"searchLocations","summary":"Ranked point search near a position","tags":["Locations"],"description":"Points ranked by distance, opening state, spare space, Relay reach and operations (NB08), with exclusion reasons. Ranking is advice, not a reservation; quotes and bookings re-check the chosen point.\n\nScope: `locations.read`.","x-qoene-scopes":["locations.read"],"x-qoene-live-only":false,"parameters":[{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude (required unless address is sent; alias latitude)."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Longitude (required unless address is sent; alias longitude)."},{"name":"address","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":300},"description":"NB16: search around this address instead of lat/lng (geocoded by Qoene; 422 ADDRESS_NOT_FOUND when it cannot be found)."},{"name":"radius","in":"query","required":false,"schema":{"type":"integer","minimum":100,"maximum":50000,"default":5000},"description":"Metres."},{"name":"purpose","in":"query","required":false,"schema":{"type":"string","enum":["PICKUP","DROPOFF"]},"description":"PICKUP (receiver collects, default) or DROPOFF."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["POINT","LOCKER","ALL"]},"description":"Default POINT."},{"name":"product","in":"query","required":false,"schema":{"type":"string","enum":["RELAY_POINT","RELAY_LOCKER","RELAY_HOME"]},"description":"Sets the type; PICKUP only."},{"name":"size","in":"query","required":false,"schema":{"type":"string","enum":["SMALL","MEDIUM","LARGE"]},"description":"Parcel size preset."},{"name":"weightGrams","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Exact parcel weight."},{"name":"lengthMm","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Give all three sides or none."},{"name":"widthMm","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Give all three sides or none."},{"name":"heightMm","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Give all three sides or none."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Ranked results."}],"responses":{"200":{"description":"Ranked and excluded points","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/PointSearch"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/locations/{code}":{"get":{"operationId":"getLocation","summary":"One point or locker","tags":["Locations"],"description":"Public projection of one active point or live locker: opening state, space level, what it accepts, size limits, Relay coverage and closures in the next 30 days. Hubs and inactive points return 404.\n\nScope: `locations.read`.","x-qoene-scopes":["locations.read"],"x-qoene-live-only":false,"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9-]{4,40}$"},"description":"Location public code."}],"responses":{"200":{"description":"The location","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/LocationDetailResult"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/quotes":{"post":{"operationId":"createQuote","summary":"Quote one product","tags":["Quotes"],"description":"Prices one product for a parcel and route with the published tariff (and your contract, if any). The quote is frozen until `expires_at`; book it with its `public_id`. TEST keys get the same price as LIVE.\n\nScope: `quotes.write`.","x-qoene-scopes":["quotes.write"],"x-qoene-live-only":false,"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,160}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"},"example":{"service":"RELAY","serviceVariant":"POINT_TO_POINT","measurements":{"actualWeightGrams":1200,"lengthMm":300,"widthMm":200,"heightMm":120},"originLocationCode":"QD-DO-5B1E9C3A7F2D04E8B6A1C9F3","destinationLocationCode":"QD-PU-1D7F3B9E5A2C08F4B6E1A9D3","payOnPickup":true}}}},"responses":{"200":{"description":"Replay of the original quote","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/QuoteResult"}},"required":["status","data"]}}}},"201":{"description":"Quote created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/QuoteResult"}},"required":["status","data"]},"example":{"status":"success","data":{"quote":{"public_id":"QD-QT-3C9E1A7F52B04D86E1F9A2C7","service":"RELAY","service_variant":"POINT_TO_POINT","service_code":"RELAY_POINT","currency":"GHS","subtotal_minor":2500,"tax_minor":0,"total_minor":2500,"expires_at":"2026-10-27T10:45:00.000Z","price":{"components":[{"code":"base","label":"Relay point to point","amountMinor":2500}],"taxComponents":[]},"promise":{"rule":"WORKING_DAYS","cutoffLocalTime":"16:00","beforeCutoff":true,"promisedBy":"2026-10-29T23:59:59.000Z","label":"Within 2 working days","timezone":"Africa/Accra","engineVersion":"NB19-1","market":"GH","promisedDate":"2026-10-29","dateLabel":"Thu 29 Oct","summary":"Ready to collect by Thu 29 Oct","window":{"start":"2026-10-29T07:00:00.000Z","end":"2026-10-29T20:00:00.000Z"},"startDate":"2026-10-27","cutoffSource":"PRODUCT","transitWorkingDays":2,"lane":{"origin":"QD-ZN-ACCRA","destination":"QD-ZN-ACCRA","transitWorkingDays":2,"source":"PRODUCT_DEFAULT"},"checkpoints":[{"code":"FIRST_SCAN","milestone":"DROPPED_OFF","dueBy":"2026-10-27T16:00:00.000Z","label":"Dropped off","reasonIfMissed":"MISSED_FIRST_SCAN"},{"code":"FINAL","milestone":"READY_FOR_PICKUP","dueBy":"2026-10-29T23:59:59.000Z","label":"Ready to collect","reasonIfMissed":"NOT_READY_FOR_COLLECTION"}],"ruleVersion":{"id":"7a04f113-af7c-4bc0-8654-90afc6755b9d","publicId":"QD-PRV-F8DD660063B0AC0087149E33","versionNumber":1}}},"replayed":false,"environment":"TEST","simulated":true}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/quotes/options":{"post":{"operationId":"createQuoteOptions","summary":"Quote every eligible product","tags":["Quotes"],"description":"Every eligible product with its price, plus why each other product is excluded (NB02).\n\nScope: `quotes.write`.","x-qoene-scopes":["quotes.write"],"x-qoene-live-only":false,"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–120 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,120}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteOptionsRequest"},"example":{"measurements":{"actualWeightGrams":1200,"lengthMm":300,"widthMm":200,"heightMm":120},"originLocationCode":"QD-DO-5B1E9C3A7F2D04E8B6A1C9F3","destinationLocationCode":"QD-PU-1D7F3B9E5A2C08F4B6E1A9D3","payOnPickup":true}}}},"responses":{"200":{"description":"Replay","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/QuoteOptionsResult"}},"required":["status","data"]}}}},"201":{"description":"Offers","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/QuoteOptionsResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shipments":{"get":{"operationId":"listShipments","summary":"List shipments","tags":["Shipments"],"description":"The Business's shipments in the key's environment, newest first. TEST keys list simulated parcels only. Pass `nextCursor` back as `cursor` for the next page.\n\nScope: `shipments.read`.","x-qoene-scopes":["shipments.read"],"x-qoene-live-only":false,"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"Internal status, or several separated by commas."},{"name":"milestone","in":"query","required":false,"schema":{"type":"string"},"description":"Current milestone code, for example READY_FOR_PICKUP."},{"name":"serviceCode","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ServiceCode"},"description":"Product (alias `product`)."},{"name":"storeId","in":"query","required":false,"schema":{"type":"string","description":"Store ID","pattern":"^(?:QD-STR-[A-F0-9]{24}|QDSTR[A-Z0-9]{3,31})$","example":"QD-STR-0123456789ABCDEF01234567"},"description":"Shipments created for this store's orders."},{"name":"orderReference","in":"query","required":false,"schema":{"type":"string","maxLength":100},"description":"Exact Business order reference (case-insensitive)."},{"name":"createdFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created at or after."},{"name":"createdTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Created before."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from nextCursor."}],"responses":{"200":{"description":"A page of shipments","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ShipmentList"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createShipment","summary":"Book a shipment from a quote","tags":["Shipments"],"description":"TEST simulates; LIVE books. A LIVE booking needs a verified Business owner (NB04). BUSINESS_WALLET needs `wallet.spend` too. No API call silently starts a gateway charge. A checkout selection attached to a LIVE order (NB16) is refused with 409 CHECKOUT_SELECTION_ATTACHED: ship that order instead.\n\nScope: `shipments.write`.","x-qoene-scopes":["shipments.write"],"x-qoene-live-only":false,"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,160}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingRequest"},"example":{"quoteId":"QD-QT-3C9E1A7F52B04D86E1F9A2C7","description":"Two cotton shirts, boxed","sender":{"name":"Adwoa Styles","phone":"0241234567"},"receiver":{"name":"Kwame Mensah","phone":"0247654321"},"paymentMode":"PAY_ON_PICKUP","orderReference":"SHOP-1001","prohibitedItemsDeclaration":{"accepted":true,"version":"2026-10-v1"}}}}},"responses":{"200":{"description":"Replay","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/BookingResult"}},"required":["status","data"]}}}},"201":{"description":"Booked","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/BookingResult"}},"required":["status","data"]},"example":{"status":"success","data":{"shipment":{"public_id":"QD-SHP-8F2A61C04B7D93E5A1C6F0B2","tracking_number":"QDE-82AF7CCD60392C9372F5EBDB","service":"RELAY","status":"BOOKED","amount_due_minor":2500,"merchant_reference":"SHOP-1001","payment_obligation_public_id":null},"replayed":false,"simulated":false,"environment":"LIVE"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shipments/{shipmentId}":{"get":{"operationId":"getShipment","summary":"One shipment","tags":["Shipments"],"description":"One shipment\n\nScope: `shipments.read`.","x-qoene-scopes":["shipments.read"],"x-qoene-live-only":false,"parameters":[{"name":"shipmentId","in":"path","required":true,"schema":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"}}],"responses":{"200":{"description":"The shipment","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ShipmentResult"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shipments/{shipmentId}/tracking":{"get":{"operationId":"getTracking","summary":"Tracking and milestones","tags":["Tracking"],"description":"The scoped event timeline plus a stable buyer view: the current `milestone`, its label, the product's main steps and any exception or return track. Show milestones to buyers instead of raw statuses. `promise` gives the promise frozen at booking and the current one (with the reason for any change) and whether it is on time, at risk or late.\n\nScope: `tracking.read`.","x-qoene-scopes":["tracking.read"],"x-qoene-live-only":false,"parameters":[{"name":"shipmentId","in":"path","required":true,"schema":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"}}],"responses":{"200":{"description":"Tracking","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/TrackingResult"}},"required":["status","data"]},"example":{"status":"success","data":{"tracking":{"shipmentId":"QD-SHP-8F2A61C04B7D93E5A1C6F0B2","trackingNumber":"QDE-82AF7CCD60392C9372F5EBDB","service":"RELAY","status":"READY_FOR_PICKUP","createdAt":"2026-10-27T10:15:00.000Z","simulated":false,"events":[{"status":"BOOKED","at":"2026-10-27T10:15:00.000Z"},{"status":"READY_FOR_PICKUP","at":"2026-10-28T14:02:00.000Z"}],"serviceCode":"RELAY_POINT","milestone":"READY_FOR_PICKUP","milestoneLabel":"Ready for pickup","viewMode":"READY_AT_POINT","milestones":[{"code":"BOOKED","label":"Booked","state":"done","at":"2026-10-27T10:15:00.000Z"},{"code":"DROPPED_OFF","label":"Dropped off","state":"done","at":"2026-10-27T12:30:00.000Z"},{"code":"IN_TRANSIT","label":"In transit","state":"done","at":"2026-10-27T16:10:00.000Z"},{"code":"ARRIVING_AT_POINT","label":"Arriving at point","state":"done","at":"2026-10-28T11:40:00.000Z"},{"code":"READY_FOR_PICKUP","label":"Ready for pickup","state":"current","at":"2026-10-28T14:02:00.000Z"},{"code":"COLLECTED","label":"Collected","state":"upcoming","at":null}],"exception":null,"returnTrack":null,"promise":{"original":{"revision":1,"promisedBy":"2026-10-29T23:59:59.000Z","promisedDate":"2026-10-29","label":"Ready to collect by Thu 29 Oct","window":{"start":"2026-10-29T07:00:00.000Z","end":"2026-10-29T20:00:00.000Z"},"reasonCode":"BOOKED","reasonLabel":"Promise at booking","createdAt":"2026-10-27T10:15:00.000Z"},"current":{"revision":1,"promisedBy":"2026-10-29T23:59:59.000Z","promisedDate":"2026-10-29","label":"Ready to collect by Thu 29 Oct","window":{"start":"2026-10-29T07:00:00.000Z","end":"2026-10-29T20:00:00.000Z"},"reasonCode":"BOOKED","reasonLabel":"Promise at booking","createdAt":"2026-10-27T10:15:00.000Z"},"revised":false,"status":{"code":"DELIVERED_ON_TIME","label":"On time"},"history":[]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shipments/{shipmentId}/cancel":{"post":{"operationId":"cancelShipment","summary":"Cancel before handoff","tags":["Shipments"],"description":"LIVE only before custody handoff; a wallet-paid parcel also needs `wallet.spend`. Paid or uncertain-payment parcels need assisted cancellation (409).\n\nScope: `shipments.cancel`.","x-qoene-scopes":["shipments.cancel"],"x-qoene-live-only":false,"parameters":[{"name":"shipmentId","in":"path","required":true,"schema":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,160}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRequest"},"example":{"reason":"Buyer cancelled the order before dispatch"}}}},"responses":{"200":{"description":"Cancelled (or replay)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CancelResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shipments/{shipmentId}/payment-intents":{"post":{"operationId":"createPaymentIntent","summary":"Request prepaid payment approval","tags":["Payments"],"description":"Creates an approval request for an authorized Business member, never a charge. Send an empty JSON body.\n\nScope: `payments.write`.","x-qoene-scopes":["payments.write"],"x-qoene-live-only":false,"parameters":[{"name":"shipmentId","in":"path","required":true,"schema":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,160}$"}}],"responses":{"200":{"description":"Replay","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/PaymentIntentResult"}},"required":["status","data"]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/PaymentIntentResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/payment-intents/{intentId}":{"get":{"operationId":"getPaymentIntent","summary":"Payment intent status","tags":["Payments"],"description":"Payment intent status\n\nScope: `payments.read`.","x-qoene-scopes":["payments.read"],"x-qoene-live-only":false,"parameters":[{"name":"intentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Intent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/PaymentIntentStatus"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shipments/{shipmentId}/labels":{"post":{"operationId":"issueLabel","summary":"Issue the first label","tags":["Labels"],"description":"Send an empty JSON body. Later calls return the existing label with replayed: true.\n\nScope: `labels.write`. LIVE keys only.","x-qoene-scopes":["labels.write"],"x-qoene-live-only":true,"parameters":[{"name":"shipmentId","in":"path","required":true,"schema":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,160}$"}}],"responses":{"200":{"description":"Existing label","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/LabelResult"}},"required":["status","data"]}}}},"201":{"description":"Issued","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/LabelResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shipments/{shipmentId}/labels/{labelId}.pdf":{"get":{"operationId":"getLabelPdf","summary":"Download a label PDF","tags":["Labels"],"description":"Download a label PDF\n\nScope: `labels.read`. LIVE keys only.","x-qoene-scopes":["labels.read"],"x-qoene-live-only":true,"parameters":[{"name":"shipmentId","in":"path","required":true,"schema":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"}},{"name":"labelId","in":"path","required":true,"schema":{"type":"string","description":"Label ID","pattern":"^(?:QD-LBL-[A-F0-9]{24}|QDLBL[A-Z0-9]{3,31})$"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["a6","a4"]},"description":"a6 (default) or a4 (A6 centred on A4)."}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/manifests":{"post":{"operationId":"createManifest","summary":"Batch manifest for booked shipments","tags":["Manifests"],"description":"Batch manifest for booked shipments\n\nScope: `manifests.write`. LIVE keys only.","x-qoene-scopes":["manifests.write"],"x-qoene-live-only":true,"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,160}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestRequest"},"example":{"shipmentIds":["QD-SHP-8F2A61C04B7D93E5A1C6F0B2"]}}}},"responses":{"200":{"description":"Replay","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ManifestResult"}},"required":["status","data"]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ManifestResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/manifests/{manifestId}":{"get":{"operationId":"getManifest","summary":"One manifest","tags":["Manifests"],"description":"One manifest\n\nScope: `manifests.read`. LIVE keys only.","x-qoene-scopes":["manifests.read"],"x-qoene-live-only":true,"parameters":[{"name":"manifestId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Manifest","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ManifestStatus"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/orders":{"post":{"operationId":"createOrder","summary":"Add a store order to the inbox","tags":["Orders"],"description":"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).\n\nScope: `orders.write`.","x-qoene-scopes":["orders.write"],"x-qoene-live-only":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreateRequest"},"example":{"storeId":"QD-STR-6A2F9C1E7B3D05A8F4C2E1B9","externalOrderId":"1001","receiver":{"name":"Kwame Mensah","phone":"0247654321"},"serviceCode":"RELAY_POINT","destinationPointCode":"QD-PU-1D7F3B9E5A2C08F4B6E1A9D3","items":[{"name":"Cotton shirt","sku":"SHIRT-M","quantity":2,"unitPriceMinor":15000}],"description":"Two cotton shirts","parcel":{"actualWeightGrams":1200,"lengthMm":300,"widthMm":200,"heightMm":120},"orderTotalMinor":30000,"storePaymentState":"PAID","placedAt":"2026-10-27T10:15:00.000Z"}}}},"responses":{"200":{"description":"Already in the inbox","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/OrderCreateResult"}},"required":["status","data"]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/OrderCreateResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"operationId":"listOrders","summary":"List orders","tags":["Orders"],"description":"Orders in stores bound to this key's API client, newest first, with per-status counts.\n\nScope: `orders.read`.","x-qoene-scopes":["orders.read"],"x-qoene-live-only":false,"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["AWAITING_SHIPMENT","SHIPMENT_CREATED","FAILED","CANCELLED"]},"description":"Status."},{"name":"storeId","in":"query","required":false,"schema":{"type":"string","description":"Store ID","pattern":"^(?:QD-STR-[A-F0-9]{24}|QDSTR[A-Z0-9]{3,31})$","example":"QD-STR-0123456789ABCDEF01234567"},"description":"One store."},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":100},"description":"Order number, reference, receiver, buyer or tracking number."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from nextCursor."}],"responses":{"200":{"description":"A page of orders","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/OrderList"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/orders/{orderId}":{"get":{"operationId":"getOrder","summary":"One order with ship attempts","tags":["Orders"],"description":"One order with ship attempts\n\nScope: `orders.read`.","x-qoene-scopes":["orders.read"],"x-qoene-live-only":false,"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","description":"Commerce order ID","pattern":"^(?:QD-ORD-[A-F0-9]{24}|QDORD[A-Z0-9]{3,31})$","example":"QD-ORD-0123456789ABCDEF01234567"}}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/OrderResult"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/orders/{orderId}/ship":{"post":{"operationId":"shipOrder","summary":"Ship one order","tags":["Orders"],"description":"Queues the same background ship run as the Business inbox (NB11): quote, booking as the verified Business owner, first label when the parcel is ready. An order with a checkout selection (NB16) books the selection quote at the shopper price while it is unused and unexpired and the run keeps its product, point, parcel, payment terms and origin; otherwise it quotes afresh. Poll GET /ship-jobs/{jobId} or subscribe to order.shipped / order.failed. BUSINESS_WALLET also needs `wallet.spend`.\n\nScope: `orders.ship`. LIVE keys only.","x-qoene-scopes":["orders.ship"],"x-qoene-live-only":true,"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","description":"Commerce order ID","pattern":"^(?:QD-ORD-[A-F0-9]{24}|QDORD[A-Z0-9]{3,31})$","example":"QD-ORD-0123456789ABCDEF01234567"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"8–100 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,100}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipRequest"},"example":{"paymentMode":"BUSINESS_INVOICE","prohibitedItemsDeclaration":{"accepted":true,"version":"2026-10-v1"}}}}},"responses":{"200":{"description":"Replay","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ShipJobResult"}},"required":["status","data"]}}}},"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ShipJobResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/ship-jobs":{"post":{"operationId":"createShipJob","summary":"Ship several orders","tags":["Orders"],"description":"1–100 orders in one run; up to 5 runs in progress per Business (429 beyond). Already shipped, cancelled, queued or TEST orders are skipped with a reason.\n\nScope: `orders.ship`. LIVE keys only.","x-qoene-scopes":["orders.ship"],"x-qoene-live-only":true,"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–100 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,100}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipJobsRequest"},"example":{"orderIds":["QD-ORD-9E4B2A7C1F5D38E0A6C4B2F1"],"paymentMode":"BUSINESS_INVOICE","prohibitedItemsDeclaration":{"accepted":true,"version":"2026-10-v1"}}}}},"responses":{"200":{"description":"Replay","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ShipJobResult"}},"required":["status","data"]}}}},"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ShipJobResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/ship-jobs/{jobId}":{"get":{"operationId":"getShipJob","summary":"Ship run with per-order results","tags":["Orders"],"description":"Only runs requested by this key's API client.\n\nScope: `orders.read`.","x-qoene-scopes":["orders.read"],"x-qoene-live-only":false,"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","description":"Ship run ID","pattern":"^(?:QD-SHJ-[A-F0-9]{24}|QDSHJ[A-Z0-9]{3,31})$","example":"QD-SHJ-0123456789ABCDEF01234567"}}],"responses":{"200":{"description":"The run","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ShipJobStatus"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/declarations/prohibited-items":{"get":{"operationId":"getProhibitedItemsDeclaration","summary":"Current prohibited-items declaration","tags":["Shipments"],"description":"Every booking and ship run must confirm `{ accepted: true, version }` for the current version, after your shop has shown it to whoever books. A changed version makes older confirmations fail with 409 `PROHIBITED_ITEMS_DECLARATION_REQUIRED`. Any valid key; no scope.","responses":{"200":{"description":"The declaration in force","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/DeclarationResult"}},"required":["status","data"]},"example":{"status":"success","data":{"declaration":{"version":"2026-10-v1","title":"Prohibited and restricted items","body":"I confirm this parcel contains no prohibited items…","publishedAt":"2026-10-01T00:00:00.000Z"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhook-endpoints":{"get":{"operationId":"listWebhookEndpoints","summary":"Webhook endpoints of this API client","tags":["Webhooks"],"description":"Webhook endpoints of this API client\n\nScope: `webhooks.read`. LIVE keys only.","x-qoene-scopes":["webhooks.read"],"x-qoene-live-only":true,"responses":{"200":{"description":"Endpoints and supported events","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/WebhookEndpointList"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createWebhookEndpoint","summary":"Create a webhook endpoint","tags":["Webhooks"],"description":"Public HTTPS on port 443 only; up to 10 active endpoints per client; no duplicate active URL. The `whsec_` secret is shown once. Rotate by creating a replacement and disabling the old endpoint.\n\nScope: `webhooks.write`. LIVE keys only.","x-qoene-scopes":["webhooks.write"],"x-qoene-live-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreateRequest"},"example":{"url":"https://shop.example.com/webhooks/qoene","events":["shipment.status_changed","payment.confirmed","order.shipped","order.failed"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/WebhookEndpointCreated"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhook-endpoints/{endpointId}/disable":{"post":{"operationId":"disableWebhookEndpoint","summary":"Disable an endpoint","tags":["Webhooks"],"description":"Stops queued sends; an attempt already in flight may still finish.\n\nScope: `webhooks.write`. LIVE keys only.","x-qoene-scopes":["webhooks.write"],"x-qoene-live-only":true,"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Disabled","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/WebhookEndpointDisabled"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhook-endpoints/{endpointId}/test":{"post":{"operationId":"testWebhookEndpoint","summary":"Queue a signed webhook.test event","tags":["Webhooks"],"description":"Queue a signed webhook.test event\n\nScope: `webhooks.write`. LIVE keys only.","x-qoene-scopes":["webhooks.write"],"x-qoene-live-only":true,"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/WebhookTestResult"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/checkout/sessions":{"post":{"operationId":"createCheckoutSession","summary":"Start a checkout session for the widget","tags":["Checkout"],"description":"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.\n\nScope: `checkout.write`.","x-qoene-scopes":["checkout.write"],"x-qoene-live-only":false,"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,160}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionRequest"},"example":{"parcel":{"actualWeightGrams":1200,"lengthMm":300,"widthMm":200,"heightMm":120},"origin":{"pointCode":"QD-DO-5B1E9C3A7F2D04E8B6A1C9F3","address":{"text":"Adwoa Styles, Oxford Street, Osu, Accra","latitude":5.5566,"longitude":-0.1826}},"serviceCodes":["EXPRESS_STANDARD","EXPRESS_PRIORITY","RELAY_POINT","RELAY_LOCKER","RELAY_HOME"],"payOnPickup":false,"orderReference":"SHOP-1001"}}}},"responses":{"200":{"description":"Replay","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CheckoutSessionResult"}},"required":["status","data"]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CheckoutSessionResult"}},"required":["status","data"]},"example":{"status":"success","data":{"session":{"id":"QD-CKS-4B7E2A9C1F5D38E0A6C4B2F1","clientSecret":"qd_cks_3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f","environment":"TEST","expiresAt":"2026-10-27T10:45:00.000Z","serviceCodes":["EXPRESS_STANDARD","EXPRESS_PRIORITY","RELAY_POINT","RELAY_LOCKER","RELAY_HOME"],"parcel":{"actualWeightGrams":1200,"lengthMm":300,"widthMm":200,"heightMm":120},"origin":{"pointCode":"QD-DO-5B1E9C3A7F2D04E8B6A1C9F3","address":{"text":"Adwoa Styles, Oxford Street, Osu, Accra","latitude":5.5566,"longitude":-0.1826}},"payOnPickup":false,"orderReference":"SHOP-1001","prefill":null},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/checkout/selections/verify":{"post":{"operationId":"verifyCheckoutSelection","summary":"Check a selection token from the widget","tags":["Checkout"],"description":"Verifies the signature, expiry, Business and environment of a checkout selection token and returns what the buyer chose (price, promised date, point) and whether it was already used. You can also verify offline with the public keys from GET /checkout/keys; booking with `checkoutSelection` checks it again and uses it once.\n\nScope: `checkout.write`.","x-qoene-scopes":["checkout.write"],"x-qoene-live-only":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSelectionVerifyRequest"}}}},"responses":{"200":{"description":"Valid selection","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CheckoutSelectionVerification"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/checkout/keys":{"get":{"operationId":"getCheckoutKeys","summary":"Public keys for selection tokens","tags":["Checkout"],"description":"JSON Web Key Set (Ed25519, `alg: EdDSA`) that signs checkout selection tokens. Cache it for up to 5 minutes; during a key rotation two keys are listed and the token header `kid` names the one used.","security":[],"responses":{"200":{"description":"JWKS","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CheckoutJwks"}},"required":["status","data"]}}}}}}},"/checkout/config":{"get":{"operationId":"getCheckoutConfig","summary":"Widget start-up details","tags":["Checkout"],"description":"Browser only, called by the widget. The merchant name, environment and whether address suggestions are available; with `X-Qoene-Checkout-Session`, the session's products, parcel and prefill.","security":[{"PublishableKey":[]}],"x-qoene-browser":true,"responses":{"200":{"description":"Configuration","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CheckoutConfig"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/checkout/options":{"post":{"operationId":"getCheckoutOptions","summary":"Delivery options for a buyer address","tags":["Checkout"],"description":"Browser only, called by the widget. Prices every eligible product for the session's parcel and origin to the buyer's address, with the promised date (NB19) and the best-ranked Qoene Point or locker (NB08), and explains each product that is not available. Send `pointCode`, `lockerCode` or `fallbackPointCode` to re-price with the buyer's own choice. At most 40 calls per session.","security":[{"PublishableKey":[],"CheckoutSession":[]}],"x-qoene-browser":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutOptionsRequest"}}}},"responses":{"200":{"description":"Offers","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CheckoutOptions"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"410":{"$ref":"#/components/responses/Gone"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/checkout/points":{"get":{"operationId":"getCheckoutPoints","summary":"Ranked Qoene Points for the picker","tags":["Checkout"],"description":"Browser only, called by the widget. Ranked pickup points (or lockers, or Relay Home fallback points) near a position, sized for the session's parcel when `X-Qoene-Checkout-Session` is sent; same ranking as GET /locations/search.","security":[{"PublishableKey":[]}],"x-qoene-browser":true,"parameters":[{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude (required)."},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180},"description":"Longitude (required)."},{"name":"product","in":"query","required":false,"schema":{"type":"string","enum":["RELAY_POINT","RELAY_LOCKER","RELAY_HOME"]},"description":"Default RELAY_POINT."},{"name":"radius","in":"query","required":false,"schema":{"type":"integer","minimum":100,"maximum":50000,"default":10000},"description":"Metres."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Ranked results."}],"responses":{"200":{"description":"Ranked points","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CheckoutPoints"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/checkout/places":{"get":{"operationId":"getCheckoutPlaces","summary":"Address suggestions","tags":["Checkout"],"description":"Browser only, called by the widget. Address suggestions from Google Maps Places when Qoene has it configured; `available: false` means the widget shows a plain address field.","security":[{"PublishableKey":[]}],"x-qoene-browser":true,"parameters":[{"name":"input","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":200},"description":"What the buyer typed (required)."}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CheckoutPlaces"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/checkout/selections":{"post":{"operationId":"createCheckoutSelection","summary":"Confirm the buyer's choice","tags":["Checkout"],"description":"Browser only, called by the widget when the buyer confirms. Returns a signed selection `token` (compact JWS, EdDSA) for one offer of this session. The widget hands it to your page; send it to your server and on to POST /shipments as `checkoutSelection`.","security":[{"PublishableKey":[],"CheckoutSession":[]}],"x-qoene-browser":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSelectionRequest"}}}},"responses":{"201":{"description":"Signed selection","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/CheckoutSelectionIssued"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/claims":{"get":{"operationId":"listClaims","summary":"List claims","tags":["Claims"],"description":"Claims on this Business's parcels, newest first, whoever filed them (API, Business workspace).\n\nScope: `claims.read`.","x-qoene-scopes":["claims.read"],"x-qoene-live-only":false,"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"One status or several, comma-separated."},"description":"Filter by status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from nextCursor."}],"responses":{"200":{"description":"A page of claims","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ClaimList"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createClaim","summary":"File a claim for a parcel","tags":["Claims"],"description":"Loss, damage, missing items, delay (the delivery promise was missed) or a wrong delivery, inside the product's claim window (409 CLAIM_WINDOW_CLOSED after it). One open claim per parcel and reason (409 CLAIM_ALREADY_OPEN). Qoene checks the parcel's custody record automatically; a supervisor decides and you receive claim.* events. Add photos or documents with POST /claims/{claimId}/evidence.\n\nScope: `claims.write`. LIVE keys only.","x-qoene-scopes":["claims.write"],"x-qoene-live-only":true,"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,160}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimCreateRequest"},"example":{"trackingNumber":"QDE-82AF7CCD60392C9372F5EBDB","reason":"DAMAGE","description":"The ceramic bowl arrived broken; the box was crushed on one corner.","declaredValueMinor":25000}}}},"responses":{"200":{"description":"Replay","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ClaimCreateResult"}},"required":["status","data"]}}}},"201":{"description":"Filed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ClaimCreateResult"}},"required":["status","data"]},"example":{"status":"success","data":{"claim":{"id":"QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4","status":"SUBMITTED","reason":"DAMAGE","description":"The ceramic bowl arrived broken; the box was crushed on one corner.","declaredValueMinor":25000,"currency":"GHS","shipment":{"trackingNumber":"QDE-82AF7CCD60392C9372F5EBDB","id":"QD-SHP-8F2A61C04B7D93E5A1C6F0B2"},"claimant":"MERCHANT","source":"API","windowEndsAt":"2026-11-10T10:15:00.000Z","liabilityCapMinor":50000,"approvedMinor":null,"decisionReason":null,"decidedAt":null,"caseReference":"QD-SUP-7B2E9A4C1F6D03B8E5A2C9F1","createdAt":"2026-10-27T10:15:00.000Z","updatedAt":"2026-10-27T10:15:00.000Z","evidence":[],"payouts":[],"timeline":[{"type":"claim.submitted","at":"2026-10-27T10:15:00.000Z"}]},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/claims/{claimId}":{"get":{"operationId":"getClaim","summary":"One claim with evidence, payouts and timeline","tags":["Claims"],"description":"One claim with evidence, payouts and timeline\n\nScope: `claims.read`.","x-qoene-scopes":["claims.read"],"x-qoene-live-only":false,"parameters":[{"name":"claimId","in":"path","required":true,"schema":{"type":"string","description":"Claim ID","pattern":"^(?:QD-CLM-[A-F0-9]{24}|QDCLM[A-Z0-9]{3,31})$","example":"QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4"}}],"responses":{"200":{"description":"The claim","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ClaimResult"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/claims/{claimId}/evidence":{"post":{"operationId":"addClaimEvidence","summary":"Attach a photo or document","tags":["Claims"],"description":"JPEG, PNG or PDF up to 3.5 MB, up to 10 files, before the decision. Stored privately; the same file twice returns 409.\n\nScope: `claims.write`. LIVE keys only.","x-qoene-scopes":["claims.write"],"x-qoene-live-only":true,"parameters":[{"name":"claimId","in":"path","required":true,"schema":{"type":"string","description":"Claim ID","pattern":"^(?:QD-CLM-[A-F0-9]{24}|QDCLM[A-Z0-9]{3,31})$","example":"QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimEvidenceRequest"},"example":{"fileName":"damage.jpg","contentBase64":"/9j/4AAQSkZJRgABAQAAAQABAAD…"}}}},"responses":{"201":{"description":"Attached","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ClaimEvidenceResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/returns":{"get":{"operationId":"listReturns","summary":"List returns","tags":["Returns"],"description":"Returns of this Business's parcels, newest first, whoever started them (customer, Business workspace or API).\n\nScope: `returns.read`.","x-qoene-scopes":["returns.read"],"x-qoene-live-only":false,"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"One status or several, comma-separated."},"description":"Filter by status."},{"name":"storeId","in":"query","required":false,"schema":{"type":"string","description":"Store ID","pattern":"^(?:QD-STR-[A-F0-9]{24}|QDSTR[A-Z0-9]{3,31})$","example":"QD-STR-0123456789ABCDEF01234567"},"description":"Only this store."},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Return ID, tracking number, order reference or external order ID."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from nextCursor."}],"responses":{"200":{"description":"A page of returns","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ReturnList"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createReturn","summary":"Start a return for your customer","tags":["Returns"],"description":"For a delivered or collected LIVE parcel inside your return window (409 WINDOW_CLOSED after it), one open return per parcel (409 RETURN_OPEN). A return you start is approved at once: Qoene books the return parcel (billed to your wallet or invoice unless your policy makes the customer pay) and sends your customer a paperless drop-off code by SMS, WhatsApp and email. Customers can also start returns themselves from the Qoene tracking page; those follow your policy (automatic or your review).\n\nScope: `returns.write`. LIVE keys only.","x-qoene-scopes":["returns.write"],"x-qoene-live-only":true,"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–160 characters (A-Z, a-z, 0-9, . _ : -). Retrying with the same key and body returns the original result; another body returns 409.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,160}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnCreateRequest"},"example":{"trackingNumber":"QDE-82AF7CCD60392C9372F5EBDB","items":[{"line":1,"quantity":1}],"reason":"WRONG_SIZE","productCode":"RELAY_POINT","dropoffPointCode":"QD-PT-0A1B2C3D4E5F60718293A4B5","prohibitedItemsDeclaration":{"accepted":true,"version":"2026-10-v1"}}}}},"responses":{"200":{"description":"Replay","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ReturnCreateResult"}},"required":["status","data"]}}}},"201":{"description":"Started","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ReturnCreateResult"}},"required":["status","data"]},"example":{"status":"success","data":{"return":{"id":"QD-RET-5C2E8A1F9B3D07E4A6C1F8B2","status":"AWAITING_DROPOFF","source":"MERCHANT_API","reason":"WRONG_SIZE","reasonLabel":"Wrong size or fit","note":null,"items":[{"line":1,"name":"Kente scarf","sku":"KS-1","quantity":1,"unitPriceMinor":4500}],"declaredValueMinor":4500,"product":"RELAY_POINT","payer":"MERCHANT","priceMinor":900,"deductFromRefundMinor":0,"currency":"GHS","promisedBy":"2026-11-06T23:59:59.000Z","dropoffBy":"2026-11-17T10:15:00.000Z","customer":{"name":"Ama Owusu"},"originalShipment":{"id":"QD-SHP-8F2A61C04B7D93E5A1C6F0B2","trackingNumber":"QDE-82AF7CCD60392C9372F5EBDB","orderReference":"ACC-1042"},"returnShipment":{"id":"QD-SHP-1B7E4C9A2D5F08E3A6C1B9D4","trackingNumber":"QDE-4C1A9E7B2D5F08E3A6C1B9D4","status":"AWAITING_DROPOFF"},"dropoffPoint":{"code":"QD-PT-0A1B2C3D4E5F60718293A4B5","name":"Osu Point"},"returnsTo":{"code":"QD-PT-9F8E7D6C5B4A39281706F5E4","name":"Accra Fashion pickup"},"store":null,"order":null,"code":{"status":"ACTIVE","expiresAt":"2026-11-17T10:15:00.000Z","usedAt":null},"payment":{"obligationId":"QD-BILL-2E9C4A7B1D5F08E3A6C1B9D4","status":"PAID"},"decision":{"at":"2026-11-03T10:15:00.000Z","reason":null,"automatic":false},"inspection":null,"refund":null,"claim":null,"createdAt":"2026-11-03T10:15:00.000Z","updatedAt":"2026-11-03T10:15:00.000Z"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/returns/policy":{"get":{"operationId":"getReturnPolicy","summary":"The return policy in force","tags":["Returns"],"description":"The return policy in force\n\nScope: `returns.read`.","x-qoene-scopes":["returns.read"],"x-qoene-live-only":false,"parameters":[{"name":"storeId","in":"query","required":false,"schema":{"type":"string","description":"Store ID","pattern":"^(?:QD-STR-[A-F0-9]{24}|QDSTR[A-Z0-9]{3,31})$","example":"QD-STR-0123456789ABCDEF01234567"},"description":"A store's own policy, when it has one."}],"responses":{"200":{"description":"The policy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ReturnPolicyResult"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/returns/quote":{"post":{"operationId":"quoteReturn","summary":"Price and promise of a return option","tags":["Returns"],"description":"Prices the return parcel from a drop-off point (or the customer's address for Express) to where your returns go, with your contract rates, and the promised date of the return leg.\n\nScope: `returns.write`. LIVE keys only.","x-qoene-scopes":["returns.write"],"x-qoene-live-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnQuoteRequest"}}}},"responses":{"200":{"description":"The quote","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ReturnQuoteResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/returns/{returnId}":{"get":{"operationId":"getReturn","summary":"One return","tags":["Returns"],"description":"One return\n\nScope: `returns.read`.","x-qoene-scopes":["returns.read"],"x-qoene-live-only":false,"parameters":[{"name":"returnId","in":"path","required":true,"schema":{"type":"string","description":"Return ID","pattern":"^(?:QD-RET-[A-F0-9]{24}|QDRET[A-Z0-9]{3,31})$","example":"QD-RET-5C2E8A1F9B3D07E4A6C1F8B2"}}],"responses":{"200":{"description":"The return","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ReturnResult"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/returns/{returnId}/approve":{"post":{"operationId":"approveReturn","summary":"Approve a customer's return","tags":["Returns"],"description":"Books the return parcel and activates (or, when the customer pays, prepares) the drop-off code. 409 when it is not waiting for review or your wallet cannot cover it.\n\nScope: `returns.write`. LIVE keys only.","x-qoene-scopes":["returns.write"],"x-qoene-live-only":true,"parameters":[{"name":"returnId","in":"path","required":true,"schema":{"type":"string","description":"Return ID","pattern":"^(?:QD-RET-[A-F0-9]{24}|QDRET[A-Z0-9]{3,31})$","example":"QD-RET-5C2E8A1F9B3D07E4A6C1F8B2"}}],"responses":{"200":{"description":"Approved","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ReturnResult"}},"required":["status","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/returns/{returnId}/reject":{"post":{"operationId":"rejectReturn","summary":"Reject a customer's return","tags":["Returns"],"description":"The customer gets your reason by SMS.\n\nScope: `returns.write`. LIVE keys only.","x-qoene-scopes":["returns.write"],"x-qoene-live-only":true,"parameters":[{"name":"returnId","in":"path","required":true,"schema":{"type":"string","description":"Return ID","pattern":"^(?:QD-RET-[A-F0-9]{24}|QDRET[A-Z0-9]{3,31})$","example":"QD-RET-5C2E8A1F9B3D07E4A6C1F8B2"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnDecisionRequest"}}}},"responses":{"200":{"description":"Rejected","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ReturnResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/returns/{returnId}/cancel":{"post":{"operationId":"cancelReturn","summary":"Cancel a return before drop-off","tags":["Returns"],"description":"Before drop-off only. A wallet charge is given back and an invoice reservation released. A return the customer already paid for is cancelled by Qoene support (409 RETURN_PAID_BY_CUSTOMER).\n\nScope: `returns.write`. LIVE keys only.","x-qoene-scopes":["returns.write"],"x-qoene-live-only":true,"parameters":[{"name":"returnId","in":"path","required":true,"schema":{"type":"string","description":"Return ID","pattern":"^(?:QD-RET-[A-F0-9]{24}|QDRET[A-Z0-9]{3,31})$","example":"QD-RET-5C2E8A1F9B3D07E4A6C1F8B2"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnDecisionRequest"}}}},"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/ReturnResult"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/analytics/summary":{"get":{"operationId":"getAnalyticsSummary","summary":"Your delivery performance","tags":["Analytics"],"description":"Volume trend, on-time rate, delivery time by product and region, returns and claims rates, cost per parcel, overstay you covered and top destinations, for your own parcels. Figures are rebuilt hourly from daily aggregates in the market time zone (Africa/Accra for Ghana). The period defaults to the last 30 days and is at most 366 days.\n\nScope: `analytics.read`.","x-qoene-scopes":["analytics.read"],"x-qoene-live-only":false,"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"First business day (YYYY-MM-DD). Default 29 days before `to`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Last business day (YYYY-MM-DD). Default today in the market."}],"responses":{"200":{"description":"Your figures","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"success"},"data":{"$ref":"#/components/schemas/AnalyticsSummary"}},"required":["status","data"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"webhooks":{"shipment.created":{"post":{"operationId":"webhook_shipment_created","summary":"shipment.created","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.status_changed":{"post":{"operationId":"webhook_shipment_status_changed","summary":"Broad subscription: every shipment transition, delivered under its specific name when one exists.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.driver_assigned":{"post":{"operationId":"webhook_shipment_driver_assigned","summary":"shipment.driver_assigned","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.driver_arriving":{"post":{"operationId":"webhook_shipment_driver_arriving","summary":"shipment.driver_arriving","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.dropoff_accepted":{"post":{"operationId":"webhook_shipment_dropoff_accepted","summary":"shipment.dropoff_accepted","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.picked_up":{"post":{"operationId":"webhook_shipment_picked_up","summary":"shipment.picked_up","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.in_transit":{"post":{"operationId":"webhook_shipment_in_transit","summary":"shipment.in_transit","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.received_at_hub":{"post":{"operationId":"webhook_shipment_received_at_hub","summary":"shipment.received_at_hub","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.arrived_at_pickup":{"post":{"operationId":"webhook_shipment_arrived_at_pickup","summary":"shipment.arrived_at_pickup","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.ready_for_pickup":{"post":{"operationId":"webhook_shipment_ready_for_pickup","summary":"shipment.ready_for_pickup","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.ready_in_locker":{"post":{"operationId":"webhook_shipment_ready_in_locker","summary":"shipment.ready_in_locker","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.delivered":{"post":{"operationId":"webhook_shipment_delivered","summary":"shipment.delivered","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.collected":{"post":{"operationId":"webhook_shipment_collected","summary":"shipment.collected","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.pickup_failed":{"post":{"operationId":"webhook_shipment_pickup_failed","summary":"shipment.pickup_failed","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.delivery_attempt_failed":{"post":{"operationId":"webhook_shipment_delivery_attempt_failed","summary":"shipment.delivery_attempt_failed","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.exception":{"post":{"operationId":"webhook_shipment_exception","summary":"shipment.exception","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.return_requested":{"post":{"operationId":"webhook_shipment_return_requested","summary":"shipment.return_requested","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.return_started":{"post":{"operationId":"webhook_shipment_return_started","summary":"shipment.return_started","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.return_at_origin":{"post":{"operationId":"webhook_shipment_return_at_origin","summary":"shipment.return_at_origin","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.returned":{"post":{"operationId":"webhook_shipment_returned","summary":"shipment.returned","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.cancelled":{"post":{"operationId":"webhook_shipment_cancelled","summary":"shipment.cancelled","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"payment.confirmed":{"post":{"operationId":"webhook_payment_confirmed","summary":"payment.confirmed","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"payment.failed":{"post":{"operationId":"webhook_payment_failed","summary":"payment.failed","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"refund.processed":{"post":{"operationId":"webhook_refund_processed","summary":"refund.processed","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"locker.overage_due":{"post":{"operationId":"webhook_locker_overage_due","summary":"locker.overage_due","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.out_for_delivery":{"post":{"operationId":"webhook_shipment_out_for_delivery","summary":"The parcel left for the delivery address. Endpoints subscribed to it receive that transition under this name.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.pickup_expiring":{"post":{"operationId":"webhook_shipment_pickup_expiring","summary":"Less than 24 hours left to collect from a point, or the final hour of a locker collection.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"order.created":{"post":{"operationId":"webhook_order_created","summary":"A store order entered the inbox.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"order.shipped":{"post":{"operationId":"webhook_order_shipped","summary":"A ship run created the order's shipment.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"order.failed":{"post":{"operationId":"webhook_order_failed","summary":"A ship run could not ship the order; `failure` says why.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookOrderEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.promise_revised":{"post":{"operationId":"webhook_shipment_promise_revised","summary":"The delivery promise changed (late drop-off, receiver choice, home fallback or operations), with the reason code.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.promise_missed":{"post":{"operationId":"webhook_shipment_promise_missed","summary":"The promised date passed without delivery or collection. Sent once per promise revision.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"claim.submitted":{"post":{"operationId":"webhook_claim_submitted","summary":"A claim was filed on one of your parcels.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookClaimEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"claim.under_review":{"post":{"operationId":"webhook_claim_under_review","summary":"Support started reviewing the claim.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookClaimEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"claim.approved":{"post":{"operationId":"webhook_claim_approved","summary":"The claim was approved in full.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookClaimEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"claim.partly_approved":{"post":{"operationId":"webhook_claim_partly_approved","summary":"The claim was approved for part of the amount.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookClaimEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"claim.rejected":{"post":{"operationId":"webhook_claim_rejected","summary":"The claim was not approved; read the reason with GET /claims/{claimId}.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookClaimEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"claim.paid":{"post":{"operationId":"webhook_claim_paid","summary":"The compensation was sent (wallet credit, refund or Mobile Money).","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookClaimEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"claim.withdrawn":{"post":{"operationId":"webhook_claim_withdrawn","summary":"The claim was withdrawn.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookClaimEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.requested":{"post":{"operationId":"webhook_return_requested","summary":"A customer started a return that waits for your review (or a return was started).","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.approved":{"post":{"operationId":"webhook_return_approved","summary":"The return was approved and its return parcel booked.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.rejected":{"post":{"operationId":"webhook_return_rejected","summary":"The return was rejected.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.cancelled":{"post":{"operationId":"webhook_return_cancelled","summary":"The return was cancelled before drop-off.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.expired":{"post":{"operationId":"webhook_return_expired","summary":"The drop-off code expired unused.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.dropped_off":{"post":{"operationId":"webhook_return_dropped_off","summary":"The customer handed the return to Qoene (point drop-off or rider pickup).","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.in_transit":{"post":{"operationId":"webhook_return_in_transit","summary":"The return is moving through the network.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.arrived":{"post":{"operationId":"webhook_return_arrived","summary":"The return is ready for you at your return point.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.received":{"post":{"operationId":"webhook_return_received","summary":"The return was handed to you. Refund your customer from your own system when you are ready.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.inspected":{"post":{"operationId":"webhook_return_inspected","summary":"You recorded the condition of the returned goods.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"return.refund_recorded":{"post":{"operationId":"webhook_return_refund_recorded","summary":"You recorded the customer refund.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReturnEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.home_attempt_failed":{"post":{"operationId":"webhook_shipment_home_attempt_failed","summary":"Relay Home: the one home attempt failed; `data.home_delivery` gives the reason and the fallback point.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.redirected_to_point":{"post":{"operationId":"webhook_shipment_redirected_to_point","summary":"Relay Home: the parcel is on its way to the fallback Qoene Point chosen at booking, where the receiver collects it.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.receiver_changed":{"post":{"operationId":"webhook_shipment_receiver_changed","summary":"The verified receiver changed the destination point or locker, the Relay Home fallback point, or extended the hold; `data.receiver_change` says what.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.overstay_started":{"post":{"operationId":"webhook_shipment_overstay_started","summary":"The free hold ended and overstay now applies; `data.overstay` gives the day rate, cap and when the parcel returns.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"shipment.overstay_paid":{"post":{"operationId":"webhook_shipment_overstay_paid","summary":"All overstay is paid (by the receiver, your wallet under your contract, or both) and the parcel can be collected.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookShipmentEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}},"webhook.test":{"post":{"operationId":"webhook_webhook_test","summary":"Synthetic test event queued with POST /webhook-endpoints/{id}/test.","parameters":[{"name":"X-Qoene-Event-Id","in":"header","description":"Stable event ID (same on retries).","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Timestamp","in":"header","description":"Unix seconds of this attempt.","schema":{"type":"string"},"required":true},{"name":"X-Qoene-Signature","in":"header","description":"v1=<hex HMAC-SHA256(secret, \"<timestamp>.<raw body>\")>. Compare in constant time; reject timestamps older than 5 minutes.","schema":{"type":"string","pattern":"^v1=[a-f0-9]{64}$"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestEvent"}}}},"responses":{"2XX":{"description":"Acknowledged after durable processing. Anything else is retried (network, 5xx, 408, 409, 425, 429) or failed."}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"qd_(test|live)_<prefix>_<secret>","description":"Merchant API key. Scopes: locations.read, quotes.write, shipments.write, wallet.spend, shipments.read, shipments.cancel, tracking.read, labels.read, labels.write, manifests.write, manifests.read, payments.write, payments.read, services.read, orders.read, orders.write, orders.ship, webhooks.read, webhooks.write, claims.read, claims.write, returns.read, returns.write, analytics.read, checkout.write."},"PublishableKey":{"type":"apiKey","in":"header","name":"X-Qoene-Publishable-Key","description":"NB15 publishable key (`qd_pk_test_…` / `qd_pk_live_…`) for the checkout widget. Safe in a browser: it only reads delivery options, promised dates and Qoene Points, only from the allowed origins set in Business → API & webhooks, and each key has its own per-minute limit (default 300). Created, changed and revoked by a Business Owner or Admin; every change is audited."},"CheckoutSession":{"type":"apiKey","in":"header","name":"X-Qoene-Checkout-Session","description":"The `clientSecret` of a checkout session your server created with POST /checkout/sessions."}},"schemas":{"MinorAmount":{"type":["integer","string"],"pattern":"^-?[0-9]+$","description":"Money in integer pesewas (GHS minor units). 64-bit columns are returned as a decimal string; treat both forms as an integer.","example":1250},"Environment":{"type":"string","enum":["TEST","LIVE"],"description":"The key environment. TEST never touches live custody, payments, dispatch or notifications."},"ServiceCode":{"type":"string","enum":["EXPRESS_STANDARD","EXPRESS_PRIORITY","RELAY_POINT","RELAY_LOCKER","RELAY_HOME"],"description":"Stable product code (NB02)."},"Error":{"type":"object","properties":{"status":{"type":"string","const":"error"},"message":{"type":"string","description":"Plain-language explanation."},"code":{"type":"string","description":"Machine-readable reason, when there is one (for example SENDER_VERIFICATION_REQUIRED, COMMERCE_ORDER_CONFLICT)."},"details":{"type":"object","properties":{},"description":"Extra machine-readable detail, for example `reason: { code, message }` for eligibility refusals."}},"required":["status","message"],"description":"Every error response.","example":{"status":"error","message":"API key scope required"}},"DeliveryPromise":{"type":"object","properties":{"rule":{"type":"string","enum":["SAME_DAY_BEFORE_CUTOFF","DIRECT_SAME_DAY","WORKING_DAYS"]},"cutoffLocalTime":{"type":["string","null"],"description":"HH:MM in the market time zone (Africa/Accra for Ghana)."},"beforeCutoff":{"type":"boolean"},"promisedBy":{"type":"string","description":"End of the promised local day.","format":"date-time"},"label":{"type":"string"},"timezone":{"type":"string"},"engineVersion":{"type":"string","description":"Promise engine version (NB19)."},"market":{"type":"string","example":"GH"},"promisedDate":{"type":"string","description":"Promised local date (YYYY-MM-DD).","format":"date"},"dateLabel":{"type":"string","example":"Thu 29 Oct"},"summary":{"type":"string","example":"Ready to collect by Thu 29 Oct"},"window":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"],"description":"Service hours on the promised day."},"startDate":{"type":"string","description":"Local date the parcel starts moving (after cut-offs, closures and non-working days).","format":"date"},"cutoffSource":{"type":"string","enum":["PRODUCT","PROMISE_RULES","EXPRESS_AREA","EXPRESS_AREA_RULE","ORIGIN_POINT","POINT_CLOSING","NONE"]},"transitWorkingDays":{"type":"integer"},"lane":{"oneOf":[{"type":"object","properties":{"origin":{"type":["string","null"]},"destination":{"type":["string","null"]},"transitWorkingDays":{"type":"integer"},"source":{"type":"string","enum":["LANE","PRODUCT_DEFAULT"]}},"required":["transitWorkingDays","source"],"description":"Relay region lane used for the transit time."},{"type":"null"}]},"originHub":{"type":["string","null"]},"destinationHub":{"type":["string","null"]},"expressArea":{"type":["string","null"]},"adjustedForDestination":{"type":"boolean","description":"Moved because the destination point is closed."},"checkpoints":{"type":"array","items":{"$ref":"#/components/schemas/PromiseCheckpoint"},"description":"Leg checkpoints the parcel must meet; missing one marks it at risk."},"ruleVersion":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"publicId":{"type":"string"},"versionNumber":{"type":"integer"}},"required":["publicId","versionNumber"],"description":"Promise rules version frozen with the quote."},{"type":"null"}]}},"required":["rule","promisedBy","label","timezone"],"description":"The delivery promise, worked out with the Ghana working calendar (public holidays and network closures), cut-offs and region lanes."},"PromiseCheckpoint":{"type":"object","properties":{"code":{"type":"string","enum":["PICKUP","OUT_FOR_DELIVERY","FIRST_SCAN","LINE_HAUL","ARRIVAL","FINAL"]},"milestone":{"type":"string","description":"Tracking milestone that satisfies the checkpoint (or any later one)."},"dueBy":{"type":"string","format":"date-time"},"label":{"type":"string"},"reasonIfMissed":{"type":"string"}},"required":["code","milestone","dueBy"]},"PromiseRevision":{"type":"object","properties":{"revision":{"type":"integer"},"promisedBy":{"type":"string","format":"date-time"},"promisedDate":{"type":"string","format":"date"},"label":{"type":"string"},"window":{"oneOf":[{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"]},{"type":"null"}]},"reasonCode":{"type":"string","enum":["BOOKED","BACKFILL","LATE_DROPOFF","RECEIVER_CHANGE","HOME_FALLBACK","OPERATIONAL"]},"reasonLabel":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["revision","promisedBy","promisedDate","reasonCode"]},"ShipmentPromise":{"type":"object","properties":{"original":{"$ref":"#/components/schemas/PromiseRevision"},"current":{"$ref":"#/components/schemas/PromiseRevision"},"revised":{"type":"boolean"},"status":{"type":"object","properties":{"code":{"type":"string","enum":["ON_TIME","AT_RISK","RUNNING_LATE","DELIVERED_ON_TIME","DELIVERED_LATE","NOT_APPLICABLE"]},"label":{"type":"string"}},"required":["code","label"],"description":"AT_RISK is shown to merchants only; consumers see ON_TIME until the promise is missed."},"history":{"type":"array","items":{"type":"object","properties":{"revision":{"type":"integer"},"promisedBy":{"type":"string","format":"date-time"},"reasonCode":{"type":"string"},"reasonLabel":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["revision","promisedBy","reasonCode"]}}},"required":["original","current","revised","status"],"description":"The promise frozen at booking (`original`) and the one in force (`current`). Changes are revisions with a reason; the booked promise never changes."},"WebhookPromise":{"type":"object","properties":{"revision":{"type":"integer"},"promised_by":{"type":"string","format":"date-time"},"promised_date":{"type":"string","format":"date"},"original_promised_by":{"type":"string","format":"date-time"},"reason_code":{"type":"string"},"status":{"type":"string","enum":["ON_TRACK","AT_RISK","LATE","MET","MISSED","VOID"]}},"required":["revision","promised_by","original_promised_by","status"],"description":"Only on shipment.promise_revised and shipment.promise_missed."},"Service":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ServiceCode"},"brand":{"type":"string","enum":["EXPRESS","RELAY"]},"name":{"type":"string"},"description":{"type":"string"},"ending":{"type":"string","enum":["DOOR","POINT","LOCKER","HOME"]},"serviceLevel":{"type":"string","enum":["STANDARD","PRIORITY"]},"originType":{"type":"string","enum":["ADDRESS","DROPOFF_POINT"]},"destinationType":{"type":"string","enum":["ADDRESS","PICKUP_POINT","LOCKER","ADDRESS_WITH_FALLBACK_POINT"]},"limits":{"type":"object","properties":{"maxWeightGrams":{"type":"integer"},"maxLengthMm":{"type":"integer"},"maxWidthMm":{"type":"integer"},"maxHeightMm":{"type":"integer"}},"required":["maxWeightGrams","maxLengthMm","maxWidthMm","maxHeightMm"]},"promise":{"type":"object","properties":{"rule":{"type":"string","enum":["SAME_DAY_BEFORE_CUTOFF","DIRECT_SAME_DAY","WORKING_DAYS"]},"workingDays":{"type":["integer","null"],"description":"Working days for WORKING_DAYS products (Monday–Saturday)."},"cutoffLocalTime":{"type":["string","null"]},"timezone":{"type":"string"},"ifBookedNow":{"$ref":"#/components/schemas/DeliveryPromise"}},"required":["rule","timezone","ifBookedNow"]}},"required":["code","brand","name","limits","promise"]},"Reason":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"ServiceUnavailable":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ServiceCode"},"name":{"type":"string"},"reason":{"$ref":"#/components/schemas/Reason"}},"required":["code","reason"]},"ContractSummary":{"type":"object","properties":{"id":{"type":"string"},"tierName":{"type":"string"},"allowedProducts":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCode"}},"effectiveFrom":{"type":"string","format":"date-time"},"effectiveTo":{"type":["string","null"],"format":"date-time"}},"required":["id","tierName","allowedProducts"]},"Address":{"type":"object","properties":{},"description":"Free-form address object as published by the point (for example line1, area, city).","additionalProperties":true},"OpenState":{"type":"object","properties":{"state":{"type":"string","enum":["OPEN","OPENS_LATER","CLOSED_TODAY","TEMPORARILY_CLOSED","HOURS_UNKNOWN"]},"label":{"type":"string"}},"required":["state","label"]},"Space":{"type":"object","properties":{"level":{"type":"string","enum":["PLENTY","LIMITED","ALMOST_FULL","FULL","UNKNOWN"]},"label":{"type":"string"}},"required":["level","label"],"description":"Space as a level; raw counts are never published."},"Closure":{"type":"object","properties":{"kind":{"type":"string","enum":["CLOSED","SPECIAL_HOURS"]},"startsOn":{"type":"string","format":"date"},"endsOn":{"type":"string","format":"date"},"opensAt":{"type":"string"},"closesAt":{"type":"string"}},"required":["kind","startsOn","endsOn"]},"MarketCode":{"type":"string","description":"Two-letter market (country network) code. Ghana (GH) is live; each market is a separate domestic network.","pattern":"^[A-Z]{2}$","example":"GH"},"Market":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/MarketCode"},"name":{"type":"string"},"status":{"type":"string","enum":["LIVE"]},"timezone":{"type":"string","description":"IANA time zone for dates and cut-offs."},"currency":{"type":"object","properties":{"code":{"type":"string","example":"GHS"},"minorUnit":{"type":"integer","description":"Digits after the decimal point; amounts are integers in this minor unit."},"symbol":{"type":"string"}},"required":["code","minorUnit","symbol"]},"locales":{"type":"array","items":{"type":"string"}},"defaultLocale":{"type":"string"},"phone":{"type":"object","properties":{"countryCode":{"type":"string","example":"233"},"nationalLength":{"type":"integer"},"trunkPrefix":{"type":["string","null"]},"example":{"type":"string"}},"required":["countryCode","nationalLength","example"]},"identityDocuments":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}},"required":["type","name"]}},"address":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"string"}},"postcode":{"oneOf":[{"type":"object","properties":{"name":{"type":"string"},"required":{"type":"boolean"}},"required":["name","required"]},{"type":"null"}]}},"required":["fields"]},"support":{"type":"object","properties":{"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"whatsapp":{"type":["string","null"]},"hours":{"type":["string","null"]}}},"products":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCode"},"description":"Products sold in the market."}},"required":["code","name","status","timezone","currency","locales","defaultLocale","phone","products"],"description":"A live market. Cross-border shipping is not offered: origin, destination and Business are always in one market."},"Location":{"type":"object","properties":{"public_code":{"type":"string","description":"Stable code to send as originLocationCode / destinationLocationCode."},"type":{"type":"string","enum":["DROPOFF_POINT","PICKUP_POINT","COMBINED_POINT","LOCKER_SITE"]},"name":{"type":"string"},"market":{"$ref":"#/components/schemas/MarketCode"},"address":{"$ref":"#/components/schemas/Address"},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"hours":{"type":"object","properties":{},"description":"Weekly opening hours as published.","additionalProperties":true},"capabilities":{"type":"array","items":{"type":"string"}}},"required":["public_code","type","name"]},"LocationDetail":{"type":"object","properties":{"public_code":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["DROPOFF_POINT","PICKUP_POINT","COMBINED_POINT","LOCKER_SITE"]},"market":{"$ref":"#/components/schemas/MarketCode"},"address":{"$ref":"#/components/schemas/Address"},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"hours":{},"open":{"$ref":"#/components/schemas/OpenState"},"space":{"$ref":"#/components/schemas/Space"},"services":{"type":"object","properties":{"pickup":{"type":"boolean","description":"Receivers can collect here."},"dropoff":{"type":"boolean","description":"Senders can drop off here."}},"required":["pickup","dropoff"]},"accepts":{"type":"object","properties":{"parcels":{"type":"boolean","description":"Taking new parcels for collection now."},"dropoffs":{"type":"boolean","description":"Taking drop-offs now."}},"required":["parcels","dropoffs"]},"limits":{"type":"object","properties":{"maxWeightGrams":{"type":["integer","null"]},"maxLengthMm":{"type":["integer","null"]},"maxWidthMm":{"type":["integer","null"]},"maxHeightMm":{"type":["integer","null"]}}},"relay":{"type":"object","properties":{"covered":{"type":"boolean","description":"Inside an active Relay zone."},"hubServed":{"type":"boolean","description":"That zone has an active hub."}},"required":["covered","hubServed"]},"upcomingClosures":{"type":"array","items":{"$ref":"#/components/schemas/Closure"}}},"required":["public_code","name","type","open","space","services","accepts","limits","relay","upcomingClosures"]},"RankedPoint":{"type":"object","properties":{"rank":{"type":"integer"},"public_code":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"},"latitude":{"type":"number"},"longitude":{"type":"number"},"distanceMeters":{"type":"number"},"hours":{},"open":{"$ref":"#/components/schemas/OpenState"},"space":{"$ref":"#/components/schemas/Space"},"accepts":{"type":"object","properties":{"parcels":{"type":"boolean"},"dropoffs":{"type":"boolean"}}},"upcomingClosures":{"type":"array","items":{"$ref":"#/components/schemas/Closure"}},"score":{"type":"object","properties":{"total":{"type":"number"},"components":{"type":"object","properties":{},"additionalProperties":{"type":"number"}}},"required":["total"]}},"required":["rank","public_code","name","type","distanceMeters","open","space","score"]},"ExcludedPoint":{"type":"object","properties":{"public_code":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"distanceMeters":{"type":"number"},"reason":{"$ref":"#/components/schemas/Reason"}},"required":["public_code","reason"]},"PointSearch":{"type":"object","properties":{"query":{"type":"object","properties":{},"additionalProperties":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/RankedPoint"}},"excluded":{"type":"array","items":{"$ref":"#/components/schemas/ExcludedPoint"}},"totalEligible":{"type":"integer"},"scoring":{"type":"object","properties":{"version":{"type":"string"},"weights":{"type":"object","properties":{},"additionalProperties":{"type":"number"}},"note":{"type":"string"}}},"generatedAt":{"type":"string","format":"date-time"},"geocoded":{"type":"object","properties":{"text":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"],"description":"NB16: present when you searched by address; the position used."}},"required":["results","excluded","totalEligible","scoring","generatedAt"]},"Contact":{"type":"object","properties":{"name":{"type":"string","maxLength":160},"phone":{"type":"string","description":"Phone number in the market format (Ghana: 024 123 4567 or 233241234567).","pattern":"^\\+?[0-9 ()-]{8,24}$"},"email":{"type":"string","format":"email"}},"required":["name","phone"]},"Measurements":{"type":"object","properties":{"actualWeightGrams":{"type":"integer","minimum":1},"lengthMm":{"type":"integer","minimum":1},"widthMm":{"type":"integer","minimum":1},"heightMm":{"type":"integer","minimum":1}},"required":["actualWeightGrams","lengthMm","widthMm","heightMm"]},"QuoteRequest":{"type":"object","properties":{"market":{"$ref":"#/components/schemas/MarketCode"},"service":{"type":"string","enum":["EXPRESS","RELAY"]},"serviceVariant":{"type":"string","description":"Relay: POINT_TO_POINT or POINT_TO_LOCKER. Express: STANDARD or PRIORITY."},"serviceCode":{"$ref":"#/components/schemas/ServiceCode"},"measurements":{"$ref":"#/components/schemas/Measurements"},"originLocationCode":{"type":"string","description":"Relay drop-off point."},"destinationLocationCode":{"type":"string","description":"Relay pickup point or locker."},"fallbackLocationCode":{"type":"string","description":"Relay Home: the fallback Qoene Point used if the one home attempt fails. Omit it and Qoene picks the nearest suitable point."},"originAddressText":{"type":"string","description":"Express pickup address."},"destinationAddressText":{"type":"string","description":"Express or Relay Home delivery address."},"destinationPlaceId":{"type":"string"},"deliveryInstructions":{"type":"string","maxLength":500},"requestedPickupAt":{"type":"string","description":"Express pickup time; for Relay the planned drop-off time. 30 minutes to 14 days ahead; default now.","format":"date-time"},"payOnPickup":{"type":"boolean"},"promotionCode":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,32}$"}},"description":"Same fields as the signed-in quote. Unknown or expired promotion codes return 422."},"Quote":{"type":"object","properties":{"public_id":{"type":"string","description":"Quote ID","pattern":"^(?:QD-QT-[A-F0-9]{24}|QDQT[A-Z0-9]{3,32})$","example":"QD-QT-0123456789ABCDEF01234567"},"service":{"type":"string","enum":["EXPRESS","RELAY"]},"service_variant":{"type":["string","null"]},"service_code":{"oneOf":[{"$ref":"#/components/schemas/ServiceCode"},{"type":"null"}]},"currency":{"type":"string","description":"The market currency; amounts are in its minor unit.","example":"GHS"},"market":{"$ref":"#/components/schemas/MarketCode"},"subtotal_minor":{"$ref":"#/components/schemas/MinorAmount"},"tax_minor":{"$ref":"#/components/schemas/MinorAmount"},"total_minor":{"$ref":"#/components/schemas/MinorAmount"},"expires_at":{"type":"string","format":"date-time"},"price":{"type":"object","properties":{"components":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}},"taxComponents":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}}},"description":"Price lines; components sum to subtotal_minor.","additionalProperties":true},"route":{"type":"object","properties":{},"description":"Route details used for the price.","additionalProperties":true},"promise":{"$ref":"#/components/schemas/DeliveryPromise"},"contract":{"type":"object","properties":{},"description":"NB10 contract terms frozen with the quote.","additionalProperties":true},"rateCard":{"type":"object","properties":{},"additionalProperties":true},"volumeTier":{}},"required":["public_id","service","currency","subtotal_minor","tax_minor","total_minor","expires_at"]},"QuoteOptionsRequest":{"type":"object","properties":{"market":{"$ref":"#/components/schemas/MarketCode"},"serviceCodes":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCode"},"description":"Narrow the products to price (default: all). Do not send service, serviceVariant or serviceCode here.","minItems":1,"uniqueItems":true},"measurements":{"$ref":"#/components/schemas/Measurements"},"originLocationCode":{"type":"string","description":"Relay drop-off point."},"destinationLocationCode":{"type":"string","description":"Relay pickup point or locker."},"fallbackLocationCode":{"type":"string","description":"Relay Home fallback point (default: the nearest suitable Qoene Point, returned as homeFallbackSuggestion)."},"originAddressText":{"type":"string","description":"Express pickup address."},"destinationAddressText":{"type":"string","description":"Express or Relay Home delivery address. For Relay Home from a drop-off point, send it with originLocationCode and no origin address."},"originPlaceId":{"type":"string"},"destinationPlaceId":{"type":"string"},"requestedPickupAt":{"type":"string","description":"Express pickup time; for Relay the planned drop-off time. 30 minutes to 14 days ahead; default now.","format":"date-time"},"payOnPickup":{"type":"boolean"},"pickupInstructions":{"type":"string","maxLength":500},"deliveryInstructions":{"type":"string","maxLength":500},"promotionCode":{"type":"string","pattern":"^[A-Za-z0-9_-]{3,32}$"}},"required":["measurements"],"description":"Every product that can serve this parcel and route is priced; the others come back in `excluded` with a reason."},"QuoteResult":{"type":"object","properties":{"quote":{"$ref":"#/components/schemas/Quote"},"replayed":{"type":"boolean"},"environment":{"$ref":"#/components/schemas/Environment"},"simulated":{"type":"boolean"}},"required":["quote","replayed","environment","simulated"]},"QuoteOptionsResult":{"type":"object","properties":{"offerGroupId":{"type":["string","null"]},"market":{"$ref":"#/components/schemas/MarketCode"},"offers":{"type":"array","items":{"type":"object","properties":{"serviceCode":{"$ref":"#/components/schemas/ServiceCode"},"quote":{"$ref":"#/components/schemas/Quote"}},"required":["serviceCode","quote"]}},"excluded":{"type":"array","items":{"type":"object","properties":{"serviceCode":{"$ref":"#/components/schemas/ServiceCode"},"reason":{"$ref":"#/components/schemas/Reason"}},"required":["serviceCode","reason"]}},"replayed":{"type":"boolean"},"environment":{"$ref":"#/components/schemas/Environment"},"simulated":{"type":"boolean"}},"required":["offers","excluded","replayed","environment"]},"Declaration":{"type":"object","properties":{"accepted":{"type":"boolean","const":true},"version":{"type":"string","description":"The current prohibited-items declaration version."}},"required":["accepted","version"]},"BookingRequest":{"type":"object","properties":{"quoteId":{"type":"string","description":"Quote ID","pattern":"^(?:QD-QT-[A-F0-9]{24}|QDQT[A-Z0-9]{3,32})$","example":"QD-QT-0123456789ABCDEF01234567"},"description":{"type":"string","minLength":3,"maxLength":500},"sender":{"$ref":"#/components/schemas/Contact"},"receiver":{"$ref":"#/components/schemas/Contact"},"paymentMode":{"type":"string","enum":["PREPAID","PAY_ON_PICKUP","BUSINESS_INVOICE","BUSINESS_WALLET"]},"orderReference":{"type":"string","description":"Business order reference, unique per Business.","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/ -]{2,99}$"},"prohibitedItemsDeclaration":{"$ref":"#/components/schemas/Declaration"},"checkoutSelection":{"type":"string","description":"NB15: the signed selection token from the checkout widget, in place of quoteId. Verified and used once; the quote, price and point come from it, and the checkout session's order reference is used when orderReference is not sent.","maxLength":8000}},"required":["description","sender","receiver","prohibitedItemsDeclaration"],"description":"Send `quoteId` (a quote from POST /quotes or /quotes/options) or `checkoutSelection` (a checkout widget token).","anyOf":[{"required":["quoteId"]},{"required":["checkoutSelection"]}]},"BookedShipment":{"type":"object","properties":{"public_id":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"},"tracking_number":{"type":"string"},"service":{"type":"string","enum":["EXPRESS","RELAY"]},"status":{"type":"string"},"amount_due_minor":{"$ref":"#/components/schemas/MinorAmount"},"merchant_reference":{"type":["string","null"]},"payment_obligation_public_id":{"type":["string","null"]}},"required":["public_id","tracking_number","status"]},"BookingResult":{"type":"object","properties":{"shipment":{"$ref":"#/components/schemas/BookedShipment"},"replayed":{"type":"boolean"},"simulated":{"type":"boolean"},"environment":{"$ref":"#/components/schemas/Environment"}},"required":["shipment","replayed","environment"]},"ReceiverChange":{"type":"object","properties":{"id":{"type":"string","description":"Receiver change ID","pattern":"^(?:QD-RCH-[A-F0-9]{24}|QDRCH[A-Z0-9]{3,31})$","example":"QD-RCH-0123456789ABCDEF01234567"},"kind":{"type":"string","enum":["DESTINATION_POINT","FALLBACK_POINT","HOLD_EXTENSION"],"description":"What the verified receiver changed."},"reason":{"type":"string","description":"Plain-language reason, also used for the promise revision."},"fromPointCode":{"type":["string","null"]},"toPointCode":{"type":["string","null"]},"toPointName":{"type":["string","null"]},"extensionHours":{"type":["integer","null"],"description":"Hours added to the hold (HOLD_EXTENSION)."},"amountMinor":{"type":"integer","description":"What the receiver paid for the change, in pesewas (0 when free)."},"appliedAt":{"type":"string","format":"date-time"}},"required":["id","kind","reason","appliedAt"]},"Overstay":{"type":"object","properties":{"pointType":{"type":"string","enum":["POINT","LOCKER"]},"engine":{"type":"string","enum":["HOLD_RULES","LOCKER_TARIFF"],"description":"HOLD_RULES: NB26 hold terms frozen with the booking. LOCKER_TARIFF: an earlier locker booking keeps its frozen locker tariff."},"readyAt":{"type":["string","null"],"format":"date-time"},"holdEndsAt":{"type":["string","null"],"description":"End of the free (or sender-prepaid, or extended) hold.","format":"date-time"},"chargeStartsAt":{"type":["string","null"],"description":"Overstay starts after the grace period.","format":"date-time"},"returnDueAt":{"type":["string","null"],"description":"The parcel returns to the sender after this time.","format":"date-time"},"started":{"type":"boolean"},"days":{"type":"integer"},"ratePerDayMinor":{"type":"integer"},"capMinor":{"type":["integer","null"]},"totalMinor":{"type":"integer","description":"Overstay through now (or the frozen moment)."},"assessedMinor":{"type":"integer"},"dueNowMinor":{"type":"integer","description":"Still to pay before the locker opens or the point releases."},"unpaidMinor":{"type":"integer"},"frozenUntil":{"type":["string","null"],"description":"The amount is frozen until this time while the receiver pays.","format":"date-time"},"paymentState":{"type":"string","enum":["NONE","DUE","PENDING","UNCLEAR","PAID"],"description":"UNCLEAR: the payment is being reconciled; the parcel stays put."},"obligations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"chargedTo":{"type":"string","enum":["RECEIVER","BUSINESS_WALLET"]},"amountMinor":{"type":"integer"},"status":{"type":"string"},"attempt":{"oneOf":[{"type":"object","properties":{"publicId":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"}}},{"type":"null"}]}},"required":["id","chargedTo","amountMinor","status"]}},"holdRuleVersion":{"type":"string"},"extensionHours":{"type":"integer"}},"required":["pointType","engine","started","totalMinor","dueNowMinor","paymentState"],"description":"Receivers pay overstay by Mobile Money at pickup; a contract that covers overstay pays from the Business wallet up to its limit."},"Shipment":{"type":"object","properties":{"public_id":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"},"tracking_number":{"type":"string"},"merchant_reference":{"type":["string","null"]},"service":{"type":"string","enum":["EXPRESS","RELAY"]},"service_variant":{"type":["string","null"]},"status":{"type":"string","description":"Detailed internal status. Prefer milestones for buyers."},"amount_due_minor":{"$ref":"#/components/schemas/MinorAmount"},"currency":{"type":"string"},"market":{"$ref":"#/components/schemas/MarketCode"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"simulated":{"type":"boolean"},"promise":{"oneOf":[{"$ref":"#/components/schemas/ShipmentPromise"},{"type":"null"}]},"receiverChanges":{"type":"array","items":{"$ref":"#/components/schemas/ReceiverChange"},"description":"Changes the verified receiver made, newest first (NB26)."},"overstay":{"oneOf":[{"$ref":"#/components/schemas/Overstay"},{"type":"null"}]}},"required":["public_id","tracking_number","service","status","created_at","simulated"]},"ShipmentListItem":{"type":"object","properties":{"public_id":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"},"tracking_number":{"type":"string"},"merchant_reference":{"type":["string","null"]},"service":{"type":"string","enum":["EXPRESS","RELAY"]},"service_variant":{"type":["string","null"]},"service_code":{"oneOf":[{"$ref":"#/components/schemas/ServiceCode"},{"type":"null"}]},"status":{"type":"string"},"milestone":{"type":"string","description":"Current milestone code (see Tracking milestones)."},"view_mode":{"type":"string","enum":["IN_TRANSIT","OUT_FOR_DELIVERY","READY_AT_POINT","READY_IN_LOCKER","DELIVERED","EXCEPTION","RETURNING"]},"amount_due_minor":{"type":["integer","null"]},"currency":{"type":"string"},"market":{"$ref":"#/components/schemas/MarketCode"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"store_id":{"type":["string","null"],"description":"Store of the commerce order this parcel was shipped for."},"order_id":{"type":["string","null"],"description":"Commerce order ID."},"simulated":{"type":"boolean"}},"required":["public_id","tracking_number","service","status","milestone","view_mode","created_at","simulated"]},"MilestoneStep":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"state":{"type":"string","enum":["done","current","upcoming"]},"at":{"type":["string","null"],"format":"date-time"}},"required":["code","label","state"]},"Tracking":{"type":"object","properties":{"shipmentId":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"},"trackingNumber":{"type":"string"},"service":{"type":"string","enum":["EXPRESS","RELAY"]},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"simulated":{"type":"boolean"},"events":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"at":{"type":"string","format":"date-time"}},"required":["status","at"]}},"serviceCode":{"$ref":"#/components/schemas/ServiceCode"},"milestone":{"type":"string"},"milestoneLabel":{"type":"string"},"viewMode":{"type":"string","enum":["IN_TRANSIT","OUT_FOR_DELIVERY","READY_AT_POINT","READY_IN_LOCKER","DELIVERED","EXCEPTION","RETURNING"]},"milestones":{"type":"array","items":{"$ref":"#/components/schemas/MilestoneStep"}},"exception":{"oneOf":[{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"nextSteps":{"type":"string"},"at":{"type":["string","null"],"format":"date-time"}},"required":["code"]},{"type":"null"}]},"returnTrack":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/MilestoneStep"}},{"type":"null"}]},"promise":{"oneOf":[{"$ref":"#/components/schemas/ShipmentPromise"},{"type":"null"}]},"receiverChanges":{"type":"array","items":{"$ref":"#/components/schemas/ReceiverChange"}},"overstay":{"oneOf":[{"$ref":"#/components/schemas/Overstay"},{"type":"null"}]}},"required":["shipmentId","trackingNumber","status","events","milestone","viewMode","milestones"]},"CancelResult":{"type":"object","properties":{"shipment":{"type":"object","properties":{"public_id":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"},"tracking_number":{"type":"string"},"status":{"type":"string"}},"required":["public_id","status"]},"replayed":{"type":"boolean"},"simulated":{"type":"boolean"}},"required":["shipment","replayed","simulated"]},"PaymentIntent":{"type":"object","properties":{"public_id":{"type":"string","description":"LIVE QDMPI or QD-MPI-. TEST QDTPI or QD-TPI-.","pattern":"^(?:QD-MPI-[A-F0-9]{24}|QDMPI[A-Z0-9]{3,31}|QD-TPI-[A-F0-9]{24}|QDTPI[A-Z0-9]{3,31})$"},"shipment_id":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"},"obligation_id":{"type":"string"},"amount_minor":{"$ref":"#/components/schemas/MinorAmount"},"paid_minor":{"$ref":"#/components/schemas/MinorAmount"},"refunded_minor":{"$ref":"#/components/schemas/MinorAmount"},"net_paid_minor":{"$ref":"#/components/schemas/MinorAmount"},"currency":{"type":"string"},"status":{"type":"string","enum":["REQUIRES_APPROVAL","PENDING","RECONCILIATION_REQUIRED","PAID","CANCELLED","SIMULATED"],"description":"PENDING and RECONCILIATION_REQUIRED do not mean paid."},"latest_attempt":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"}}},{"type":"null"}]},"approval_url":{"type":["string","null"],"description":"Send to an authorized Business member, never to the receiver."},"created_at":{"type":"string","format":"date-time"},"simulated":{"type":"boolean"}},"required":["public_id","shipment_id","amount_minor","status","simulated"]},"PaymentIntentResult":{"type":"object","properties":{"intent":{"$ref":"#/components/schemas/PaymentIntent"},"replayed":{"type":"boolean"}},"required":["intent","replayed"]},"LabelResult":{"type":"object","properties":{"label":{"type":"object","properties":{"public_id":{"type":"string","description":"Label ID","pattern":"^(?:QD-LBL-[A-F0-9]{24}|QDLBL[A-Z0-9]{3,31})$"},"version_number":{"type":"integer"}},"required":["public_id","version_number"]},"replayed":{"type":"boolean"}},"required":["label","replayed"]},"Manifest":{"type":"object","properties":{"public_id":{"type":"string"},"status":{"type":"string"},"kind":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"issued_at":{"type":["string","null"],"format":"date-time"},"shipment_count":{"type":"integer"},"shipments":{"type":"array","items":{"type":"object","properties":{"public_id":{"type":"string"},"tracking_number":{"type":"string"},"service":{"type":"string"},"status":{"type":"string"}}}}},"required":["public_id","status","shipment_count","shipments"]},"OrderItem":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"sku":{"type":"string","maxLength":64},"quantity":{"type":"integer","minimum":1,"maximum":10000},"unitPriceMinor":{"type":"integer","minimum":0}},"required":["name"]},"OrderInput":{"type":"object","properties":{"externalOrderId":{"type":"string","description":"Your order number; unique per store, case-insensitive.","pattern":"^#?[A-Za-z0-9][A-Za-z0-9._:/ -]{0,63}$"},"receiver":{"$ref":"#/components/schemas/Contact"},"buyer":{"$ref":"#/components/schemas/Contact"},"serviceCode":{"$ref":"#/components/schemas/ServiceCode"},"destinationPointCode":{"type":"string","description":"Relay Point / Relay Locker: the buyer's chosen point code."},"destinationAddress":{"type":"object","properties":{"text":{"type":"string","minLength":5,"maxLength":300},"placeId":{"type":"string"}},"required":["text"],"description":"Express and Relay Home: delivery address."},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"},"maxItems":100},"description":{"type":"string","minLength":3,"maxLength":500},"parcel":{"$ref":"#/components/schemas/Measurements"},"orderTotalMinor":{"type":"integer","description":"Order value in pesewas (information only).","minimum":0},"currency":{"type":"string","const":"GHS"},"storePaymentState":{"type":"string","enum":["PAID","PENDING","CASH_ON_DELIVERY","REFUNDED","UNKNOWN"]},"placedAt":{"type":"string","format":"date-time"}},"required":["externalOrderId","receiver","serviceCode"]},"OrderCreateRequest":{"allOf":[{"type":"object","properties":{"storeId":{"type":"string","description":"Store public ID (QD-STR-…). The store must be bound to this key's API client."},"checkoutSelection":{"type":"string","description":"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.","maxLength":8000}},"required":["storeId"]},{"$ref":"#/components/schemas/OrderInput"}]},"Order":{"type":"object","properties":{"public_id":{"type":"string","description":"Commerce order ID","pattern":"^(?:QD-ORD-[A-F0-9]{24}|QDORD[A-Z0-9]{3,31})$","example":"QD-ORD-0123456789ABCDEF01234567"},"external_order_id":{"type":"string"},"order_reference":{"type":"string","description":"<store prefix>-<external order ID>; becomes the shipment's merchant_reference."},"source":{"type":"string","enum":["MANUAL","CSV","API","WOOCOMMERCE"]},"buyer_contact":{"$ref":"#/components/schemas/Contact"},"receiver_contact":{"$ref":"#/components/schemas/Contact"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"description":{"type":["string","null"]},"parcel":{"oneOf":[{"$ref":"#/components/schemas/Measurements"},{"type":"null"}]},"service_code":{"$ref":"#/components/schemas/ServiceCode"},"destination_point_code":{"type":["string","null"]},"destination_address":{"oneOf":[{"type":"object","properties":{"text":{"type":"string"},"placeId":{"type":"string"}}},{"type":"null"}]},"order_total_minor":{"oneOf":[{"$ref":"#/components/schemas/MinorAmount"},{"type":"null"}]},"currency":{"type":"string"},"store_payment_state":{"type":"string"},"status":{"type":"string","enum":["AWAITING_SHIPMENT","SHIPMENT_CREATED","FAILED","CANCELLED"]},"failure_code":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"placed_at":{"type":["string","null"],"format":"date-time"},"version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"shipped_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"cancel_reason":{"type":["string","null"]},"api_environment":{"oneOf":[{"$ref":"#/components/schemas/Environment"},{"type":"null"}]},"store":{"type":"object","properties":{"public_id":{"type":"string"},"name":{"type":"string"},"platform":{"type":"string"}},"required":["public_id"]},"shipment":{"oneOf":[{"type":"object","properties":{"public_id":{"type":"string"},"tracking_number":{"type":"string"},"status":{"type":"string"}},"required":["public_id"]},{"type":"null"}]},"queued_job":{"type":["string","null"],"description":"Ship run currently shipping this order."},"checkout_selection_id":{"type":["string","null"],"description":"NB16: the checkout selection (QD-SEL-…) attached when the order was created; null after an edit changed the product, destination or parcel."},"ship_attempts":{"type":"array","items":{"type":"object","properties":{"job_public_id":{"type":"string"},"status":{"type":"string"},"failure_code":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"tracking_number":{"type":["string","null"]}}},"description":"Detail only: the latest 20 ship attempts."}},"required":["public_id","external_order_id","order_reference","status","service_code","store","created_at"]},"OrderCreateResult":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"},"replayed":{"type":"boolean","description":"True when this store already had the same order."},"environment":{"$ref":"#/components/schemas/Environment"}},"required":["order","replayed"]},"OrderList":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"counts":{"type":"object","properties":{"AWAITING_SHIPMENT":{"type":"integer"},"SHIPMENT_CREATED":{"type":"integer"},"FAILED":{"type":"integer"},"CANCELLED":{"type":"integer"}}},"nextCursor":{"type":["string","null"]}},"required":["orders","counts","nextCursor"]},"ShipRequest":{"type":"object","properties":{"paymentMode":{"type":"string","enum":["PREPAID","PAY_ON_PICKUP","BUSINESS_INVOICE","BUSINESS_WALLET"],"description":"BUSINESS_WALLET also needs the wallet.spend scope."},"originPointCode":{"type":"string","description":"Relay drop-off point; defaults to the store's usual point."},"originAddressText":{"type":"string","description":"Express pickup address; defaults to the store's."},"pickupAt":{"type":"string","format":"date-time"},"prohibitedItemsDeclaration":{"$ref":"#/components/schemas/Declaration"}},"required":["paymentMode","prohibitedItemsDeclaration"]},"ShipJobsRequest":{"allOf":[{"type":"object","properties":{"orderIds":{"type":"array","items":{"type":"string","description":"Commerce order ID","pattern":"^(?:QD-ORD-[A-F0-9]{24}|QDORD[A-Z0-9]{3,31})$","example":"QD-ORD-0123456789ABCDEF01234567"},"minItems":1,"maxItems":100,"uniqueItems":true}},"required":["orderIds"]},{"$ref":"#/components/schemas/ShipRequest"}]},"ShipJob":{"type":"object","properties":{"public_id":{"type":"string","description":"Ship run ID","pattern":"^(?:QD-SHJ-[A-F0-9]{24}|QDSHJ[A-Z0-9]{3,31})$","example":"QD-SHJ-0123456789ABCDEF01234567"},"status":{"type":"string","enum":["QUEUED","RUNNING","COMPLETED"]},"options":{"type":"object","properties":{},"additionalProperties":true},"declaration_version":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"retry_of_job_public_id":{"type":["string","null"]},"requested_by_api_client_id":{"type":["string","null"]},"requested_by_api_client_name":{"type":["string","null"]},"total_count":{"type":"integer"},"queued_count":{"type":"integer"},"processing_count":{"type":"integer"},"created_count":{"type":"integer"},"failed_count":{"type":"integer"},"skipped_count":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"status":{"type":"string","enum":["QUEUED","PROCESSING","CREATED","FAILED","SKIPPED"]},"order_public_id":{"type":"string"},"external_order_id":{"type":"string"},"order_reference":{"type":"string"},"shipment_public_id":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"amount_minor":{"oneOf":[{"$ref":"#/components/schemas/MinorAmount"},{"type":"null"}]},"label_status":{"type":["string","null"],"description":"ISSUED, or AWAITING_PAYMENT for a prepaid parcel."},"label_public_id":{"type":["string","null"]},"failure_code":{"type":["string","null"]},"failure_reason":{"type":["string","null"]}},"required":["position","status","order_public_id"]},"description":"Detail only: one result per order."}},"required":["public_id","status","total_count"]},"ShipJobResult":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/ShipJob"},"replayed":{"type":"boolean"}},"required":["job","replayed"]},"WebhookEventName":{"type":"string","enum":["shipment.created","shipment.status_changed","shipment.driver_assigned","shipment.driver_arriving","shipment.dropoff_accepted","shipment.picked_up","shipment.in_transit","shipment.received_at_hub","shipment.arrived_at_pickup","shipment.ready_for_pickup","shipment.ready_in_locker","shipment.delivered","shipment.collected","shipment.pickup_failed","shipment.delivery_attempt_failed","shipment.exception","shipment.return_requested","shipment.return_started","shipment.return_at_origin","shipment.returned","shipment.cancelled","payment.confirmed","payment.failed","refund.processed","locker.overage_due","shipment.out_for_delivery","shipment.pickup_expiring","order.created","order.shipped","order.failed","shipment.promise_revised","shipment.promise_missed","claim.submitted","claim.under_review","claim.approved","claim.partly_approved","claim.rejected","claim.paid","claim.withdrawn","return.requested","return.approved","return.rejected","return.cancelled","return.expired","return.dropped_off","return.in_transit","return.arrived","return.received","return.inspected","return.refund_recorded","shipment.home_attempt_failed","shipment.redirected_to_point","shipment.receiver_changed","shipment.overstay_started","shipment.overstay_paid"]},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"subscribed_events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventName"}},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"delivery_health":{"type":"object","properties":{"recentDeliveries":{"type":"integer"},"recentSucceeded":{"type":"integer"},"recentFailed":{"type":"integer"},"unresolved":{"type":"integer"},"overdue":{"type":"integer"},"failedTotal":{"type":"integer"},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"}}}},"required":["id","url","subscribed_events","is_active"]},"WebhookEndpointList":{"type":"object","properties":{"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"supportedEvents":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventName"}},"reservedEvents":{"type":"array","items":{"type":"string"}}},"required":["endpoints","supportedEvents"]},"WebhookEndpointCreateRequest":{"type":"object","properties":{"url":{"type":"string","description":"Public HTTPS URL on port 443.","format":"uri","maxLength":2048},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventName"},"minItems":1,"uniqueItems":true}},"required":["url","events"]},"WebhookEndpointCreated":{"type":"object","properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"secret":{"type":"string","description":"whsec_ signing secret. Shown only in this response; store it server-side.","pattern":"^whsec_[a-f0-9]{64}$"}},"required":["endpoint","secret"]},"WebhookTestDelivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"event_id":{"type":"string","description":"The X-Qoene-Event-Id of the test event."}},"required":["id","status"]},"WebhookShipment":{"type":"object","properties":{"id":{"type":"string","description":"LIVE shipments use QDSHP or QD-SHP-. TEST shipments use QDTST or QD-TST-.","pattern":"^(?:QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31}|QD-TST-[A-F0-9]{24}|QDTST[A-Z0-9]{3,31})$","example":"QD-SHP-0123456789ABCDEF01234567"},"tracking_number":{"type":"string"},"service":{"type":"string","enum":["EXPRESS","RELAY"]},"status":{"type":"string"},"milestone":{"type":"string","description":"Present on events queued from NB07 onward."},"view_mode":{"type":"string"}},"required":["id","tracking_number","service","status"]},"WebhookShipmentEvent":{"type":"object","properties":{"id":{"type":"string","description":"Stable event ID; deduplicate on it.","format":"uuid"},"type":{"$ref":"#/components/schemas/WebhookEventName"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"shipment":{"$ref":"#/components/schemas/WebhookShipment"},"pickup":{"type":"object","properties":{"expires_at":{"type":"string","format":"date-time"},"location_type":{"type":"string","enum":["POINT","LOCKER"]}},"required":["expires_at","location_type"],"description":"Only on shipment.pickup_expiring."},"promise":{"$ref":"#/components/schemas/WebhookPromise"},"home_delivery":{"type":"object","properties":{"attempt_reason":{"type":"string","description":"Why the one home attempt failed.","example":"RECEIVER_ABSENT"},"fallback_point_code":{"type":"string","description":"The fallback Qoene Point chosen at booking."},"fallback_point_name":{"type":"string"},"route":{"type":"string","enum":["CARRY_TO_POINT","RETURN_TO_HUB"],"description":"How the parcel reaches the point: carried there by the rider the same day, or back through the hub."}},"description":"Only on shipment.home_attempt_failed and shipment.redirected_to_point (Relay Home)."},"receiver_change":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["DESTINATION_POINT","FALLBACK_POINT","HOLD_EXTENSION"]},"reason":{"type":"string"},"from_point_code":{"type":"string"},"to_point_code":{"type":"string"},"to_point_name":{"type":"string"},"extension_hours":{"type":"integer"},"hold_ends_at":{"type":"string","format":"date-time"},"amount_minor":{"type":"integer"}},"required":["id","kind"],"description":"Only on shipment.receiver_changed."},"overstay":{"type":"object","properties":{"hold_ended_at":{"type":"string","format":"date-time"},"location_type":{"type":"string","enum":["POINT","LOCKER"]},"rate_per_day_minor":{"type":"integer"},"cap_minor":{"type":["integer","null"]},"return_after":{"type":"string","format":"date-time"},"amount_minor":{"type":"integer"},"paid_by":{"type":"string","enum":["RECEIVER","BUSINESS","SPLIT"]},"business_covered_minor":{"type":"integer"},"receiver_paid_minor":{"type":"integer"}},"description":"Only on shipment.overstay_started and shipment.overstay_paid."}},"required":["shipment"]}},"required":["id","type","created_at","data"],"description":"Body for shipment.*, payment.*, refund.processed and locker.overage_due. No names, phones, addresses, codes or proof."},"WebhookOrderEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["order.created","order.shipped","order.failed"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","description":"Commerce order ID","pattern":"^(?:QD-ORD-[A-F0-9]{24}|QDORD[A-Z0-9]{3,31})$","example":"QD-ORD-0123456789ABCDEF01234567"},"external_order_id":{"type":"string"},"order_reference":{"type":"string"},"store_id":{"type":"string","description":"Store ID","pattern":"^(?:QD-STR-[A-F0-9]{24}|QDSTR[A-Z0-9]{3,31})$","example":"QD-STR-0123456789ABCDEF01234567"},"source":{"type":"string"},"service_code":{"$ref":"#/components/schemas/ServiceCode"},"status":{"type":"string"},"shipment":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"}},"required":["id","tracking_number"]},{"type":"null"}]},"failure":{"oneOf":[{"type":"object","properties":{"code":{"type":["string","null"]},"message":{"type":["string","null"]}}},{"type":"null"}]},"ship_job_id":{"type":["string","null"]}},"required":["id","external_order_id","order_reference","store_id","status"]}},"required":["order"]}},"required":["id","type","created_at","data"],"description":"Body for order.* events. No buyer or receiver details. Orders created with a TEST key send no events."},"WebhookTestEvent":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"webhook.test"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"business_id":{"type":"string"}},"required":["business_id"]}},"required":["id","type","created_at","data"]},"CheckoutSessionRequest":{"type":"object","properties":{"parcel":{"type":"object","properties":{"actualWeightGrams":{"type":"integer","minimum":1,"maximum":100000},"lengthMm":{"type":"integer","minimum":1,"maximum":5000},"widthMm":{"type":"integer","minimum":1,"maximum":5000},"heightMm":{"type":"integer","minimum":1,"maximum":5000}},"required":["actualWeightGrams","lengthMm","widthMm","heightMm"],"description":"The parcel as packed."},"origin":{"type":"object","properties":{"pointCode":{"type":"string","description":"Your drop-off Qoene Point (Relay products)."},"address":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":300},"latitude":{"type":"number"},"longitude":{"type":"number"},"placeId":{"type":"string","description":"From GET /checkout/places."}},"description":"Address text, a place, or coordinates."}},"description":"Where the parcel starts: a drop-off point for Relay and/or a pickup address for Express."},"serviceCodes":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCode"},"description":"Products to offer (default: all five). Products you cannot use are still shown as unavailable."},"payOnPickup":{"type":"boolean","description":"Price the Relay offers for payment when the receiver collects (default false)."},"orderReference":{"type":"string","description":"Your order reference; booked with the selection unless the booking sends its own.","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/ -]{2,99}$"},"expiresInMinutes":{"type":"integer","description":"Session lifetime (default 30).","minimum":5,"maximum":120},"requestedPickupAt":{"type":"string","description":"Planned pickup or drop-off time; the promise counts from it.","format":"date-time"},"prefill":{"type":"object","properties":{"addressText":{"type":"string","maxLength":300}},"description":"Shown in the widget's address field."}},"required":["parcel","origin"]},"CheckoutSession":{"type":"object","properties":{"id":{"type":"string","description":"Checkout session ID","pattern":"^(?:QD-CKS-[A-F0-9]{24}|QDCKS[A-Z0-9]{10,31})$","example":"QD-CKS-4B7E2A9C1F5D38E0A6C4B2F1"},"clientSecret":{"type":"string","description":"Give this to the widget in the buyer's browser. It only prices this session's parcel.","pattern":"^qd_cks_[a-f0-9]{64}$"},"environment":{"$ref":"#/components/schemas/Environment"},"expiresAt":{"type":"string","format":"date-time"},"serviceCodes":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCode"}},"parcel":{"type":"object","properties":{"actualWeightGrams":{"type":"integer","minimum":1,"maximum":100000},"lengthMm":{"type":"integer","minimum":1,"maximum":5000},"widthMm":{"type":"integer","minimum":1,"maximum":5000},"heightMm":{"type":"integer","minimum":1,"maximum":5000}},"required":["actualWeightGrams","lengthMm","widthMm","heightMm"],"description":"The parcel as packed."},"origin":{"type":"object","properties":{"pointCode":{"type":["string","null"]},"address":{"oneOf":[{"type":"object","properties":{"text":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"}}},{"type":"null"}]}}},"payOnPickup":{"type":"boolean"},"orderReference":{"type":["string","null"]},"prefill":{"oneOf":[{"type":"object","properties":{"addressText":{"type":["string","null"]}}},{"type":"null"}]}},"required":["id","clientSecret","environment","expiresAt","serviceCodes"]},"CheckoutSessionResult":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/CheckoutSession"},"replayed":{"type":"boolean"}},"required":["session","replayed"]},"CheckoutPoint":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"type":{"type":["string","null"]},"address":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"distanceMeters":{"type":["number","null"]},"open":{"type":["object","null"]},"space":{"type":["object","null"]},"hours":{"type":["object","null"]}},"required":["code","name"]},"CheckoutSelection":{"type":"object","properties":{"serviceCode":{"$ref":"#/components/schemas/ServiceCode"},"name":{"type":"string"},"brand":{"type":"string","enum":["EXPRESS","RELAY"]},"quoteId":{"type":"string","description":"Quote ID","pattern":"^(?:QD-QT-[A-F0-9]{24}|QDQT[A-Z0-9]{3,32})$","example":"QD-QT-0123456789ABCDEF01234567"},"currency":{"type":"string"},"totalMinor":{"type":"integer","description":"What Qoene charges you for this delivery, in pesewas."},"subtotalMinor":{"type":"integer"},"taxMinor":{"type":"integer"},"quoteExpiresAt":{"type":"string","description":"Book before this time.","format":"date-time"},"promise":{"oneOf":[{"type":"object","properties":{"summary":{"type":"string"},"promisedDate":{"type":["string","null"],"format":"date"},"promisedBy":{"type":"string","format":"date-time"}},"required":["promisedBy"]},{"type":"null"}]},"point":{"oneOf":[{"$ref":"#/components/schemas/CheckoutPoint"},{"type":"null"}]},"fallbackPoint":{"oneOf":[{"$ref":"#/components/schemas/CheckoutPoint"},{"type":"null"}]},"deliveryAddress":{"oneOf":[{"type":"object","properties":{"text":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]}}},{"type":"null"}]},"parcel":{"type":"object","properties":{"actualWeightGrams":{"type":"integer","minimum":1,"maximum":100000},"lengthMm":{"type":"integer","minimum":1,"maximum":5000},"widthMm":{"type":"integer","minimum":1,"maximum":5000},"heightMm":{"type":"integer","minimum":1,"maximum":5000}},"required":["actualWeightGrams","lengthMm","widthMm","heightMm"],"description":"The parcel as packed."},"payOnPickup":{"type":"boolean"}},"required":["serviceCode","quoteId","currency","totalMinor","promise","point","fallbackPoint","deliveryAddress"],"description":"What the buyer chose. Point and price come from Qoene, never from the browser."},"CheckoutSelectionVerifyRequest":{"type":"object","properties":{"token":{"type":"string","description":"The selection token from the widget.","maxLength":8000}},"required":["token"]},"CheckoutSelectionVerification":{"type":"object","properties":{"selectionId":{"type":"string","description":"Selection ID","pattern":"^(?:QD-SEL-[A-F0-9]{24}|QDSEL[A-Z0-9]{10,31})$"},"sessionId":{"type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"expiresAt":{"type":"string","format":"date-time"},"orderReference":{"type":["string","null"]},"embedOrigin":{"type":"string","description":"The page that showed the widget."},"selection":{"$ref":"#/components/schemas/CheckoutSelection"},"used":{"type":"boolean","description":"Already booked."},"shipmentId":{"type":["string","null"]}},"required":["selectionId","sessionId","environment","expiresAt","selection","used","shipmentId"]},"CheckoutJwks":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"kty":{"type":"string","const":"OKP"},"crv":{"type":"string","const":"Ed25519"},"x":{"type":"string"},"kid":{"type":"string"},"alg":{"type":"string","const":"EdDSA"},"use":{"type":"string","const":"sig"}},"required":["kty","crv","x","kid"]}}},"required":["keys"]},"CheckoutConfig":{"type":"object","properties":{"merchant":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"environment":{"$ref":"#/components/schemas/Environment"},"widgetVersion":{"type":"string"},"places":{"type":"boolean"},"session":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"serviceCodes":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCode"}},"prefill":{"type":["object","null"]},"parcel":{"type":"object","properties":{"actualWeightGrams":{"type":"integer","minimum":1,"maximum":100000},"lengthMm":{"type":"integer","minimum":1,"maximum":5000},"widthMm":{"type":"integer","minimum":1,"maximum":5000},"heightMm":{"type":"integer","minimum":1,"maximum":5000}},"required":["actualWeightGrams","lengthMm","widthMm","heightMm"],"description":"The parcel as packed."}}},{"type":"null"}]}},"required":["merchant","environment","places","session"]},"CheckoutOptionsRequest":{"type":"object","properties":{"destination":{"type":"object","properties":{"text":{"type":"string","minLength":3,"maxLength":300},"latitude":{"type":"number"},"longitude":{"type":"number"},"placeId":{"type":"string","description":"From GET /checkout/places."}},"description":"Address text, a place, or coordinates."},"pointCode":{"type":"string","description":"Buyer's chosen pickup point (Relay Point)."},"lockerCode":{"type":"string","description":"Buyer's chosen locker (Relay Locker)."},"fallbackPointCode":{"type":"string","description":"Buyer's chosen fallback point (Relay Home)."},"serviceCodes":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCode"},"description":"Narrow to these products."}},"required":["destination"]},"CheckoutOffer":{"type":"object","properties":{"serviceCode":{"$ref":"#/components/schemas/ServiceCode"},"name":{"type":"string"},"brand":{"type":"string"},"ending":{"type":"string"},"quoteId":{"type":"string","description":"Quote ID","pattern":"^(?:QD-QT-[A-F0-9]{24}|QDQT[A-Z0-9]{3,32})$","example":"QD-QT-0123456789ABCDEF01234567"},"currency":{"type":"string"},"totalMinor":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"promise":{"oneOf":[{"type":"object","properties":{"summary":{"type":"string"},"promisedDate":{"type":["string","null"]},"promisedBy":{"type":"string","format":"date-time"},"label":{"type":"string"}},"required":["promisedBy"]},{"type":"null"}]},"point":{"oneOf":[{"$ref":"#/components/schemas/CheckoutPoint"},{"type":"null"}]},"fallbackPoint":{"oneOf":[{"$ref":"#/components/schemas/CheckoutPoint"},{"type":"null"}]}},"required":["serviceCode","quoteId","totalMinor","currency","promise","point","fallbackPoint"]},"CheckoutOptions":{"type":"object","properties":{"sessionId":{"type":"string"},"environment":{"$ref":"#/components/schemas/Environment"},"destination":{"type":"object","properties":{"text":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"]},"offers":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutOffer"}},"excluded":{"type":"array","items":{"type":"object","properties":{"serviceCode":{"$ref":"#/components/schemas/ServiceCode"},"name":{"type":["string","null"]},"reason":{"$ref":"#/components/schemas/Reason"}},"required":["serviceCode","reason"]}}},"required":["sessionId","destination","offers","excluded"]},"CheckoutPoints":{"type":"object","properties":{"product":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/RankedPoint"}},"excluded":{"type":"array","items":{"$ref":"#/components/schemas/ExcludedPoint"}},"refusal":{"oneOf":[{"$ref":"#/components/schemas/Reason"},{"type":"null"}]},"generatedAt":{"type":"string","format":"date-time"}},"required":["product","results","excluded"]},"CheckoutPlaces":{"type":"object","properties":{"available":{"type":"boolean"},"suggestions":{"type":"array","items":{"type":"object","properties":{"placeId":{"type":"string"},"text":{"type":"string"}},"required":["placeId","text"]}}},"required":["available","suggestions"]},"CheckoutSelectionRequest":{"type":"object","properties":{"quoteId":{"type":"string","description":"Quote ID","pattern":"^(?:QD-QT-[A-F0-9]{24}|QDQT[A-Z0-9]{3,32})$","example":"QD-QT-0123456789ABCDEF01234567"},"destination":{"type":"object","properties":{"text":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]}}}},"required":["quoteId"]},"CheckoutSelectionIssued":{"type":"object","properties":{"token":{"type":"string","description":"Compact JWS (EdDSA). Send it to your server; never trust the decoded body without verifying."},"selectionId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"selection":{"$ref":"#/components/schemas/CheckoutSelection"}},"required":["token","selectionId","expiresAt","selection"]},"MarketList":{"type":"object","properties":{"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}},"required":["markets"]},"ServicesResult":{"type":"object","properties":{"market":{"$ref":"#/components/schemas/MarketCode"},"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"unavailable":{"type":"array","items":{"$ref":"#/components/schemas/ServiceUnavailable"}},"contract":{"oneOf":[{"$ref":"#/components/schemas/ContractSummary"},{"type":"null"}]},"generatedAt":{"type":"string","format":"date-time"}},"required":["services","unavailable","contract"]},"LocationList":{"type":"object","properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}},"required":["locations"]},"LocationDetailResult":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/LocationDetail"},"generatedAt":{"type":"string","format":"date-time"}},"required":["location"]},"ShipmentList":{"type":"object","properties":{"shipments":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentListItem"}},"nextCursor":{"type":["string","null"]},"environment":{"$ref":"#/components/schemas/Environment"}},"required":["shipments","nextCursor","environment"]},"ShipmentResult":{"type":"object","properties":{"shipment":{"$ref":"#/components/schemas/Shipment"}},"required":["shipment"]},"TrackingResult":{"type":"object","properties":{"tracking":{"$ref":"#/components/schemas/Tracking"}},"required":["tracking"]},"CancelRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":10,"maxLength":500}},"required":["reason"]},"PaymentIntentStatus":{"type":"object","properties":{"intent":{"$ref":"#/components/schemas/PaymentIntent"}},"required":["intent"]},"ManifestRequest":{"type":"object","properties":{"shipmentIds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100}},"required":["shipmentIds"]},"ManifestResult":{"type":"object","properties":{"manifest":{"$ref":"#/components/schemas/Manifest"},"replayed":{"type":"boolean"}},"required":["manifest","replayed"]},"ManifestStatus":{"type":"object","properties":{"manifest":{"$ref":"#/components/schemas/Manifest"}},"required":["manifest"]},"OrderResult":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}},"required":["order"]},"ShipJobStatus":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/ShipJob"}},"required":["job"]},"WebhookEndpointDisabled":{"type":"object","properties":{"endpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"is_active":{"type":"boolean"}},"required":["id","is_active"]}},"required":["endpoint"]},"WebhookTestResult":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/WebhookTestDelivery"}},"required":["delivery"]},"DeclarationResult":{"type":"object","properties":{"declaration":{"type":"object","properties":{"version":{"type":"string","description":"Send this as prohibitedItemsDeclaration.version."},"title":{"type":"string"},"body":{"type":"string","description":"The text to show before confirming."},"publishedAt":{"type":"string","format":"date-time"}},"required":["version","title","body"]}},"required":["declaration"]},"ClaimReason":{"type":"string","enum":["LOSS","DAMAGE","MISSING_ITEMS","DELAY","WRONG_DELIVERY"],"description":"LOSS, DAMAGE, MISSING_ITEMS, DELAY (the delivery promise was missed) or WRONG_DELIVERY."},"ClaimStatus":{"type":"string","enum":["SUBMITTED","UNDER_REVIEW","AWAITING_APPROVAL","APPROVED","PARTLY_APPROVED","REJECTED","PAID","WITHDRAWN"],"description":"AWAITING_APPROVAL: approved above the threshold and waiting for a second supervisor. PAID: the compensation was sent."},"ClaimEvidence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fileName":{"type":"string"},"contentType":{"type":"string","enum":["application/pdf","image/jpeg","image/png"]},"sizeBytes":{"type":"integer"},"sha256":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"}},"required":["id","fileName","contentType","sizeBytes","sha256","uploadedAt"]},"ClaimPayout":{"type":"object","properties":{"reference":{"type":"string","description":"Payout ID","pattern":"^(?:QD-CPO-[A-F0-9]{24}|QDCPO[A-Z0-9]{10,31})$"},"method":{"type":"string","enum":["ORIGINAL_PAYMENT","BUSINESS_WALLET","PERSONAL_WALLET","MOBILE_MONEY"]},"amountMinor":{"type":"integer"},"status":{"type":"string","enum":["REQUESTED","PENDING","CONFIRMED","FAILED","UNKNOWN"],"description":"REQUESTED: a refund to the original payment is reserved and being processed."},"momoNumber":{"type":["string","null"],"description":"Masked Mobile Money number."},"createdAt":{"type":"string","format":"date-time"},"confirmedAt":{"type":["string","null"],"format":"date-time"}},"required":["reference","method","amountMinor","status"]},"Claim":{"type":"object","properties":{"id":{"type":"string","description":"Claim ID","pattern":"^(?:QD-CLM-[A-F0-9]{24}|QDCLM[A-Z0-9]{3,31})$","example":"QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4"},"status":{"$ref":"#/components/schemas/ClaimStatus"},"reason":{"$ref":"#/components/schemas/ClaimReason"},"description":{"type":"string"},"declaredValueMinor":{"type":"integer","description":"Declared value of the contents in pesewas (0 for DELAY)."},"currency":{"type":"string","const":"GHS"},"shipment":{"type":"object","properties":{"trackingNumber":{"type":["string","null"]},"id":{"type":["string","null"]}}},"claimant":{"type":"string","enum":["SENDER","RECEIVER","MERCHANT"]},"source":{"type":"string","enum":["PERSONAL","BUSINESS","API","STAFF"]},"windowEndsAt":{"type":["string","null"],"description":"Last moment this parcel could be claimed.","format":"date-time"},"liabilityCapMinor":{"type":"integer","description":"Liability cap for this product, after your contract terms."},"approvedMinor":{"type":["integer","null"],"description":"Approved compensation once decided."},"decisionReason":{"type":["string","null"]},"decidedAt":{"type":["string","null"],"format":"date-time"},"caseReference":{"type":["string","null"],"description":"The linked support case (QD-SUP-…)."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/ClaimEvidence"}},"payouts":{"type":"array","items":{"$ref":"#/components/schemas/ClaimPayout"}},"timeline":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"at":{"type":"string","format":"date-time"}},"required":["type","at"]}}},"required":["id","status","reason","declaredValueMinor","currency","shipment","liabilityCapMinor","approvedMinor","createdAt"],"description":"A parcel claim. Internal liability findings and staff names are never returned."},"ClaimCreateRequest":{"type":"object","properties":{"trackingNumber":{"type":"string","description":"Tracking number or shipment ID of your LIVE parcel.","pattern":"^(?:QDE-[A-F0-9]{24}|QDE[A-Z0-9]{10,33}|QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31})$"},"reason":{"$ref":"#/components/schemas/ClaimReason"},"description":{"type":"string","description":"What happened, 20–3000 characters.","minLength":20,"maxLength":3000},"declaredValueMinor":{"type":"integer","description":"Value of the contents in pesewas; required above 0 except for DELAY.","minimum":0,"maximum":100000000}},"required":["trackingNumber","reason","description","declaredValueMinor"]},"ClaimResult":{"type":"object","properties":{"claim":{"$ref":"#/components/schemas/Claim"}},"required":["claim"]},"ClaimCreateResult":{"type":"object","properties":{"claim":{"$ref":"#/components/schemas/Claim"},"replayed":{"type":"boolean"}},"required":["claim","replayed"]},"ClaimList":{"type":"object","properties":{"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"nextCursor":{"type":["string","null"]}},"required":["claims","nextCursor"]},"ClaimEvidenceRequest":{"type":"object","properties":{"fileName":{"type":"string","maxLength":200},"contentBase64":{"type":"string","description":"The file, base64 encoded: JPEG, PNG or PDF, up to 3.5 MB.","contentEncoding":"base64"}},"required":["fileName","contentBase64"]},"ClaimEvidenceResult":{"type":"object","properties":{"evidence":{"$ref":"#/components/schemas/ClaimEvidence"}},"required":["evidence"]},"WebhookClaimEvent":{"type":"object","properties":{"id":{"type":"string","description":"Stable event ID; deduplicate on it.","format":"uuid"},"type":{"type":"string","enum":["claim.submitted","claim.under_review","claim.approved","claim.partly_approved","claim.rejected","claim.paid","claim.withdrawn"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"claim":{"type":"object","properties":{"id":{"type":"string","description":"Claim ID","pattern":"^(?:QD-CLM-[A-F0-9]{24}|QDCLM[A-Z0-9]{3,31})$","example":"QD-CLM-4D1A7E9C2B5F08A3E6C1D9B4"},"reason":{"$ref":"#/components/schemas/ClaimReason"},"status":{"$ref":"#/components/schemas/ClaimStatus"},"declared_value_minor":{"type":"integer"},"approved_minor":{"type":["integer","null"]},"currency":{"type":"string"},"shipment":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"}},"required":["id","tracking_number"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","reason","status","shipment"]}},"required":["claim"]}},"required":["id","type","created_at","data"],"description":"Body for claim.* events, for claims on your parcels (filed in the Business workspace or with a LIVE key). No description, evidence or contact details."},"ReturnReason":{"type":"string","enum":["CHANGED_MIND","WRONG_SIZE","WRONG_ITEM","DAMAGED","DEFECTIVE","NOT_AS_DESCRIBED","LATE","OTHER"],"description":"Why the goods come back."},"ReturnStatus":{"type":"string","enum":["REQUESTED","AWAITING_PAYMENT","AWAITING_DROPOFF","DROPPED_OFF","IN_TRANSIT","ARRIVED","RECEIVED","INSPECTED","REJECTED","CANCELLED","EXPIRED"],"description":"REQUESTED: waiting for your review. AWAITING_PAYMENT: approved; the customer pays before the code works. AWAITING_DROPOFF: the paperless code is active. DROPPED_OFF, IN_TRANSIT, ARRIVED (ready for you), RECEIVED (handed to you), INSPECTED. Closed: REJECTED, CANCELLED, EXPIRED."},"ReturnProduct":{"type":"string","enum":["RELAY_POINT","RELAY_LOCKER","EXPRESS_STANDARD"],"description":"RELAY_POINT: dropped off at a Qoene Point. RELAY_LOCKER: locker drop-off (not live until lockers are deployed). EXPRESS_STANDARD: a rider collects it inside an Express area."},"ReturnPayer":{"type":"string","enum":["MERCHANT","CUSTOMER","DEDUCT_FROM_REFUND"],"description":"MERCHANT: billed to your Business wallet or invoice. CUSTOMER: the customer pays by Mobile Money before the code works. DEDUCT_FROM_REFUND: billed to you; deductFromRefundMinor tells your refund system what to keep back."},"ReturnItem":{"type":"object","properties":{"line":{"type":"integer","description":"Line number in the original order (1-based)."},"name":{"type":"string"},"sku":{"type":["string","null"]},"quantity":{"type":"integer"},"unitPriceMinor":{"type":["integer","null"]}},"required":["line","name","quantity"]},"Return":{"type":"object","properties":{"id":{"type":"string","description":"Return ID","pattern":"^(?:QD-RET-[A-F0-9]{24}|QDRET[A-Z0-9]{3,31})$","example":"QD-RET-5C2E8A1F9B3D07E4A6C1F8B2"},"status":{"$ref":"#/components/schemas/ReturnStatus"},"source":{"type":"string","enum":["TRACKING_PAGE","PERSONAL_APP","MERCHANT_WEB","MERCHANT_API"]},"reason":{"$ref":"#/components/schemas/ReturnReason"},"reasonLabel":{"type":"string"},"note":{"type":["string","null"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnItem"}},"declaredValueMinor":{"type":"integer"},"product":{"$ref":"#/components/schemas/ReturnProduct"},"payer":{"$ref":"#/components/schemas/ReturnPayer"},"priceMinor":{"type":"integer","description":"Price of the return parcel in pesewas."},"deductFromRefundMinor":{"type":"integer","description":"For DEDUCT_FROM_REFUND: keep this much back from the customer refund."},"currency":{"type":"string","const":"GHS"},"promisedBy":{"type":["string","null"],"description":"Promise on the return leg (NB19).","format":"date-time"},"dropoffBy":{"type":["string","null"],"description":"The code expires at this time if unused.","format":"date-time"},"customer":{"type":"object","properties":{"name":{"type":["string","null"]}}},"originalShipment":{"type":"object","properties":{"id":{"type":"string"},"trackingNumber":{"type":"string"},"orderReference":{"type":["string","null"]}},"required":["id","trackingNumber"]},"returnShipment":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"trackingNumber":{"type":"string"},"status":{"type":"string"}},"required":["id","trackingNumber","status"]},{"type":"null"}]},"dropoffPoint":{"oneOf":[{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},{"type":"null"}]},"returnsTo":{"oneOf":[{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code"]},{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},{"type":"null"}]},"store":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},{"type":"null"}]},"order":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"externalOrderId":{"type":"string"}}},{"type":"null"}]},"code":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","enum":["PENDING_PAYMENT","ACTIVE","USED","EXPIRED","REVOKED"]},"expiresAt":{"type":"string","format":"date-time"},"usedAt":{"type":["string","null"],"format":"date-time"}},"required":["status"],"description":"State of the paperless code. The code itself is only shown to the customer."},{"type":"null"}]},"payment":{"oneOf":[{"type":"object","properties":{"obligationId":{"type":"string"},"status":{"type":"string"}}},{"type":"null"}]},"decision":{"oneOf":[{"type":"object","properties":{"at":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]},"automatic":{"type":"boolean"}}},{"type":"null"}]},"inspection":{"oneOf":[{"type":"object","properties":{"condition":{"type":"string","enum":["AS_NEW","OPENED","USED","DAMAGED","MISSING_ITEMS","WRONG_ITEM"]},"notes":{"type":["string","null"]},"at":{"type":"string","format":"date-time"}}},{"type":"null"}]},"refund":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","enum":["MERCHANT_SYSTEM","DELIVERY_WALLET","NONE"]},"amountMinor":{"type":["integer","null"]},"reference":{"type":["string","null"]},"at":{"type":"string","format":"date-time"}}},{"type":"null"}]},"claim":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}}},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","reason","items","product","payer","priceMinor","originalShipment","createdAt"],"description":"An e-commerce return: a reverse parcel linked to the original. The customer's phone and the drop-off code are never returned."},"ReturnCreateRequest":{"type":"object","properties":{"trackingNumber":{"type":"string","description":"Tracking number or shipment ID of the delivered LIVE parcel.","pattern":"^(?:QDE-[A-F0-9]{24}|QDE[A-Z0-9]{10,33}|QD-SHP-[A-F0-9]{24}|QDSHP[A-Z0-9]{3,31})$"},"items":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"quantity":{"type":"integer"}},"required":["line"]},"description":"Lines from the original order (all of them when you omit quantity).","minItems":1,"maxItems":50},"reason":{"$ref":"#/components/schemas/ReturnReason"},"note":{"type":["string","null"],"description":"Required for OTHER (5–1000 characters)."},"productCode":{"$ref":"#/components/schemas/ReturnProduct"},"dropoffPointCode":{"type":"string","description":"The Qoene Point where the customer plans to drop off (they may use another point of the same price)."},"pickupAddressText":{"type":"string","description":"EXPRESS_STANDARD: where the rider collects."},"email":{"type":"string","description":"Optional email to send the code to."},"declaredValueMinor":{"type":"integer","description":"Only when the order lines have no prices."},"prohibitedItemsDeclaration":{"type":"object","properties":{"accepted":{"type":"boolean","const":true},"version":{"type":"string"}},"required":["accepted","version"]}},"required":["trackingNumber","items","reason","prohibitedItemsDeclaration"]},"ReturnQuoteRequest":{"type":"object","properties":{"trackingNumber":{"type":"string"},"productCode":{"$ref":"#/components/schemas/ReturnProduct"},"dropoffPointCode":{"type":"string"},"pickupAddressText":{"type":"string"}},"required":["trackingNumber"]},"ReturnQuote":{"type":"object","properties":{"quoteId":{"type":"string","description":"Quote ID","pattern":"^(?:QD-QT-[A-F0-9]{24}|QDQT[A-Z0-9]{3,32})$","example":"QD-QT-0123456789ABCDEF01234567"},"productCode":{"$ref":"#/components/schemas/ReturnProduct"},"totalMinor":{"type":"integer"},"currency":{"type":"string"},"payer":{"$ref":"#/components/schemas/ReturnPayer"},"customerPaysMinor":{"type":"integer"},"deductedFromRefundMinor":{"type":"integer"},"promisedBy":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"returnsTo":{"oneOf":[{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}}},{"type":"null"}]}},"required":["quoteId","totalMinor","payer"]},"ReturnQuoteResult":{"type":"object","properties":{"quote":{"$ref":"#/components/schemas/ReturnQuote"}},"required":["quote"]},"ReturnDecisionRequest":{"type":"object","properties":{"reason":{"type":"string","description":"5–500 characters, shown to the customer.","minLength":5,"maxLength":500}},"required":["reason"]},"ReturnResult":{"type":"object","properties":{"return":{"$ref":"#/components/schemas/Return"}},"required":["return"]},"ReturnCreateResult":{"type":"object","properties":{"return":{"$ref":"#/components/schemas/Return"},"replayed":{"type":"boolean"}},"required":["return","replayed"]},"ReturnList":{"type":"object","properties":{"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"nextCursor":{"type":["string","null"]}},"required":["returns","nextCursor"]},"ReturnPolicy":{"type":"object","properties":{"source":{"type":"string","enum":["DEFAULT","BUSINESS","STORE"]},"id":{"type":["string","null"]},"version":{"type":"integer"},"status":{"type":"string","enum":["ACTIVE","DISABLED"]},"windowDays":{"type":"integer"},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/ReturnReason"}},"payer":{"$ref":"#/components/schemas/ReturnPayer"},"merchantPaymentMode":{"type":"string","enum":["BUSINESS_WALLET","BUSINESS_INVOICE"]},"allowedProducts":{"type":"array","items":{"$ref":"#/components/schemas/ReturnProduct"}},"approvalMode":{"type":"string","enum":["AUTO","MANUAL"]},"maxValueMinor":{"type":["integer","null"]},"returnPointCode":{"type":["string","null"]},"returnPointName":{"type":["string","null"]},"returnAddress":{"oneOf":[{"type":"object","properties":{"text":{"type":"string"}}},{"type":"null"}]},"returnContact":{"oneOf":[{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"}}},{"type":"null"}]},"instructions":{"type":["string","null"]},"contract":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"overrides":{"type":"array","items":{"type":"string"}}}},{"type":"null"}]}},"required":["source","status","windowDays","reasons","payer","allowedProducts","approvalMode"],"description":"The return policy in force (store, else Business, else default), after any contract terms."},"ReturnPolicyResult":{"type":"object","properties":{"policy":{"$ref":"#/components/schemas/ReturnPolicy"}},"required":["policy"]},"WebhookReturnEvent":{"type":"object","properties":{"id":{"type":"string","description":"Stable event ID; deduplicate on it.","format":"uuid"},"type":{"type":"string","enum":["return.requested","return.approved","return.rejected","return.cancelled","return.expired","return.dropped_off","return.in_transit","return.arrived","return.received","return.inspected","return.refund_recorded"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"return":{"type":"object","properties":{"id":{"type":"string","description":"Return ID","pattern":"^(?:QD-RET-[A-F0-9]{24}|QDRET[A-Z0-9]{3,31})$","example":"QD-RET-5C2E8A1F9B3D07E4A6C1F8B2"},"status":{"$ref":"#/components/schemas/ReturnStatus"},"reason":{"$ref":"#/components/schemas/ReturnReason"},"product":{"$ref":"#/components/schemas/ReturnProduct"},"payer":{"$ref":"#/components/schemas/ReturnPayer"},"price_minor":{"type":"integer"},"deduct_from_refund_minor":{"type":"integer"},"currency":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"sku":{"type":["string","null"]},"quantity":{"type":"integer"}}}},"inspection_condition":{"type":["string","null"]},"refund_method":{"type":["string","null"]},"refund_amount_minor":{"type":["integer","null"]},"original_shipment":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"order_reference":{"type":["string","null"]}},"required":["id","tracking_number"]},"return_shipment":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"}}},{"type":"null"}]},"order":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"external_order_id":{"type":"string"}}},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","status","reason","original_shipment"]}},"required":["return"]}},"required":["id","type","created_at","data"],"description":"Body for return.* events. No customer contact, notes or drop-off codes. Refund your customer from your own system on return.received or return.inspected."},"AnalyticsTotals":{"type":"object","properties":{"booked":{"type":"integer","description":"Parcels booked in the period."},"delivered":{"type":"integer","description":"Parcels handed to the receiver (delivered or collected)."},"promiseMet":{"type":"integer"},"promiseMissed":{"type":"integer"},"onTimeRate":{"type":["number","null"],"description":"Promises met out of promises decided. Percent with one decimal; null when there is nothing to divide by."},"averageDeliveryMinutes":{"type":["integer","null"],"description":"Average minutes from booking to delivery or collection."},"collected":{"type":"integer","description":"Parcels collected at a Qoene Point or locker."},"returnedUncollected":{"type":"integer","description":"Parcels sent back because nobody collected them."},"pickupRate":{"type":["number","null"],"description":"Collected out of collected plus returned uncollected. Percent with one decimal; null when there is nothing to divide by."},"returned":{"type":"integer"},"cancelled":{"type":"integer"},"claimsFiled":{"type":"integer"},"claimsRate":{"type":["number","null"],"description":"Claims filed per parcel booked. Percent with one decimal; null when there is nothing to divide by."},"returnsAuthorised":{"type":"integer"},"returnsRate":{"type":["number","null"],"description":"Returns started per parcel delivered. Percent with one decimal; null when there is nothing to divide by."},"chargeMinor":{"$ref":"#/components/schemas/MinorAmount"},"costPerParcelMinor":{"oneOf":[{"$ref":"#/components/schemas/MinorAmount"},{"type":"null"}]},"overstayParcels":{"type":"integer"},"overstayMinor":{"$ref":"#/components/schemas/MinorAmount"},"overstayCoveredMinor":{"$ref":"#/components/schemas/MinorAmount","description":"Overstay you covered for your customers (NB26)."}},"required":["booked","delivered","onTimeRate","costPerParcelMinor"],"description":"Totals for the period. Each figure counts on the business day its own event happened."},"AnalyticsTrendDay":{"type":"object","properties":{"date":{"type":"string","description":"Business day in the market time zone.","format":"date"},"booked":{"type":"integer"},"delivered":{"type":"integer"},"promiseMet":{"type":"integer"},"promiseMissed":{"type":"integer"},"onTimeRate":{"type":["number","null"],"description":"Promises met out of promises decided that day. Percent with one decimal; null when there is nothing to divide by."}},"required":["date","booked","delivered"]},"AnalyticsBreakdown":{"type":"object","properties":{"serviceCode":{"$ref":"#/components/schemas/ServiceCode"},"region":{"type":"string","description":"Destination region (from the point or the address region). No addresses."},"booked":{"type":"integer"},"delivered":{"type":"integer"},"onTimeRate":{"type":["number","null"],"description":"On time. Percent with one decimal; null when there is nothing to divide by."},"averageDeliveryMinutes":{"type":["integer","null"]},"returnsRate":{"type":["number","null"],"description":"Returns. Percent with one decimal; null when there is nothing to divide by."},"claimsRate":{"type":["number","null"],"description":"Claims. Percent with one decimal; null when there is nothing to divide by."},"costPerParcelMinor":{"oneOf":[{"$ref":"#/components/schemas/MinorAmount"},{"type":"null"}]}},"required":["serviceCode","booked","delivered"]},"AnalyticsSummary":{"type":"object","properties":{"environment":{"$ref":"#/components/schemas/Environment"},"market":{"type":"string","example":"GH"},"currency":{"type":"string","example":"GHS"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"refreshedAt":{"type":["string","null"],"description":"When the daily figures were last rebuilt (hourly).","format":"date-time"},"totals":{"$ref":"#/components/schemas/AnalyticsTotals"},"trend":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsTrendDay"},"description":"One entry per business day in the period."},"byProduct":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsBreakdown"}},"byRegion":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsBreakdown"}},"topDestinations":{"type":"array","items":{"type":"object","properties":{"region":{"type":"string"},"parcels":{"type":"integer"}},"required":["region","parcels"]},"description":"Up to 10 destination regions by parcels booked."}},"required":["environment","market","currency","from","to","totals","trend","byProduct","byRegion","topDestinations"],"description":"Delivery performance of your own parcels. Only your Business; no receiver names, phones or addresses. TEST and LIVE keys read the same LIVE figures (read-only aggregates)."}},"responses":{"BadRequest":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid, expired or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks the scope, or the operation needs a LIVE key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found for this Business and environment. IDs from another Business or environment are always 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Idempotency key reused with another body, or the resource changed state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"Eligibility or business rule refused the request; `details.reason` explains why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests. See the RateLimit headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Gone":{"description":"The checkout session or price has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotImplemented":{"description":"Reserved for a later stage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"x-qoene-scopes":["locations.read","quotes.write","shipments.write","wallet.spend","shipments.read","shipments.cancel","tracking.read","labels.read","labels.write","manifests.write","manifests.read","payments.write","payments.read","services.read","orders.read","orders.write","orders.ship","webhooks.read","webhooks.write","claims.read","claims.write","returns.read","returns.write","analytics.read","checkout.write"]}