{"openapi":"3.1.0","info":{"title":"Transport Management System","version":"1.0","description":"Price hiding: a service provider can hide its prices from a customer account per order family (local delivery, label service, shipping service, LTL service, storage services, moving services, device orders). Responses to such a customer omit every price field (shipping_price, price_details, currency, tax, surcharge amounts, rate prices, paid amounts) and carry price_hidden: true; rate lists keep rate_id and service names. Online payment endpoints answer 403 with code PRICE_HIDDEN_SETTLE_OFFLINE for a hidden family. Treat price fields as optional; a missing figure never means free."},"servers":[{"description":"Production","url":"/api/"},{"description":"Local","url":"http://127.0.0.1/api/"}],"tags":[{"name":"Broker Order Assignments","description":"Handing one order to one contractor exclusively, and taking it back"},{"name":"User","description":"Operations about user"},{"name":"Driver","description":"Everything about your drivers Error messages follow the Accept-Language request header (en, zh-Hans, zh-Hant, fr, de, es and the other supported languages); without that header they are returned in English exactly as before."},{"name":"Client","description":"Everything about client"},{"name":"Shipping","description":"Everything about shipping"},{"name":"AddressBook","description":"Everything about addressbook"},{"name":"DriverInfo","description":"Everything about Drivers"},{"name":"Skills","description":"Everything about Drivers Skills"},{"name":"ReturnReasons","description":"Everything about ReturnReasons"},{"name":"LabelService","description":"Operations about LabelService"},{"name":"OCR","description":"Operations for Optical Character Recognition (OCR) label parsing"},{"name":"POI","description":"Operations for Points of Interest (POI) management"},{"name":"Dataset","description":"Operations for Dataset management - flexible data storage and geocoding"},{"name":"Alliance","description":"Delivery Alliance management - cross-client tracking authorization and data sharing"},{"name":"Tracking","description":"Package tracking and tracking number management"},{"name":"Customer","description":"Customer-facing APIs for placing orders from a customer account"},{"name":"ThirdPartyDelivery","description":"Third-party delivery provider order pull and acceptance APIs"},{"name":"Warehouse Transfer","description":"Move mis-received local delivery packages between warehouses with batch rollback and audit trail"},{"name":"InstantRider","description":"Superroute-native Instant Deliver rider API for our own driver app (a rider is a driver granted Instant Deliver). Uses the standard driver login + Bearer token. Error messages follow the Accept-Language request header (en, zh-Hans, zh-Hant, fr, de, es and the other supported languages); without that header they are returned in English exactly as before."},{"name":"OTEP","description":"Open Tracking Event Protocol — unified tracking timeline (self-delivery, third-party, carrier) with content-negotiated GS1 EPCIS / IATA ONE Record / UN-CEFACT projections"},{"name":"Custom Maps","description":"Custom Maps Layer API — public/embed and authenticated business maps"},{"name":"Loading Planner","description":"Multimodal loading solver for sea containers, air ULD envelopes, vehicles, truck bodies, breakbulk and custom rectangular cargo spaces"},{"name":"Packing Plans","description":"Carton packing solver. Candidate packagings come from the business's packaging catalog (whole packaging categories or specific packagings) plus per-plan custom sizes; the solver picks the combination that packs everything while minimizing total outer volume, then package count, then cost. The plan's target_utilization_percent is a hard fill cap: no package is ever filled beyond cap x inner volume."},{"name":"Smart Locker","description":"Smart locker operator and device operations"},{"name":"Webhooks","description":"Webhook delivery management"},{"name":"Warehouse Mobile","description":"Standalone warehouse mobile app APIs for receiving, putaway, route sorting and route outbound"},{"name":"Platform Apps","description":"Public runtime configuration for standalone apps assigned to Superroute clients"},{"name":"Dispatch","description":"Dispatch board: what needs a dispatcher today, and what they decided about it. Reports observed state only — no arrival forecasts."},{"name":"Device Operations","description":"Unified operation log for kiosks, smart lockers and smart drops."},{"name":"Reservations","description":"Public reservation and waitlist booking APIs"},{"name":"Driver Route Board","description":"Route Board, driver side: see the boards of your fleet, claim a route first come first served, queue as standby, withdraw. Shared with the driver web page at /driver/board."},{"name":"Locker Resale","description":"Item handovers through a smart locker. The platform never holds the money for the goods."},{"name":"Luggage Relay","description":"Bags kept at the hub warehouse between two compartments, and the renter's return choice made on their behalf"},{"name":"Locker Storage","description":"Short-term luggage storage. Read-only."},{"name":"Consolidation","description":"Package forwarding (consolidation) warehouse integration. Inbound tracking pushes from a contracted tracking provider."},{"name":"Order Chat","description":"Per-order conversation between dispatchers, the assigned driver and (optionally) the customer on the tracking page. Opt-in family `order_chat` of the Dispatch Options Center: every endpoint answers 409 {result:false, feature_enabled:false} while the option is off. Messages are separate from order notes. Live push over the platform MQTT channel (topic {prefix}/order-chat/{business_id}/{order_id}); driver-app push type `order_chat_message`."},{"name":"Operations AI Agent","description":"Operations AI agent (Dispatch Options → ai_ops_agent, opt-in): console conversations that run the User MCP read tools on behalf of the caller and propose writes for human approval, plus AI dispatcher suggestions. Every endpoint answers 409 {result:false, feature_enabled:false} while the family (or the platform admin gate) is off and 429 {error_code:\"DAILY_CAP_REACHED\"} once the business's daily turn cap is used. Client / employee accounts."},{"name":"SMS Marketing","description":"Opt-in SMS marketing (Dispatch Options family sms_marketing): subscribers with double opt-in consent evidence, audience segments built on recipient profiles, campaigns with frequency caps, quiet hours, unsubscribe keywords and offer codes. Every endpoint answers 409 while the family is off, revoked by the platform admin, or not migrated; 403 for non-business accounts."},{"name":"Device Orders","description":"The device order ledger: each handling of a parcel by a smart locker, kiosk or smart drop, its history and its exceptions."},{"name":"Documents","description":"Document fingerprints: verify that a PDF was issued by this system and is intact"},{"name":"Fleets","description":"Fleets under an owner, their captains and the fleet shift calendar (docs/FLEET-CAPTAIN-DESIGN.md)"}],"paths":{"/v1/broker-order-assignments":{"get":{"tags":["Broker Order Assignments"],"summary":"List manual contractor order assignments","description":"Orders handed to a contractor exclusively, newest first, with their current status and history. An assigned order is plannable only by that contractor: it leaves every other contractor's rule pool and the client's own planning pool until it is revoked or released. Client and employee accounts only; a contractor account always sees only its own assignments and the broker_id filter is ignored for it. Mirrored by GraphQL brokerOrderAssignments. Available only while the platform has enabled the contractor order assignment module for the account; otherwise every operation answers 403.","parameters":[{"in":"query","name":"broker_id","required":false,"schema":{"type":"integer","description":"Only this contractor (ignored for contractor accounts)\n\n**Details:** Optional · Type `integer`."},"description":"Only this contractor (ignored for contractor accounts)\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"status","required":false,"schema":{"type":"string","enum":["active","revoked","released"],"description":"Only assignments in this state\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `revoked` · `released`.\n\n**Details:** Optional · Type `string`."},"description":"Only assignments in this state\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `revoked` · `released`.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"order_id","required":false,"schema":{"type":"integer","description":"Only this order\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`."},"description":"Only this order\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"page","required":false,"schema":{"type":"integer","description":"Page number, from 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Page number, from 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","description":"Rows per page, 1-200 (default 50)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"Rows per page, 1-200 (default 50)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Assignments","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"page":{"type":"integer","description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer`."},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`."},"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"order_ref":{"type":["string","null"],"description":"Order ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"order_status_id":{"type":["integer","null"],"description":"Order status id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"scheduled_date":{"type":["string","null"],"description":"Scheduled date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string` · Nullable."},"route_id":{"type":["integer","null"],"description":"The route the order is on, or null while it is unplanned\n\n**Details:** Type `integer` · Nullable."},"broker_id":{"type":"integer","description":"Broker id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"broker_name":{"type":["string","null"],"description":"Broker name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"string","enum":["active","revoked","released"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `revoked` · `released`.\n\n**Details:** Type `string`."},"note":{"type":["string","null"],"description":"Note. Free-text note.\n\n**Details:** Type `string` · Nullable."},"assigned_by":{"type":["integer","null"],"description":"Assigned by. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"assigned_at":{"type":["string","null"],"description":"Assigned at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"ended_by":{"type":["integer","null"],"description":"Ended by. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"ended_at":{"type":["string","null"],"description":"Ended at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"end_reason":{"type":["string","null"],"description":"End reason. Free-text note.\n\n**Details:** Type `string` · Nullable."}}},"description":"Assignments. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"total":1,"page":1,"per_page":50,"assignments":[{"id":41,"order_id":90210,"order_ref":"ORD-90210","order_status_id":2,"scheduled_date":"2026-09-21","route_id":null,"broker_id":8812,"broker_name":"Northside Couriers","status":"active","note":"Keyed building, they have the fob","assigned_by":501,"assigned_at":"2026-09-19 09:12:00","ended_by":null,"ended_at":null,"end_reason":null}]}}}},"403":{"description":"Not authorized"},"503":{"description":"Contractor order assignment is not available yet on this system"}}},"post":{"tags":["Broker Order Assignments"],"summary":"Assign orders to one contractor exclusively","description":"Hands each order to the named contractor. An order already held by another contractor is moved in one step. Client admin accounts only. An order is refused (and reported in errors) when it is already on a route, is not a self-delivery order, is not in an assignable status, or is held by a third-party carrier. Mirrored by GraphQL assignOrdersToBroker. Available only while the platform has enabled the contractor order assignment module for the account; otherwise every operation answers 403.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_ids","broker_id"],"properties":{"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nOrders to assign\n\n**Details:** Type `array`, items `integer`."},"broker_id":{"type":"integer","description":"**Required.**\n\nContractor (broker employee) user id\n\n**Details:** Type `integer`."},"note":{"type":"string","description":"Optional note stored with the assignment\n\n**Details:** Type `string` · maxLength `500`.","maxLength":500}}},"example":{"order_ids":[90210,90211],"broker_id":8812,"note":"Keyed building, they have the fob"}}}},"responses":{"200":{"description":"Assignment result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"True when at least one order was assigned\n\n**Details:** Type `boolean`."},"assigned":{"type":"integer","description":"Assigned. Field in the JSON request body.\n\n**Details:** Type `integer`."},"skipped":{"type":"integer","description":"Skipped. Field in the JSON request body.\n\n**Details:** Type `integer`."},"errors":{"type":"array","description":"One entry per order that was not changed, with the reason\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"example":{"result":true,"assigned":1,"skipped":1,"errors":[{"order_id":90211,"message":"This order is already on a route"}]}}}},"403":{"description":"Not authorized"},"422":{"description":"Missing orders or contractor"}}}},"/v1/broker-order-assignments/revoke":{"post":{"tags":["Broker Order Assignments"],"summary":"Take manually assigned orders back from a contractor","description":"Ends the active assignment on each order and returns it to the ordinary contractor rules. Client admin accounts only. An order already on a route is refused and reported in errors: take it off the route first, which is a separate operation. Mirrored by GraphQL revokeBrokerOrderAssignments. Available only while the platform has enabled the contractor order assignment module for the account; otherwise every operation answers 403.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_ids"],"properties":{"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nOrders to take back\n\n**Details:** Type `array`, items `integer`."},"reason":{"type":"string","description":"Optional reason stored on the assignment\n\n**Details:** Type `string` · maxLength `255`.","maxLength":255}}},"example":{"order_ids":[90210],"reason":"Planning in house today"}}}},"responses":{"200":{"description":"Revoke result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"revoked":{"type":"integer","description":"Revoked. Field in the JSON request body.\n\n**Details:** Type `integer`."},"skipped":{"type":"integer","description":"Skipped. Field in the JSON request body.\n\n**Details:** Type `integer`."},"errors":{"type":"array","description":"One entry per order that was not changed, with the reason\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"example":{"result":true,"revoked":1,"skipped":0,"errors":[]}}}},"403":{"description":"Not authorized"},"422":{"description":"Missing orders"}}}},"/v1/broker-order-assignments/release":{"post":{"tags":["Broker Order Assignments"],"summary":"Hand a manually assigned order back to the client","description":"The holding contractor gives the order back; it returns to the ordinary contractor rules, that contractor's own rules included. Contractor (broker employee) accounts only, and only for their own assignment. Refused while the order is on a route. Mirrored by GraphQL releaseBrokerOrderAssignment. Available only while the platform has enabled the contractor order assignment module for the account; otherwise every operation answers 403.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["order_id"],"properties":{"order_id":{"type":"integer","description":"**Required.**\n\nThe assigned order to hand back\n\n**Details:** Type `integer`."},"reason":{"type":"string","description":"Optional reason stored on the assignment\n\n**Details:** Type `string` · maxLength `255`.","maxLength":255}}},"example":{"order_id":90210,"reason":"No capacity on that day"}}}},"responses":{"200":{"description":"Release result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Assignment released"}}}},"400":{"description":"The order is on a route, or is not assigned to this contractor"},"403":{"description":"Not authorized"}}}},"/v1/apps/{appCode}/clients/{clientCode}/bootstrap":{"get":{"tags":["Platform Apps"],"summary":"Bootstrap a client-assigned app","description":"Returns public branding, effective capabilities, service contracts and version policy. The client code identifies configuration only and is not an authorization credential. settings.home.quick_actions lists the home screen shortcut ids (send, return, store, lockers, luggage, handover, pay, wallet) in the Client's order, without the ones it hid; the app shows a shortcut only while its capability is on.","operationId":"platformAppBootstrap","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["ios","android"],"description":"Client platform for bootstrap / capability negotiation.\n\nClient platform for bootstrap / capability negotiation.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Optional · Type `string`.","x-enumDescriptions":["Apple iOS","Google Android"]},"description":"Client platform for bootstrap / capability negotiation.\n\nClient platform for bootstrap / capability negotiation.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Optional · Type `string`."},{"name":"app_version","in":"query","required":false,"schema":{"type":"string","description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Optional · Type `string`.","examples":["1.0.0"]},"description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"Effective public app configuration","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"app":{"code":"mibox","name":"MiBox","type":"customer","schema_version":1},"client":{"code":"n4x7q2g8w9r3k6m1p5t0z8ab","display_name":"Mili Express"},"configuration_version":3,"capabilities":{"auth.google":true,"wallet.balance":true,"locker.pickup":true},"authentication":{"methods":{"google":true,"email":true,"registration":true},"google":{"server_client_id":"shared-web-oauth-client.apps.googleusercontent.com"},"registration":{"enabled":true,"phone_verification_required":true,"sms_configured":true,"default_phone_region":"CA","requires_approval":false,"code_length":6,"resend_after":60}},"services":{"identity":{"source_of_truth":"superroute","shared_with_web":true},"wallet":{"source_of_truth":"superroute","ledger_mode":"existing_customer_account"}}}}}}},"403":{"description":"The app or client assignment is not currently available"},"404":{"description":"The app/client context does not exist"},"422":{"description":"Invalid platform or app version"}}}},"/v1/apps/{appCode}/clients/{clientCode}/auth/google":{"post":{"tags":["Platform Apps"],"summary":"Sign in to an app with Google","description":"Verifies a Google ID token against the app's shared backend audience, resolves the single global Google binding also used by Web, then restricts access to the selected Client and allowed user roles. Native mobile sign-in does not use the Web OAuth callback.","operationId":"platformAppGoogleLogin","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id_token","device_id","device_platform"],"properties":{"id_token":{"type":"string","description":"**Required.**\n\nGoogle (or other IdP) ID token to exchange for a Superroute session.\n\n**Details:** Type `string`."},"device_id":{"type":"string","maxLength":191,"description":"**Required.**\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Type `string` · maxLength `191`."},"device_platform":{"type":"string","enum":["ios","android"],"description":"**Required.**\n\nNative client platform for app session / device binding.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Type `string`.","x-enumDescriptions":["Apple iOS","Google Android"]},"app_version":{"type":["string","null"],"description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Type `string` · Nullable."}}},"example":{"id_token":"google-signed-id-token","device_id":"0f3d1c43-7f53-4c16-ae90-62a2bc921812","device_platform":"ios","app_version":"1.0.0"}}}},"responses":{"200":{"description":"App session issued","content":{"application/json":{"example":{"result":true,"access_token":"passport-access-token","token_type":"Bearer","expires_at":"2026-07-30 12:00:00","expires_timestamp":1785436800,"user":{"id":1001,"name":"MiBox Customer","email":"customer@example.com"},"app_context":{"app_code":"mibox","client_code":"n4x7q2g8w9r3k6m1p5t0z8ab","client_name":"Mili Express","configuration_version":3}}}}},"401":{"description":"Invalid Google ID token or identity"},"403":{"description":"App, method, role or Client access is not allowed"},"409":{"description":"Registration is required or the Google binding conflicts"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/auth/email":{"post":{"tags":["Platform Apps"],"summary":"Sign in to an app with email","description":"Authenticates the normal Superroute account password, then applies the selected app's role and Client ownership policy before issuing an app session.","operationId":"platformAppEmailLogin","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","device_id","device_platform"],"properties":{"email":{"type":"string","format":"email","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email`."},"password":{"type":"string","format":"password","description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string`, format `password`."},"device_id":{"type":"string","maxLength":191,"description":"**Required.**\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Type `string` · maxLength `191`."},"device_platform":{"type":"string","enum":["ios","android"],"description":"**Required.**\n\nNative client platform for app session / device binding.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Type `string`.","x-enumDescriptions":["Apple iOS","Google Android"]},"app_version":{"type":["string","null"],"description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Type `string` · Nullable."}}},"example":{"email":"customer@example.com","password":"account-password","device_id":"0f3d1c43-7f53-4c16-ae90-62a2bc921812","device_platform":"android","app_version":"1.0.0"}}}},"responses":{"200":{"description":"App session issued; response matches Google login"},"401":{"description":"Invalid credentials"},"403":{"description":"App, method, role or Client access is not allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/auth/refresh":{"post":{"tags":["Platform Apps"],"summary":"Refresh an app session","description":"Issues a replacement Passport token for the same app, Client, user and device, and revokes the prior token.","operationId":"platformAppRefresh","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"device_id":"0f3d1c43-7f53-4c16-ae90-62a2bc921812","device_platform":"ios","app_version":"1.0.0"},"schema":{"type":"object","required":["device_id","device_platform"],"properties":{"device_id":{"type":"string","description":"**Required.**\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Type `string`."},"device_platform":{"type":"string","enum":["ios","android"],"description":"**Required.**\n\nNative client platform for app session / device binding.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Type `string`.","x-enumDescriptions":["Apple iOS","Google Android"]},"app_version":{"type":["string","null"],"description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Type `string` · Nullable."}}}}}},"responses":{"200":{"description":"Replacement app session issued"},"401":{"description":"Invalid or expired app session"},"403":{"description":"App access is no longer allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/auth/logout":{"post":{"tags":["Platform Apps"],"summary":"Sign out of an app","description":"Revokes the current Passport token and marks the matching app-device session as revoked.","operationId":"platformAppLogout","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"responses":{"200":{"description":"Session revoked","content":{"application/json":{"example":{"result":true,"message":"Signed out successfully."}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"App access is no longer allowed"}}}},"/v1/apps/{appCode}/clients/{clientCode}/registration/phone/request":{"post":{"tags":["Platform Apps"],"summary":"Request a registration phone verification code","description":"Creates a five-minute, App- and Client-scoped verification challenge and sends a six-digit code using the selected Client's SMS provider. Codes are rate limited and never returned by the API.","operationId":"platformAppRequestRegistrationCode","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","maxLength":50,"description":"**Required.**\n\nPhone number used for OTP or contact.\n\n**Details:** Type `string` · maxLength `50`."},"locale":{"type":"string","description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Type `string`.","examples":["en"]}}},"example":{"phone":"+1 416 555 0100","locale":"en"}}}},"responses":{"200":{"description":"Verification challenge created","content":{"application/json":{"example":{"result":true,"message":"A verification code was sent.","challenge_id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","phone_e164":"+14****0100","expires_in":300,"resend_after":60}}}},"403":{"description":"Registration is disabled for this App and Client"},"422":{"description":"Invalid phone number"},"429":{"description":"Code request rate limit exceeded"},"503":{"description":"Client SMS service is not configured or delivery failed"}}}},"/v1/apps/{appCode}/clients/{clientCode}/registration/complete":{"post":{"tags":["Platform Apps"],"summary":"Register a Client customer","description":"Creates the normal Superroute User and Customer records and either issues an app session or returns a pending-review result. Existing accounts are never overwritten or duplicated.\n\nTwo shapes, chosen by the Client's `registration.require_phone_verification` setting (published as `authentication.registration.phone_verification_required` on bootstrap). When it is on, send `challenge_id` and `code` from /registration/phone/request and the phone is recorded as verified. When it is off, send `phone` instead and the number is stored unverified. A challenge is always honoured if supplied.\n\nThe address is mandatory in both shapes. The new account starts from the customer template the Client selected for this app, or from the business default template when it selected none.","operationId":"platformAppRegisterCustomer","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","password","password_confirmation","address","city","postcode","country","device_id","device_platform"],"properties":{"challenge_id":{"type":["string","null"],"minLength":64,"maxLength":64,"description":"Required when the Client requires SMS verification. Send with `code`.\n\n**Details:** Type `string` · Nullable · minLength `64` · maxLength `64`."},"code":{"type":["string","null"],"pattern":"^[0-9]{6}$","description":"Required when the Client requires SMS verification. Send with `challenge_id`.\n\n**Details:** Type `string` · Nullable · pattern `^[0-9]{6}$`."},"name":{"type":"string","maxLength":255,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `255`."},"email":{"type":"string","format":"email","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email`."},"password":{"type":"string","format":"password","minLength":8,"description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string`, format `password` · minLength `8`."},"password_confirmation":{"type":"string","format":"password","description":"**Required.**\n\nPassword confirmation. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`, format `password`."},"country":{"type":"string","maxLength":255,"description":"**Required.**\n\nISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string` · maxLength `255`."},"locale":{"type":["string","null"],"description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Type `string` · Nullable."},"device_id":{"type":"string","maxLength":191,"description":"**Required.**\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Type `string` · maxLength `191`."},"device_platform":{"type":"string","enum":["ios","android"],"description":"**Required.**\n\nNative client platform for app session / device binding.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Type `string`.","x-enumDescriptions":["Apple iOS","Google Android"]},"app_version":{"type":["string","null"],"description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Type `string` · Nullable."},"phone":{"type":["string","null"],"maxLength":50,"description":"Required when no challenge is sent; stored unverified.\n\n**Details:** Type `string` · Nullable · maxLength `50`."},"address":{"type":"string","maxLength":255,"description":"**Required.**\n\nAddress. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · maxLength `255`."},"address_2":{"type":["string","null"],"maxLength":255,"description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string` · Nullable · maxLength `255`."},"city":{"type":"string","maxLength":255,"description":"**Required.**\n\nCity / locality.\n\n**Details:** Type `string` · maxLength `255`."},"province":{"type":["string","null"],"maxLength":255,"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable · maxLength `255`."},"postcode":{"type":"string","maxLength":255,"description":"**Required.**\n\nPostal / ZIP code.\n\n**Details:** Type `string` · maxLength `255`."}}},"example":{"challenge_id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","code":123456,"name":"MiBox Customer","email":"customer@example.com","password":"account-password","password_confirmation":"account-password","address":"123 King Street West","address_2":"Unit 5","city":"Toronto","province":"ON","postcode":"M5H 1A1","country":"Canada","device_id":"0f3d1c43-7f53-4c16-ae90-62a2bc921812","device_platform":"ios","app_version":"1.0.0"}}}},"responses":{"201":{"description":"Customer registered. Returns either a Passport app session or REGISTRATION_PENDING_REVIEW.","content":{"application/json":{"example":{"result":true,"message":"Registration and phone verification completed.","phone_verified":true,"requires_approval":false,"access_token":"passport-access-token","token_type":"Bearer"}}}},"403":{"description":"Registration is disabled for this App and Client"},"409":{"description":"Existing account, linked phone, or concurrent registration"},"410":{"description":"Verification challenge expired"},"422":{"description":"Invalid request, missing address, invalid verification code, or PHONE_VERIFICATION_REQUIRED when the Client requires SMS verification and no challenge was sent"},"429":{"description":"Verification attempt limit exceeded"}}}},"/v1/apps/{appCode}/clients/{clientCode}/pay/resolve":{"post":{"tags":["Platform Apps"],"summary":"Resolve a scanned pay tag","description":"Scan-to-pay entry point. The tag token names a device and nothing else; who is standing at it comes from the authenticated session. Returns every payable this payer owes at that device — none, one, or several — and the app decides from the list length whether to say nothing is due, go straight to paying, or show a chooser. Resolving also records that the sticker was scanned, which is the only way to tell a working sticker from one that peeled off. Throttled to 30 requests a minute.","operationId":"platformAppPayResolveTag","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tag_token"],"properties":{"tag_token":{"type":"string","maxLength":64,"description":"**Required.**\n\nTag token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string` · maxLength `64`."}}},"example":{"tag_token":"7b1e9c04a8f24d6fb0537ce1249ad835"}}}},"responses":{"200":{"description":"What this payer owes at that device","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"tag":{"token":"7b1e9c04a8f24d6fb0537ce1249ad835","label":"Cabinet A, front panel","target_type":"locker","target_id":312},"payables":[{"subject_type":"locker","subject_id":8801,"amount_cents":1250,"amount":12.5,"currency":"CAD","title":"Locker storage — CAB-A","description":"3 h 20 min"}]}}}},"404":{"description":"The sticker is revoked, unknown, or points at something this deployment cannot collect for","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"TAG_NOT_USABLE","message":"This code is no longer in use."}}}},"403":{"description":"The app assignment is not effective for this customer"}}}},"/v1/apps/{appCode}/clients/{clientCode}/pay/outstanding":{"get":{"tags":["Platform Apps"],"summary":"Everything this payer owes","description":"What the badge on the app's home screen counts: every payable this payer owes across the business, without scanning anything. Runs on app open, so a resolver that cannot answer cheaply returns nothing rather than make every launch slow — a short list is therefore not proof that nothing is owed.","operationId":"platformAppPayOutstanding","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Outstanding payables","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"count":1,"total_cents":1250,"payables":[{"subject_type":"locker","subject_id":8801,"amount_cents":1250,"amount":12.5,"currency":"CAD","title":"Locker storage — CAB-A","description":"3 h 20 min"}]}}}},"403":{"description":"The app assignment is not effective for this customer"}}}},"/v1/apps/{appCode}/clients/{clientCode}/pay/requests":{"post":{"tags":["Platform Apps"],"summary":"Raise a payment request for one payable","description":"Turns one outstanding payable into a request that can be settled. The amount is never taken from the caller: the payable is re-read from the business that owns it, so an app cannot name its own price or raise a charge against a subject it merely guessed. Passing tag_token scopes the re-read to that device; omitting it re-reads everything the payer owes. Asking twice for the same subject returns the request already standing rather than raising a second one. Throttled to 30 requests a minute.","operationId":"platformAppPayCreateRequest","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject_type","subject_id"],"properties":{"subject_type":{"type":"string","maxLength":32,"description":"**Required.**\n\nSubject type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · maxLength `32`.\n\n**Example:** `locker`.","examples":["locker"]},"subject_id":{"type":"integer","minimum":1,"description":"**Required.**\n\nSubject id. Identifier referencing the related record.\n\n**Details:** Type `integer` · min `1`."},"tag_token":{"type":["string","null"],"maxLength":64,"description":"Tag token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string` · Nullable · maxLength `64`."}}},"example":{"subject_type":"locker","subject_id":8801,"tag_token":"7b1e9c04a8f24d6fb0537ce1249ad835"}}}},"responses":{"200":{"description":"The request, and the methods that may settle it","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"request":{"token":"9f2c41ab7d6e40518c3a0b17e5d94a26","subject_type":"locker","subject_id":8801,"amount_cents":1250,"amount":12.5,"currency":"CAD","description":"Locker storage — CAB-A","status":"pending","expires_at":"2026-09-04T18:30:00-04:00","paid_at":null,"pay_url":"https://app.superroute.ca/pay/r/9f2c41ab7d6e40518c3a0b17e5d94a26"},"methods":[{"kind":"wallet","gateway":null,"method":"wallet","label":"Account balance","icon":"fas fa-wallet","badge_color":"secondary","available":true,"reason":null,"completion":"redirect"},{"kind":"gateway","gateway":"stripe","method":"card","label":"Credit / Debit Card","icon":"fas fa-credit-card","badge_color":"primary","completion":"sheet","available":true,"reason":null},{"kind":"gateway","gateway":"alphapay","method":"wechat_pay","label":"AlphaPay WeChat Pay","icon":"fab fa-weixin","badge_color":"success","available":true,"reason":null,"completion":"redirect"}]}}}},"422":{"description":"The payer does not owe the named subject","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"NOTHING_TO_PAY","message":"You have nothing to pay here."}}}},"403":{"description":"The app assignment is not effective for this customer"}}}},"/v1/apps/{appCode}/clients/{clientCode}/pay/requests/{publicToken}":{"get":{"tags":["Platform Apps"],"summary":"One payment request and its methods","description":"What the request is for, what it costs, and what may settle it. The method list is the business's configured gateways narrowed by the methods it left switched on, in its own order, plus the account balance when the payer has one and it covers the amount. A method the payer cannot use is returned with available false and a reason rather than omitted, so the app can grey it out and say why.","operationId":"platformAppPayRequest","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"publicToken","in":"path","required":true,"description":"The request's own opaque token, 32 hex characters.\n\n**Details:** Required · Type `string` · pattern `^[0-9a-f]{32}$`.\n\n**Example:** `9f2c41ab7d6e40518c3a0b17e5d94a26`.","schema":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"The request's own opaque token, 32 hex characters.\n\n**Details:** Required · Type `string` · pattern `^[0-9a-f]{32}$`.\n\n**Example:** `9f2c41ab7d6e40518c3a0b17e5d94a26`.","examples":["9f2c41ab7d6e40518c3a0b17e5d94a26"]}}],"responses":{"200":{"description":"The request and its methods","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"request":{"token":"9f2c41ab7d6e40518c3a0b17e5d94a26","subject_type":"locker","subject_id":8801,"amount_cents":1250,"amount":12.5,"currency":"CAD","description":"Locker storage — CAB-A","status":"pending","expires_at":"2026-09-04T18:30:00-04:00","paid_at":null,"pay_url":"https://app.superroute.ca/pay/r/9f2c41ab7d6e40518c3a0b17e5d94a26"},"methods":[{"kind":"wallet","gateway":null,"method":"wallet","label":"Account balance","icon":"fas fa-wallet","badge_color":"secondary","available":true,"reason":null,"completion":"redirect"},{"kind":"gateway","gateway":"stripe","method":"card","label":"Credit / Debit Card","icon":"fas fa-credit-card","badge_color":"primary","completion":"sheet","available":true,"reason":null},{"kind":"gateway","gateway":"alphapay","method":"wechat_pay","label":"AlphaPay WeChat Pay","icon":"fab fa-weixin","badge_color":"success","available":true,"reason":null,"completion":"redirect"}]}}}},"404":{"description":"Unknown token, or it belongs to another payer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"NOT_FOUND","message":"Unknown item"}}}},"403":{"description":"The app assignment is not effective for this customer"}}}},"/v1/apps/{appCode}/clients/{clientCode}/pay/requests/{publicToken}/pay":{"post":{"tags":["Platform Apps"],"summary":"Pay a payment request","description":"Start paying. A wallet payment finishes here and comes back with paid true. A gateway payment does not: it comes back with a `next` object saying how the payer finishes. `next.kind` is the only field worth branching on — `redirect` means open `next.checkout_url`, `sheet` means hand `next.client_secret` to the provider's mobile SDK, initialised with `next.publishable_key`. The sheet is where Apple Pay and Google Pay appear: they are not separate methods to switch on beside card, they are surfaces the SDK offers on that same payment when the device supports them. Either way the money is not collected until the gateway says so — poll the request until its status becomes paid. Pass method wallet with no gateway to spend the balance; otherwise pass the gateway code and the method it offers. Throttled to 10 requests a minute: it moves money, or calls out to somebody who does.","operationId":"platformAppPay","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"publicToken","in":"path","required":true,"description":"The request's own opaque token, 32 hex characters.\n\n**Details:** Required · Type `string` · pattern `^[0-9a-f]{32}$`.\n\n**Example:** `9f2c41ab7d6e40518c3a0b17e5d94a26`.","schema":{"type":"string","pattern":"^[0-9a-f]{32}$","description":"The request's own opaque token, 32 hex characters.\n\n**Details:** Required · Type `string` · pattern `^[0-9a-f]{32}$`.\n\n**Example:** `9f2c41ab7d6e40518c3a0b17e5d94a26`.","examples":["9f2c41ab7d6e40518c3a0b17e5d94a26"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["method"],"properties":{"method":{"type":"string","maxLength":32,"description":"**Required.**\n\nMethod. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · maxLength `32`.\n\n**Example:** `wallet`.","examples":["wallet"]},"gateway":{"type":["string","null"],"maxLength":32,"description":"Gateway. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · maxLength `32`.\n\n**Example:** `alphapay`.","examples":["alphapay"]}}},"example":{"method":"wallet"}}}},"responses":{"200":{"description":"Settled from the balance, or told how to finish (redirect or native sheet)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"paid":true,"request":{"token":"9f2c41ab7d6e40518c3a0b17e5d94a26","subject_type":"locker","subject_id":8801,"amount_cents":1250,"amount":12.5,"currency":"CAD","description":"Locker storage — CAB-A","status":"paid","expires_at":"2026-09-04T18:30:00-04:00","paid_at":"2026-09-04T18:12:07-04:00","pay_url":"https://app.superroute.ca/pay/r/9f2c41ab7d6e40518c3a0b17e5d94a26"},"methods":[{"kind":"wallet","gateway":null,"method":"wallet","label":"Account balance","icon":"fas fa-wallet","badge_color":"secondary","available":true,"reason":null,"completion":"redirect"},{"kind":"gateway","gateway":"stripe","method":"card","label":"Credit / Debit Card","icon":"fas fa-credit-card","badge_color":"primary","completion":"sheet","available":true,"reason":null},{"kind":"gateway","gateway":"alphapay","method":"wechat_pay","label":"AlphaPay WeChat Pay","icon":"fab fa-weixin","badge_color":"success","available":true,"reason":null,"completion":"redirect"}],"next":{"kind":"sheet","checkout_url":null,"client_secret":"pi_3Qx0example_secret_9fA2","publishable_key":"pk_live_51Hxxxxxx","merchant_country":"CA","merchant_display_name":"Waypoint Logistics"}}}}},"422":{"description":"Expired, refused, or a gateway that cannot be used here","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"CHARGE_FAILED","message":"The payment could not be completed. Please try again."}}}},"403":{"description":"The app assignment is not effective for this customer"}}}},"/v1/apps/{appCode}/clients/{clientCode}/wallet":{"get":{"tags":["Platform Apps"],"summary":"Get the app-scoped customer wallet","description":"Returns the selected Client's existing customer balance, credit allowance, remaining credit, available spending amount, online-payment policy and tax mode. This endpoint does not maintain a separate App balance.","operationId":"platformAppWallet","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"locale","in":"query","required":false,"schema":{"type":"string","description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`.","examples":["en"]},"description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"Existing Superroute customer wallet summary","content":{"application/json":{"schema":{"type":"object","required":["result","data"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"**Required.**\n\nData. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"currency":"CAD","balance":"-25.00","credit_limit":"100.00","credit_used":"25.00","credit_remaining":"75.00","available_to_spend":"75.00","online_payment":{"available":true,"minimum_top_up":"1.00","maximum_top_up":"300.00"},"tax":{"mode":"fixed_tax_zone"}}}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Customer, Client assignment or wallet capability denied"}}}},"/v1/apps/{appCode}/clients/{clientCode}/wallet/transactions":{"get":{"tags":["Platform Apps"],"summary":"List the customer wallet ledger","description":"Returns Client- and customer-scoped entries from the existing transactions ledger, supplemented with matching payment metadata. Adjustments remain normal transaction entries.","operationId":"platformAppWalletTransactions","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["payment","credit","adjustment","charge","refund"],"description":"Category filter. For wallet transactions: payment / credit / adjustment / charge / refund.\n\nCategory filter. For wallet transactions: payment / credit / adjustment / charge / refund.\n\nEnum values (from deployed code):\n- `payment` — Customer payment into wallet\n- `credit` — Manual / promotional credit\n- `adjustment` — Balance adjustment\n- `charge` — Charge against wallet\n- `refund` — Refund back to wallet / payment method\n\n**Details:** Optional · Type `string`.","x-enumDescriptions":["Customer payment into wallet","Manual / promotional credit","Balance adjustment","Charge against wallet","Refund"]},"description":"Category filter. For wallet transactions: payment / credit / adjustment / charge / refund.\n\nCategory filter. For wallet transactions: payment / credit / adjustment / charge / refund.\n\nEnum values (from deployed code):\n- `payment` — Customer payment into wallet\n- `credit` — Manual / promotional credit\n- `adjustment` — Balance adjustment\n- `charge` — Charge against wallet\n- `refund` — Refund back to wallet / payment method\n\n**Details:** Optional · Type `string`."},{"name":"status","in":"query","required":false,"schema":{"type":"integer","enum":[0,1,2,3],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — Pending\n- `1` — Completed\n- `2` — Failed\n- `3` — Cancelled\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["Pending","Completed","Failed","Cancelled"]},"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — Pending\n- `1` — Completed\n- `2` — Failed\n- `3` — Cancelled\n\n**Details:** Optional · Type `integer`."},{"name":"type","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Optional · Type `integer` · min `0`."},"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Optional · Type `integer` · min `0`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `100`."},"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `100`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."}],"responses":{"200":{"description":"Paginated ledger","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"items":[{"id":501,"category":"payment","amount":"50.00","balance_effect":"50.00","direction":"credit","payment":{"gateway":"alphapay","method":"wechat_pay"}}],"pagination":{"page":1,"per_page":20,"total":1}}}}}},"403":{"description":"Wallet transaction capability denied"},"422":{"description":"Invalid filter or pagination"}}}},"/v1/apps/{appCode}/clients/{clientCode}/wallet/payment-methods":{"get":{"tags":["Platform Apps"],"summary":"List Client-approved wallet payment methods","description":"Returns only configured, App-approved gateway methods and masked saved instruments. Gateway credentials and processor secrets are never exposed.","operationId":"platformAppWalletPaymentMethods","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"locale","in":"query","required":false,"schema":{"type":"string","description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`.","examples":["en"]},"description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"Configured and masked saved methods","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"configured_methods":[{"id":"alphapay:wechat_pay","display_name":"WeChat Pay","supports_top_up":true,"maximum_amount":"300.00"}],"saved_methods":[{"id":701,"brand":"visa","last_four":4242,"is_default":true}]}}}}},"403":{"description":"Wallet payment-method capability denied"}}}},"/v1/apps/{appCode}/clients/{clientCode}/wallet/tax-preview":{"post":{"tags":["Platform Apps"],"summary":"Preview configured customer tax","description":"Uses the Client's existing tax zones and the customer's fixed, billing-address or service-address tax mode. The preview does not write a transaction.","operationId":"platformAppWalletTaxPreview","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","format":"double","minimum":0,"description":"**Required.**\n\nAmount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`, format `double` · min `0`."},"country":{"type":["string","null"],"description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string` · Nullable."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"postcode":{"type":["string","null"],"description":"Postal / ZIP code.\n\n**Details:** Type `string` · Nullable."}}},"example":{"amount":100,"country":"Canada","province":"Ontario","postcode":"M5V 2T6"}}}},"responses":{"200":{"description":"Calculated tax preview","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"subtotal":"100.00","total_tax":"13.00","total":"113.00","tax_zone_id":20,"tax_details":[{"name":"HST","rate":"13.000","amount":"13.00"}]}}}}},"403":{"description":"Wallet tax capability denied"},"422":{"description":"Invalid amount or address"}}}},"/v1/apps/{appCode}/clients/{clientCode}/wallet/top-ups":{"post":{"tags":["Platform Apps"],"summary":"Create an idempotent customer wallet top-up","description":"Creates a payment through a Client-configured gateway. The operation record provides idempotency and payment orchestration only; successful settlement is written to the existing payments and transactions ledger by the normal verified gateway callback.","operationId":"platformAppWalletCreateTopUp","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"Idempotency-Key","in":"header","required":true,"description":"Client-generated stable key, 16 to 100 characters\n\n**Details:** Required · Type `string`.\n\n**Example:** `6ba7b810-9dad-11d1-80b4-00c04fd430c8`.","schema":{"type":"string","description":"Client-generated stable key, 16 to 100 characters\n\n**Details:** Required · Type `string`.\n\n**Example:** `6ba7b810-9dad-11d1-80b4-00c04fd430c8`.","examples":["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id","amount"],"properties":{"payment_method_id":{"type":"string","pattern":"^[a-z0-9_-]+:[a-z0-9_-]+$","description":"**Required.**\n\nPayment method id. Identifier referencing the related record.\n\n**Details:** Type `string` · pattern `^[a-z0-9_-]+:[a-z0-9_-]+$`."},"amount":{"type":"number","format":"double","minimum":0.01,"description":"**Required.**\n\nAmount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`, format `double` · min `0.01`."},"locale":{"type":["string","null"],"description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Type `string` · Nullable."}}},"example":{"payment_method_id":"alphapay:wechat_pay","amount":50,"locale":"en"}}}},"responses":{"200":{"description":"Previously created operation replayed"},"201":{"description":"Top-up payment created","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"id":7001,"status":"pending","amount":"50.00","currency":"CAD","next_action":{"type":"qr_code","value":"weixin://pay/7001"}}}}}},"403":{"description":"Top-up, online payment, App method or amount denied"},"409":{"description":"Idempotency key reused with different input"},"422":{"description":"Invalid amount, method or idempotency key"},"502":{"description":"Payment gateway rejected the creation request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/wallet/top-ups/{operationId}":{"get":{"tags":["Platform Apps"],"summary":"Get a wallet top-up status","description":"Returns only an operation owned by the authenticated customer and selected App-Client assignment, reconciled against the existing payment and transaction records.","operationId":"platformAppWalletTopUpStatus","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"operationId","in":"path","required":true,"schema":{"type":"integer","minimum":1,"description":"Operation id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer` · min `1`.\n\n**Example:** `7001`.","examples":[7001]},"description":"Operation id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer` · min `1`.\n\n**Example:** `7001`."}],"responses":{"200":{"description":"Current top-up status","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"id":7001,"status":"succeeded","amount":"50.00","currency":"CAD","transaction_id":501}}}}},"403":{"description":"Wallet top-up capability denied"},"404":{"description":"Operation not found in this App, Client and customer context"}}}},"/v1/third-party-delivery/locker-scopes":{"get":{"tags":["ThirdPartyDelivery"],"summary":"List partner locker scopes","description":"Returns active platform grants, partner-managed child scopes, and current eligible-location counts for the authenticated provider.","operationId":"partnerLockerScopes","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Locker scopes"},"403":{"description":"LOCKER_ACCESS_DISABLED or LOCKER_PERMISSION_DENIED"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}},"post":{"tags":["ThirdPartyDelivery"],"summary":"Create a partner locker scope","operationId":"createPartnerLockerScope","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["parent_scope_group_id","name","access_mode"],"properties":{"parent_scope_group_id":{"type":"integer","description":"**Required.**\n\nParent scope group id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","maxLength":100,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `100`."},"access_mode":{"type":"string","enum":["scope_any","restricted_locations"],"description":"**Required.**\n\nPartner locker scope access mode.\n\nEnum values (from deployed code):\n- `scope_any` — Any locker in the partner scope may be used\n- `restricted_locations` — Only listed locations in the scope may be used\n\n**Details:** Type `string`.","x-enumDescriptions":["Any locker in the partner scope","Only listed locations"]},"location_ids":{"type":"array","items":{"type":"integer","description":"Location ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Location ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"rules":{"type":"object","description":"Rules. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"parent_scope_group_id":12,"name":"Downtown evening lockers","access_mode":"restricted_locations","location_ids":[101,102],"rules":{"version":1,"type":"group","combinator":"all","children":[]}}}}},"responses":{"201":{"description":"Scope created"},"403":{"description":"LOCKER_PERMISSION_DENIED or LOCKER_SCOPE_DENIED"},"404":{"description":"LOCKER_SCOPE_NOT_FOUND"},"422":{"description":"Invalid scope definition"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-scopes/{scopeId}":{"patch":{"tags":["ThirdPartyDelivery"],"summary":"Update a partner locker scope","operationId":"updatePartnerLockerScope","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"scopeId","required":true,"schema":{"type":"integer","description":"Scope id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Scope id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"parent_scope_group_id":{"type":"integer","description":"Parent scope group id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"access_mode":{"type":"string","enum":["scope_any","restricted_locations"],"description":"Partner locker scope access mode.\n\nEnum values (from deployed code):\n- `scope_any` — Any locker in the partner scope may be used\n- `restricted_locations` — Only listed locations in the scope may be used\n\n**Details:** Type `string`.","x-enumDescriptions":["Any locker in the partner scope","Only listed locations"]},"location_ids":{"type":"array","items":{"type":"integer","description":"Location ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Location ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"rules":{"type":"object","description":"Rules. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"Scope updated"},"403":{"description":"LOCKER_SCOPE_DENIED"},"404":{"description":"LOCKER_SCOPE_NOT_FOUND"},"422":{"description":"Invalid scope definition"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}},"delete":{"tags":["ThirdPartyDelivery"],"summary":"Disable a partner locker scope","operationId":"disablePartnerLockerScope","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"scopeId","required":true,"schema":{"type":"integer","description":"Scope id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Scope id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Scope disabled"},"403":{"description":"LOCKER_PERMISSION_DENIED"},"404":{"description":"LOCKER_SCOPE_NOT_FOUND"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-deliveries":{"get":{"tags":["ThirdPartyDelivery"],"summary":"List partner locker deliveries","description":"Lists delivery-code aggregates. Full access codes are never returned. Authorized provider users receive the order-level pickup code after successful settlement.","operationId":"partnerLockerDeliveries","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"external_order_id","schema":{"type":"string","description":"Merchant / upstream order reference stored on the Superroute order.\n\n**Details:** Type `string`."},"description":"Merchant / upstream order reference stored on the Superroute order.\n\n**Details:** Type `string`."},{"in":"query","name":"status","schema":{"type":"string","enum":["draft","active","at_locker","opening","awaiting_confirmation","failed_retryable","failed_attention","delivered","picked_up","expired","cancelled","failed"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `draft` — Draft assignment\n- `active` — Active at locker network\n- `at_locker` — Parcel is at the locker\n- `opening` — Door open in progress\n- `awaiting_confirmation` — Waiting for confirmation\n- `failed_retryable` — Failed but may be retried\n- `failed_attention` — Failed — needs manual attention\n- `delivered` — Delivered into locker\n- `picked_up` — Picked up by recipient\n- `expired` — Expired without pickup\n- `cancelled` — Cancelled\n- `failed` — Terminal failure\n\n**Details:** Type `string`.","x-enumDescriptions":["Draft assignment","Active at locker network","Parcel is at the locker","Door open in progress","Waiting for confirmation","Failed but may be retried","Failed — needs manual attention","Delivered into locker","Picked up by recipient","Expired without pickup","Cancelled","Terminal failure"]},"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `draft` — Draft assignment\n- `active` — Active at locker network\n- `at_locker` — Parcel is at the locker\n- `opening` — Door open in progress\n- `awaiting_confirmation` — Waiting for confirmation\n- `failed_retryable` — Failed but may be retried\n- `failed_attention` — Failed — needs manual attention\n- `delivered` — Delivered into locker\n- `picked_up` — Picked up by recipient\n- `expired` — Expired without pickup\n- `cancelled` — Cancelled\n- `failed` — Terminal failure\n\n**Details:** Type `string`."},{"in":"query","name":"date_from","schema":{"type":"string","format":"date","description":"Date from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Date from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"date_to","schema":{"type":"string","format":"date","description":"Date to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Date to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"mock","description":"Environment filter: true lists sandbox deliveries only, false lists production deliveries only; omit for both.\n\n**Details:** Type `boolean`.","schema":{"type":"boolean","description":"Environment filter: true lists sandbox deliveries only, false lists production deliveries only; omit for both.\n\n**Details:** Type `boolean`."}},{"in":"query","name":"per_page","schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `50` · min `1` · max `100`."},"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `50` · min `1` · max `100`."}],"responses":{"200":{"description":"Paginated locker deliveries with masked access codes and delivered pickup results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerLockerDeliveryListEnvelope"},"example":{"result":true,"code":"OK","message":"Locker deliveries listed.","data":{"deliveries":[{"delivery_no":"PLD-01J2XYZ","external_order_id":"FOOD-1001","status":"delivered","pickup_status":"ready","requested_package_count":2,"actual_package_count":1,"failed_package_count":1,"partial_delivery":true,"associated_package_group_id":551,"pickup_code":"P1K2UP","ready_package_count":1,"remaining_package_count":1,"delivered_location":{"id":101,"name":"Downtown Locker"},"packages":[{"sequence":1,"external_package_id":"BAG-1","status":"confirmed","inventory_id":9012,"associated_package_group_item_id":552,"final_shelf_id":201,"final_grid_id":301,"final_shelf_code":"L1","final_compartment_number":12,"final_pickup_locker_number":3,"final_pickup_locker_code":"L1-3","smart_locker_log_id":401}]}],"pagination":{"current_page":1,"last_page":1,"per_page":50,"total":1}}}}}},"403":{"description":"LOCKER_PERMISSION_DENIED"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}},"post":{"tags":["ThirdPartyDelivery"],"summary":"Create a partner locker delivery code","description":"Creates one order-level unified code, package intents, and a location-level capacity reservation in one transaction. An identical idempotent replay returns the original result. The recipient pickup code is minted in the same transaction and returned as pickup_code, so the partner can announce one code to the recipient from the moment the task exists; it is the same code the open response and the doors_opened / delivered webhooks carry, and it becomes usable at the cabinet once the driver confirms the deposit. A task cancelled or expired before any deposit releases the code.","operationId":"createPartnerLockerDelivery","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","maxLength":191,"description":"Idempotency key. Stable machine-readable code.\n\n**Details:** Required · Type `string` · maxLength `191`."},"description":"Idempotency key. Stable machine-readable code.\n\n**Details:** Required · Type `string` · maxLength `191`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["external_order_id","recipient","platform_scope_group_id"],"properties":{"external_order_id":{"type":"string","maxLength":191,"description":"**Required.**\n\nMerchant / upstream order reference stored on the Superroute order.\n\n**Details:** Type `string` · maxLength `191`."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"external_driver_id":{"type":["string","null"],"description":"External driver id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"recipient":{"type":"object","description":"**Required.**\n\nExactly one of phone or email.\n\n**Details:** Type `object`.","properties":{"phone":{"type":"string","description":"Phone number used for OTP or contact.\n\n**Details:** Type `string`."},"email":{"type":"string","format":"email","description":"Account email address.\n\n**Details:** Type `string`, format `email`."}}},"platform_scope_group_id":{"type":"integer","description":"**Required.**\n\nPlatform scope group id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"partner_scope_group_id":{"type":["integer","null"],"description":"Partner scope group id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"access_mode":{"type":"string","enum":["scope_any","restricted_locations"],"default":"scope_any","description":"Partner locker scope access mode.\n\nEnum values (from deployed code):\n- `scope_any` — Any locker in the partner scope may be used\n- `restricted_locations` — Only listed locations in the scope may be used\n\n**Details:** Type `string` · Default: `scope_any`.","x-enumDescriptions":["Any locker in the partner scope","Only listed locations"]},"restricted_location_ids":{"type":"array","items":{"type":"integer","description":"Restricted location ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Location ids the order may use, when access_mode is restricted_locations. The ids must come from the locker location list requested in the same mode as the mock flag on this request, otherwise the order is rejected with LOCKER_NO_CABINET_FOR_MODE even though the location itself is authorized.\n\n**Details:** Type `array`, items `integer`."},"package_count":{"type":"integer","minimum":1,"maximum":50,"default":1,"description":"Package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Default: `1` · min `1` · max `50`."},"packages":{"type":"array","items":{"type":"object","properties":{"carrier_package_no":{"type":"string","maxLength":64,"description":"A package the carrier pre-advised, by the package number the carrier-packages API reports (`{carrier_id}-{sequence}`). The task then deposits that package instead of describing a new one: it is pinned to the package's pickup location (access_mode restricted_locations with that location only), the package keeps its number and pickup code, staff cannot shelve it and the carrier cannot cancel or reroute it while the task is live, and settlement shelves the existing row in place. Measurements not repeated here are taken from the pre-advice. Either every package of the task names one or none does (422 CARRIER_PACKAGE_MIX_NOT_ALLOWED); packages waiting at different locations, or a restricted_location_ids that differs from theirs, are refused (422 CARRIER_PACKAGE_LOCATION_MISMATCH); the packages of one pre-advised order group must all be named and nothing else (409 CARRIER_PACKAGE_NOT_ADOPTABLE); a shelved or collected package, or one held by another live task, is refused (409 CARRIER_PACKAGE_NOT_ADOPTABLE / CARRIER_PACKAGE_CLAIMED); an unknown number is 404 CARRIER_PACKAGE_NOT_FOUND.\n\n**Details:** Type `string` · maxLength `64`."},"external_package_id":{"type":"string","description":"External package id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"length":{"type":"number","exclusiveMinimum":0,"description":"Length dimension.\n\n**Details:** Type `number` · exclusiveMin `0`."},"width":{"type":"number","exclusiveMinimum":0,"description":"Width dimension.\n\n**Details:** Type `number` · exclusiveMin `0`."},"height":{"type":"number","exclusiveMinimum":0,"description":"Height dimension.\n\n**Details:** Type `number` · exclusiveMin `0`."},"dimension_unit":{"type":"string","enum":["mm","cm","m","ft","inch"],"description":"Optional, like the three edges. The size check runs only when all three edges and the unit are given; anything short of the four is carried as unmeasured and the package is placed on availability alone. A value that is sent must still be a positive number in a supported unit, otherwise 422 LOCKER_DIMENSIONS_INVALID.\n\nEnum values:\n- `mm` — Millimetres\n- `cm` — Centimetres\n- `m` — Metres\n- `ft` — Feet\n- `inch` — Inches\n\n**Details:** Type `string`.","x-enumDescriptions":["Millimetres","Centimetres","Metres","Feet","Inches"]},"weight":{"type":"number","exclusiveMinimum":0,"description":"Optional declared weight, compared against each compartment's load limit. Needs weight_unit; a compartment with no limit of its own never refuses on weight.\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_unit":{"type":"string","enum":["kg","g","lb","oz"],"description":"Required when weight is given, and vice versa; otherwise 422 LOCKER_WEIGHT_INVALID.\n\nAllowed values: `kg` · `g` · `lb` · `oz`.\n\n**Details:** Type `string`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"expires_in_minutes":{"type":"integer","minimum":1,"maximum":1440,"default":120,"description":"Expires in minutes. Field in the JSON request body.\n\n**Details:** Type `integer` · Default: `120` · min `1` · max `1440`."},"display_name":{"type":"string","maxLength":100,"description":"Display name. Human-readable label.\n\n**Details:** Type `string` · maxLength `100`."},"mock":{"type":"boolean","default":false,"description":"Sandbox flag: the delivery is fulfilled only by the provider's mock lockers and never consumes real locker capacity. The mode also decides which locations can serve the order — sandbox orders can only use locations holding a mock cabinet, live orders only locations holding a production cabinet. Call the locker location endpoints with the same value of this flag to get the matching location ids; mixing a sandbox order with a live-only location (or the reverse) is rejected with LOCKER_NO_CABINET_FOR_MODE.\n\n**Details:** Type `boolean` · Default: `false`."},"delivery_mode":{"type":"string","enum":["standard","grouped"],"default":"standard","description":"How the packages of a multi-package order are placed. standard (default; the only behaviour before this field existed): compartments are taken wherever they are free at the location. grouped: the order was announced as one whose packages belong together - compartments are chosen in one cabinet when a cabinet at the location can take every package, otherwise in as few cabinets of that location as possible, never at another location; the one pickup code opens every compartment. Grouping is a placement preference, never a gate: when the location is short of space the doors that can open still open and the driver may confirm a partial delivery exactly as for a standard task. After a partial delivery of a grouped task the undelivered packages automatically become a follow-up delivery (same order, same recipient, same scope and mode, only the remaining packages) with its own access code: the confirm response returns it as split_delivery, and the two tasks reference each other through split_from_delivery_no / split_delivery_no.\n\nAllowed values: `standard` · `grouped`.\n\n**Details:** Type `string` · Default: `standard`."}}},"example":{"external_order_id":"FOOD-20260714-1001","external_driver_id":"DRIVER-77","recipient":{"phone":"+14165550123"},"platform_scope_group_id":12,"partner_scope_group_id":19,"access_mode":"restricted_locations","restricted_location_ids":[101,102],"packages":[{"external_package_id":"BAG-1","length":30,"width":20,"height":15,"dimension_unit":"cm","weight":2.5,"weight_unit":"kg"}],"expires_in_minutes":120}}}},"responses":{"200":{"description":"Idempotent replay"},"201":{"description":"Delivery code created"},"403":{"description":"LOCKER_ACCESS_DISABLED, LOCKER_PERMISSION_DENIED, or LOCKER_SCOPE_DENIED"},"404":{"description":"LOCKER_SCOPE_NOT_FOUND"},"409":{"description":"LOCKER_CAPACITY_UNAVAILABLE (compartments that could hold the order exist but none is free), LOCKER_CAPACITY_SIZE_EXCEEDED / LOCKER_CAPACITY_WEIGHT_EXCEEDED / LOCKER_CAPACITY_SIZE_AND_WEIGHT_EXCEEDED (no compartment at the authorized locations could ever hold the declared package, whatever empties — retrying will not help), LOCKER_NO_CABINET_FOR_MODE (no authorized location holds a cabinet for the requested mock / live mode), LOCKER_DELIVERY_ALREADY_ACTIVE, or IDEMPOTENCY_CONFLICT"},"422":{"description":"Contact, package, dimension (LOCKER_DIMENSIONS_INVALID), weight (LOCKER_WEIGHT_INVALID), text length, TTL, or empty-scope validation error"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-deliveries/{deliveryNo}":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Get a partner locker delivery","description":"An authorized active detail may include the complete access code. After delivery, authorized provider users receive the independent group pickup code and confirmed package results. Terminal details never expose either code.","operationId":"partnerLockerDelivery","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deliveryNo","required":true,"schema":{"type":"string","description":"Delivery no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`.\n\n**Example:** `PLD-01J2XYZ`.","examples":["PLD-01J2XYZ"]},"description":"Delivery no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`.\n\n**Example:** `PLD-01J2XYZ`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Locker delivery detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerLockerDeliveryEnvelope"},"example":{"result":true,"code":"OK","message":"Locker delivery found.","data":{"delivery_no":"PLD-01J2XYZ","external_order_id":"FOOD-1001","status":"delivered","pickup_status":"ready","requested_package_count":2,"actual_package_count":1,"failed_package_count":1,"partial_delivery":true,"associated_package_group_id":551,"pickup_code":"P1K2UP","ready_package_count":1,"remaining_package_count":1,"delivered_location":{"id":101,"name":"Downtown Locker"},"packages":[{"sequence":1,"external_package_id":"BAG-1","status":"confirmed","inventory_id":9012,"associated_package_group_item_id":552,"final_shelf_id":201,"final_grid_id":301,"final_shelf_code":"L1","final_compartment_number":12,"final_pickup_locker_number":3,"final_pickup_locker_code":"L1-3","smart_locker_log_id":401}]}}}}},"403":{"description":"LOCKER_PERMISSION_DENIED"},"404":{"description":"Delivery not found"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-deliveries/{deliveryNo}/cancel":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Cancel a partner locker delivery","description":"Cancels an unconsumed delivery and releases its capacity reservation. Repeated cancellation returns the current cancelled result.","operationId":"cancelPartnerLockerDelivery","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deliveryNo","required":true,"schema":{"type":"string","description":"Delivery no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"description":"Delivery no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Delivery cancelled or cancellation replayed"},"404":{"description":"Delivery not found"},"409":{"description":"LOCKER_DELIVERY_ALREADY_CONSUMED"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-locations":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Find eligible locker locations near an address or coordinates","description":"Returns the provider's eligible locker locations sorted by distance from a query point, so partners can pick a location_id before creating a delivery or opening doors remotely. Provide either latitude+longitude or a free-text address (optionally with city/province/country/postcode) that the platform geocodes. Results are limited to locations covered by the provider's active platform grants (optionally filtered to one grant / partner scope) that have at least one matching locker; with mock=true only the provider's own mock lockers count. Each location uses the standard address shape: address_1, address_2, city, province, country, postcode, plus id, code, name, latitude, longitude, distance_km, locker_count, and platform_scope_group_ids. online_only defaults to true: cabinets the provider reports as offline are not counted, and a location whose every cabinet is offline is left out of the listing — pass online_only=false to list every eligible cabinet and skip the device-state lookup entirely. A cabinet whose provider cannot be reached at all is unknown, not offline, and stays listed. include_lockers=true adds a lockers[] array to each location naming its cabinets and their state; online_locker_count/offline_locker_count/unknown_locker_count are null when neither option asked for device state.","operationId":"partnerLockerNearbyLocations","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"address","required":false,"schema":{"type":"string","maxLength":500,"description":"Free-text address; required when latitude/longitude are not supplied.\n\n**Details:** Optional · Type `string` · maxLength `500`."},"description":"Free-text address; required when latitude/longitude are not supplied.\n\n**Details:** Optional · Type `string` · maxLength `500`."},{"in":"query","name":"city","required":false,"schema":{"type":"string","description":"City / locality.\n\n**Details:** Optional · Type `string`."},"description":"City / locality.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"province","required":false,"schema":{"type":"string","description":"Province / state / region.\n\n**Details:** Optional · Type `string`."},"description":"Province / state / region.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"country","required":false,"schema":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Optional · Type `string`."},"description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"postcode","required":false,"schema":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Optional · Type `string`."},"description":"Postal / ZIP code.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"latitude","required":false,"schema":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Optional · Type `number` · min `-90` · max `90`."},"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Optional · Type `number` · min `-90` · max `90`."},{"in":"query","name":"longitude","required":false,"schema":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Optional · Type `number` · min `-180` · max `180`."},"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Optional · Type `number` · min `-180` · max `180`."},{"in":"query","name":"platform_scope_group_id","required":false,"schema":{"type":"integer","description":"Platform scope group id. Identifier referencing the related record.\n\n**Details:** Optional · Type `integer`."},"description":"Platform scope group id. Identifier referencing the related record.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"partner_scope_group_id","required":false,"schema":{"type":"integer","description":"Partner scope group id. Identifier referencing the related record.\n\n**Details:** Optional · Type `integer`."},"description":"Partner scope group id. Identifier referencing the related record.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"mock","required":false,"schema":{"type":"boolean","default":false,"description":"Return sandbox locations instead of production ones. A location is only listed when it holds a cabinet of the matching kind, so the ids returned here are exactly the ids a delivery created with the same mock value can use.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},"description":"Return sandbox locations instead of production ones. A location is only listed when it holds a cabinet of the matching kind, so the ids returned here are exactly the ids a delivery created with the same mock value can use.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},{"in":"query","name":"online_only","required":false,"schema":{"type":"boolean","default":true,"description":"Only count cabinets the platform can currently reach. Default true: an offline cabinet cannot take a parcel, and a location whose every cabinet is offline is left out of the listing entirely. Pass false to list every eligible cabinet regardless of device state (and to skip the device-state lookup). A cabinet whose provider cannot be reached at all is 'unknown', not offline, and stays listed.\n\n**Details:** Optional · Type `boolean` · Default: `true`."},"description":"Only count cabinets the platform can currently reach. Default true: an offline cabinet cannot take a parcel, and a location whose every cabinet is offline is left out of the listing entirely. Pass false to list every eligible cabinet regardless of device state (and to skip the device-state lookup). A cabinet whose provider cannot be reached at all is 'unknown', not offline, and stays listed.\n\n**Details:** Optional · Type `boolean` · Default: `true`."},{"in":"query","name":"include_lockers","required":false,"schema":{"type":"boolean","default":false,"description":"Add a lockers[] array to every location listing the cabinets it holds (shelf_id, device_id, name, status, online, mock, compartment_count). Off by default because it needs a device-state lookup.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},"description":"Add a lockers[] array to every location listing the cabinets it holds (shelf_id, device_id, name, status, online, mock, compartment_count). Off by default because it needs a device-state lookup.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `10` · min `1` · max `50`."},"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `10` · min `1` · max `50`."}],"responses":{"200":{"description":"Nearby eligible locations sorted by distance (locations without coordinates sort last with distance_km null)","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Nearby locker locations listed.","data":{"origin":{"latitude":43.6532,"longitude":-79.3832,"geocoded":true},"locations":[{"id":101,"name":"Downtown Locker","code":"LOC-A1B2C3","address_1":"100 Front St W","address_2":"Unit 5","city":"Toronto","province":"ON","country":"Canada","postcode":"M5J 1E3","latitude":43.6426,"longitude":-79.3871,"distance_km":1.22,"locker_count":2,"platform_scope_group_ids":[12]}]}},"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"origin":{"type":"object","properties":{"latitude":{"type":"number","description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`."},"longitude":{"type":"number","description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`."},"geocoded":{"type":"boolean","description":"Geocoded. Stable machine-readable code.\n\n**Details:** Type `boolean`."}},"description":"Origin. Field in the JSON request body.\n\n**Details:** Type `object`."},"locations":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/PartnerLockerScopeLocation"},{"type":"object","properties":{"distance_km":{"type":["number","null"],"description":"Distance km. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable."}}}]},"description":"Locations. Field in the JSON request body.\n\n**Details:** Type `array`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"LOCKER_ACCESS_DISABLED or LOCKER_PERMISSION_DENIED"},"404":{"description":"LOCKER_SCOPE_NOT_FOUND (unknown or inactive grant / partner scope)"},"422":{"description":"LOCKER_INPUT_INVALID: address missing (api_address_required) or not resolvable to coordinates (api_address_unresolved)"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-deliveries/{deliveryNo}/rotate-code":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Rotate a delivery's access or pickup code","description":"Replaces one of the delivery's codes with a freshly minted one; the old code dies the instant the new one is written, on every cabinet and API entry point alike. code_type access rotates the courier delivery code and is allowed only while the code is unused (draft / active); code_type pickup rotates the recipient pickup code and is allowed only once the deposit is settled and not fully collected (group ready / partially picked up). The new code is revealed only in this response. notify_recipient (pickup only) re-sends the recipient notification carrying the new code. The delivery must belong to the calling provider. The rotation also emits the partner_locker.delivery.code_rotated webhook, which names what happened but never carries the code.","operationId":"rotatePartnerLockerDeliveryCode","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deliveryNo","required":true,"schema":{"type":"string","description":"Delivery no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"description":"Delivery no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code_type"],"properties":{"code_type":{"type":"string","enum":["access","pickup"],"description":"**Required.**\n\nWhich code to rotate.\n\nAllowed values: `access` · `pickup`.\n\n**Details:** Type `string`."},"notify_recipient":{"type":"boolean","description":"pickup only: re-send the recipient notification carrying the new code. Default false.\n\n**Details:** Type `boolean`."}}},"example":{"code_type":"access"}}}},"responses":{"200":{"description":"Code rotated; the new code is revealed only in this response","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Code rotated. The previous code is no longer valid.","data":{"delivery_no":"PLD-01J2XYZ","code_type":"access","access_code":"9T4K2M","masked_access_code":"****2M","expires_at":"2026-08-11T16:01:27-04:00"}}}}},"403":{"description":"LOCKER_PERMISSION_DENIED (provider lacks can_generate_codes)"},"404":{"description":"LOCKER_DELIVERY_NOT_FOUND (unknown delivery or a delivery of another provider)"},"409":{"description":"LOCKER_CODE_ROTATION_UNAVAILABLE (the delivery / pickup group state does not allow rotation; the current state is named in the message)"},"422":{"description":"LOCKER_INPUT_INVALID (code_type must be access or pickup)"}}}},"/v1/third-party-delivery/locker-deliveries/open":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Remotely open locker doors for a delivery access code at a location","description":"Opens locker compartments for one of the provider's own delivery access codes at the given location, so the driver does not need to type the code on a terminal. The platform picks an eligible locker cabinet at the location (allocation may span several cabinets there). location_id may be omitted when the code was created for exactly one location (a single restricted location, or a scope snapshot with exactly one eligible location) - it is then inferred. Validates provider ownership, per-provider locker access, and scope eligibility, then allocates compartments and sends the door-open command. Returns a claim_token used to confirm or abort the attempt. Calling confirm is optional for a remote open: the platform settles the deposit by itself as soon as the cabinet has reported every opened door closed again (the delivered webhook then carries confirmed_by = door_close; if the confirmation window lapses with all doors verified closed it is settled with confirmed_by = timeout_door_closed). An explicit confirm afterwards is idempotent and returns the same result. Only a door that stays open, or whose state cannot be verified, still leads to manual attention. From the moment the doors open the response also carries the delivery's recipient pickup_code; the doors_opened webhook announces the same code, and it stays the active code once the courier confirms the deposit (it only becomes usable for pickup after that confirmation). When compartments cannot be opened (failed_retryable or a partial open), the attempt additionally carries `availability` — per-location counts of total / occupied / held (other in-progress deliveries) / blocked (awaiting manual resolution after an abnormal open) / door_open / free compartments — and `failure_hint`, a human-readable explanation of the concrete reason with the next step (resolve blocked compartments, release stale holds, or retry once space frees up; the access code stays valid until it expires). The same lookup abuse guard and rate limits as the terminal apply. For a task created with delivery_mode = grouped, compartments are chosen in one cabinet when a cabinet at the location can take every package, otherwise in as few cabinets of that location as possible (never another location); this is a preference only - when the location is short of space the doors that can open still open and the driver may confirm a partial delivery, after which the undelivered packages automatically become a follow-up delivery (see confirm).","operationId":"openPartnerLockerDelivery","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["access_code"],"properties":{"location_id":{"type":"integer","description":"Target location id (see GET /locker-locations). Optional when the delivery code was created for exactly one location.\n\n**Details:** Type `integer`."},"access_code":{"type":"string","description":"**Required.**\n\nThe delivery access code issued when the delivery was created.\n\n**Details:** Type `string`."}}},"example":{"location_id":101,"access_code":"8Q4W2Z"}}}},"responses":{"200":{"description":"Door open request processed; attempt contains per-compartment results and awaiting_confirmation status on success","content":{"application/json":{"examples":{"opened":{"summary":"Doors opened","value":{"result":true,"code":"OK","message":"Locker door open request processed.","data":{"delivery_no":"PLD-01J2XYZ","claim_token":"b1f9...64chars","location_id":101,"location_name":"Downtown Locker","pickup_code":"7K3M9Q","attempt":{"result":true,"attempt_status":"awaiting_confirmation","requested_count":2,"opened_count":2,"failed_count":0,"partial_success":false,"pickup_code":"7K3M9Q","groups":[{"shelf_name":"LK-A1","locker_identifier":"SL-88231","compartments":[{"package_sequence":1,"compartment_number":12,"grid_id":5011,"pickup_locker_number":3,"pickup_locker_code":"L1-3"},{"package_sequence":2,"compartment_number":15,"grid_id":5014,"pickup_locker_number":6,"pickup_locker_code":"L1-6"}]}],"can_confirm":true,"can_accept_partial":false,"can_abort":true,"can_cancel":false,"message":"All doors opened.","delivery_mode":"standard","failure_code":null}}}}}}}},"403":{"description":"LOCKER_DELIVERY_DISABLED, LOCKER_PERMISSION_DENIED, or LOCKER_SCOPE_DENIED (location outside the delivery's scope snapshot)"},"404":{"description":"LOCKER_LOCATION_UNAVAILABLE (location has no eligible locker for this provider) or LOCKER_DELIVERY_CODE_UNAVAILABLE (unknown code or a code that does not belong to the provider)"},"409":{"description":"LOCKER_DELIVERY_IN_USE, LOCKER_DELIVERY_MANUAL_ATTENTION, or LOCKER_DELIVERY_CODE_UNAVAILABLE (already consumed/expired)"},"422":{"description":"access_code missing, or location_id missing and not inferable (api_location_required)"},"429":{"description":"LOCKER_RATE_LIMITED or LOCKER_DELIVERY_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-deliveries/confirm":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Confirm a remotely opened locker deposit","description":"Settles a remote door-opening attempt after the driver has placed the packages: creates inventory, marks the delivery delivered, and issues the recipient pickup flow. Optional since the platform settles a remote open automatically once every opened door is verified closed; calling it on an attempt the door-close already settled is idempotent and returns the same result, whose confirmed_by names the path that settled (courier_terminal, partner_api, door_close, timeout_door_closed, console). decision must be confirm_all when every requested compartment opened, or accept_partial when only some did. The attempt is identified by claim_token; location_id is an optional consistency check against the attempt's location. For a grouped task (delivery_mode = grouped) settled with accept_partial, the packages left undelivered automatically become a follow-up delivery for the same order and recipient with its own access code; the response carries it as split_delivery (delivery_no, requested_package_count, access_code, expires_at, replayed) and null when nothing was split. The parent reports it as split_delivery_no, the child as split_from_delivery_no.","operationId":"confirmPartnerLockerDelivery","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claim_token","decision"],"properties":{"location_id":{"type":"integer","description":"Optional; must match the attempt's location when provided.\n\n**Details:** Type `integer`."},"claim_token":{"type":"string","description":"**Required.**\n\nThe claim_token returned by the open call.\n\n**Details:** Type `string`."},"decision":{"type":"string","enum":["confirm_all","accept_partial"],"description":"**Required.**\n\nEnum values:\n- `confirm_all` — Confirm every package\n- `accept_partial` — Accept a partial set\n\n**Details:** Type `string`.","x-enumDescriptions":["Confirm every package","Accept a partial set"]}}},"example":{"claim_token":"b1f9...64chars","decision":"confirm_all"}}}},"responses":{"200":{"description":"Deposit settled","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Deposit confirmation processed.","data":{"result":true,"delivery_no":"PLD-01J2XYZ","delivery_status":"delivered","requested_count":2,"opened_count":2,"failed_count":0,"partial_success":false,"associated_package_group_id":551,"pickup_ready":true,"confirmed_by":"partner_api","split_delivery":null,"packages":[{"sequence":1,"external_package_id":"PKG-1","shelf_id":21,"grid_id":5011,"compartment_number":12,"pickup_locker_number":3,"pickup_locker_code":"L1-3"},{"sequence":2,"external_package_id":"PKG-2","shelf_id":21,"grid_id":5014,"compartment_number":15,"pickup_locker_number":6,"pickup_locker_code":"L1-6"}]}}}}},"409":{"description":"LOCKER_DELIVERY_CLAIM_UNAVAILABLE (unknown/expired claim, or location_id mismatch), LOCKER_DELIVERY_DECISION_CONFLICT, or LOCKER_DELIVERY_SETTLEMENT_FAILED"},"422":{"description":"decision missing or not confirm_all/accept_partial"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-deliveries/abort":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Abort a remotely opened locker delivery attempt","description":"Aborts an in-progress remote attempt identified by claim_token (location_id is an optional consistency check). Before any door-open request the delivery is restored for retry and leased compartments are released; after a door has been opened the attempt is flagged for manual attention instead.","operationId":"abortPartnerLockerDelivery","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claim_token"],"properties":{"location_id":{"type":"integer","description":"Optional; must match the attempt's location when provided.\n\n**Details:** Type `integer`."},"claim_token":{"type":"string","description":"**Required.**\n\nClaim token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."}}},"example":{"claim_token":"b1f9...64chars"}}}},"responses":{"200":{"description":"Attempt aborted or flagged for manual attention"},"409":{"description":"LOCKER_DELIVERY_CLAIM_UNAVAILABLE"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-deliveries/reassign":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Reject an opened compartment and re-open a different one (before confirmation)","description":"While an attempt is awaiting confirmation, the courier rejects the compartment opened for one package and the platform re-allocates and re-opens a different one. reason is door_not_open, compartment_occupied, or too_small; too_small forces a strictly larger compartment. Identify the attempt by claim_token and the package by package_sequence. If no suitable compartment remains, that package fails with NO_AVAILABLE_COMPARTMENT and the courier should switch lockers.","operationId":"reassignPartnerLockerDelivery","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claim_token","package_sequence","reason"],"properties":{"location_id":{"type":"integer","description":"Optional; must match the attempt's location when provided.\n\n**Details:** Type `integer`."},"claim_token":{"type":"string","description":"**Required.**\n\nClaim token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."},"package_sequence":{"type":"integer","description":"**Required.**\n\nThe 1-based sequence of the package whose compartment is being rejected.\n\n**Details:** Type `integer`."},"reason":{"type":"string","enum":["door_not_open","compartment_occupied","too_small"],"description":"**Required.**\n\nHuman-readable reason for the action (failure, cancellation, reassignment, etc.).\n\nEnum values:\n- `door_not_open` — Door did not open\n- `compartment_occupied` — Compartment already occupied\n- `too_small` — Compartment too small\n\n**Details:** Type `string`.","x-enumDescriptions":["Door did not open","Compartment already occupied","Compartment too small"]}}},"example":{"claim_token":"b1f9...64chars","package_sequence":1,"reason":"too_small"}}}},"responses":{"200":{"description":"Compartment reassigned; the attempt payload reflects the newly opened compartment"},"409":{"description":"LOCKER_DELIVERY_REASSIGN_UNAVAILABLE (package is not in an opened state) or LOCKER_DELIVERY_CLAIM_UNAVAILABLE"},"422":{"description":"LOCKER_DELIVERY_REASSIGN_REASON_INVALID or LOCKER_INPUT_INVALID (missing package_sequence)"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-deliveries/cancel-placement":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Cancel an opened placement and terminate the delivery (before confirmation)","description":"The courier asserts that nothing was deposited (e.g. wrong locker, or no larger compartment is available). Every compartment opened for this attempt is released and the delivery is terminated as cancelled, emitting a partner_locker.delivery_cancelled webhook. Distinct from abort (which flags manual attention after a door opened) and from the delivery cancel endpoint (which only cancels tasks that never reached a locker).","operationId":"cancelPartnerLockerPlacement","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claim_token"],"properties":{"location_id":{"type":"integer","description":"Optional; must match the attempt's location when provided.\n\n**Details:** Type `integer`."},"claim_token":{"type":"string","description":"**Required.**\n\nClaim token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."}}},"example":{"claim_token":"b1f9...64chars"}}}},"responses":{"200":{"description":"Placement cancelled and delivery terminated"},"409":{"description":"LOCKER_DELIVERY_CLAIM_UNAVAILABLE"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/locker-deliveries/reopen":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Reopen a just-confirmed delivery's compartments to correct a wrong placement","description":"Within the correction window (60 seconds by default) after a drop-off is confirmed, reopens the same compartments the parcels were deposited into so the courier can fix a wrong placement. The delivery stays delivered; only door-open commands are re-issued. Identify the delivery by delivery_no (preferred) or the original access_code. The same correction is available on the locker screen by re-entering the delivery code. Every correction reopen emits a partner_locker.delivery.correction_reopened webhook event to subscribed endpoints with the reopened compartments in the payload.","operationId":"reopenPartnerLockerDelivery","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delivery_no":{"type":"string","description":"The delivery number returned when the delivery was created. Either delivery_no or access_code is required.\n\n**Details:** Type `string`."},"access_code":{"type":"string","description":"The original courier access code, as an alternative to delivery_no.\n\n**Details:** Type `string`."}}},"example":{"delivery_no":"PLD-20260721-000123"}}}},"responses":{"200":{"description":"Compartments reopened for correction","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Correction reopen processed.","data":{"result":true,"correction":true,"delivery_no":"PLD-20260721-000123","delivery_status":"delivered","correction_expires_in":41,"reopened_count":2,"failed_count":0,"groups":[{"shelf_id":12,"shelf_name":"Cabinet A","locker_identifier":"SL-0012","compartments":[{"package_sequence":1,"compartment_number":"A03","grid_id":5011,"pickup_locker_number":3,"pickup_locker_code":"L1-3"},{"package_sequence":2,"compartment_number":"A04","grid_id":5014,"pickup_locker_number":6,"pickup_locker_code":"L1-6"}]}]}}}}},"404":{"description":"LOCKER_DELIVERY_CODE_UNAVAILABLE — unknown delivery or not owned by this provider"},"409":{"description":"LOCKER_DELIVERY_CORRECTION_WINDOW_CLOSED — the correction window has expired; LOCKER_DELIVERY_CORRECTION_UNAVAILABLE — the delivery has no reopenable compartments"},"422":{"description":"LOCKER_INPUT_INVALID — delivery_no or access_code is required"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"},"502":{"description":"LOCKER_DELIVERY_CORRECTION_OPEN_FAILED — no compartment door could be reopened"}}}},"/v1/third-party-delivery/locker-deliveries/pickup-open":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Pickup-stage remote open: open the compartments still holding the provider's delivered packages","description":"Once a drop-off is confirmed the packages sit in locker compartments awaiting pickup. This endpoint lets the partner open those compartments remotely — for example to assist a recipient standing at the locker or to let a courier collect the parcels — provided the goods in the compartments belong to the requesting provider: the delivery (or the pickup code's package group) must be owned by the resolved provider, otherwise the request is refused before any door command is issued. Identify the delivery by delivery_no (preferred) or by the group pickup_code that was issued to the recipient. Every compartment that opens successfully is settled exactly like the locker's own pickup screen settles it: the parcel is stocked out, the group item is marked picked up, and when the last parcel leaves the delivery moves to picked_up and the partner_locker.delivery.picked_up webhook event fires. Compartments that fail to open stay ready and the call can simply be retried for the remainder.","operationId":"pickupOpenPartnerLockerDelivery","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delivery_no":{"type":"string","description":"The delivery number returned when the delivery was created. Either delivery_no or pickup_code is required.\n\n**Details:** Type `string`."},"pickup_code":{"type":"string","description":"The group pickup code issued to the recipient, as an alternative to delivery_no.\n\n**Details:** Type `string`."}}},"example":{"delivery_no":"PLD-20260721-000123"}}}},"responses":{"200":{"description":"Pickup compartments opened and settled","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Pickup door open request processed.","data":{"delivery_no":"PLD-20260721-000123","delivery_status":"picked_up","pickup_status":"completed","location_id":101,"picked_up_count":2,"total_picked_up_count":2,"remaining_package_count":0,"partial_success":false,"opened":[{"inventory_id":9012,"compartment_number":"A03"},{"inventory_id":9013,"compartment_number":"A04"}],"failed":[]}}}}},"404":{"description":"LOCKER_DELIVERY_CODE_UNAVAILABLE — unknown delivery/pickup code or not owned by this provider"},"409":{"description":"LOCKER_PICKUP_NOT_READY — the delivery has no packages awaiting pickup; LOCKER_PICKUP_ALREADY_COMPLETED — every package was already picked up; LOCKER_PICKUP_BUSY — another operation is processing this pickup, retry shortly"},"422":{"description":"LOCKER_INPUT_INVALID — delivery_no or pickup_code is required"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"},"502":{"description":"LOCKER_PICKUP_OPEN_FAILED — no compartment door could be opened; nothing was settled"}}}},"/v1/third-party-delivery/locker-mock/lockers":{"get":{"tags":["ThirdPartyDelivery"],"summary":"List the provider's mock lockers","description":"Sandbox tooling: lists the provider's virtual locker cabinets with per-compartment door state, occupancy, and dimensions. Mock lockers behave like real hardware in every API flow (create delivery with mock=true, remote open, confirm) but never mix with real locker capacity. Each locker carries its shelf_id and each compartment its grid_id and uppercase pickup_locker_code, so console state can be matched to API traffic even when a compartment is empty. Compartments are ordered by the numeric pickup locker number, so R-2 precedes R-10. Each compartment reports what it holds: parcels[] with inventory_id (the same id the delivery API and the webhooks report), carrier_inventory_id, reference, final_pickup_locker_code, pickup_code, inventory_pickup_code and source (seeded or flow), plus hold when a sandbox delivery is still holding the compartment. final_pickup_locker_code is derived from the parcel's grid_id using the same cabinet-layout rule as delivery packages and is normalized to uppercase (for example R-7). pickup_code is the recipient-facing order/group code used by notifications and real lockers; it falls back to the single-inventory code for an ungrouped parcel. inventory_pickup_code always preserves that single-inventory code. parcel_count totals the cabinet.","operationId":"partnerLockerMockLockers","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Mock lockers with compartment states","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Mock lockers listed.","data":{"lockers":[{"device_id":"MOCK-AB12CD34EF","shelf_id":72,"name":"r","location":{"id":101,"name":"Downtown Locker"},"online":true,"compartment_count":8,"parcel_count":1,"compartments":[{"compartment":1,"pickup_locker_code":"R-7","grid_id":2120,"door_status":"closed","occupied":true,"length_mm":600,"width_mm":500,"height_mm":400,"parcels":[{"inventory_id":9012,"carrier_inventory_id":62198,"reference":"ORDER-1-PKG-1","final_pickup_locker_code":"R-7","pickup_code":"IYB0IT","inventory_pickup_code":"Q603ME","source":"flow"}]}]}]}}}}},"403":{"description":"LOCKER_PERMISSION_DENIED"},"429":{"description":"LOCKER_RATE_LIMITED"}}},"post":{"tags":["ThirdPartyDelivery"],"summary":"Generate a mock locker cabinet","description":"Creates a virtual cabinet (shelf + compartments) at one of the client's active locations for early integration development before real-hardware testing. The returned device_id is used in the remote open API and the mock door/device controls. Limited per provider.","operationId":"createPartnerLockerMockLocker","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["location_id"],"properties":{"location_id":{"type":"integer","description":"**Required.**\n\nLocation id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","maxLength":50,"description":"Human-readable name.\n\n**Details:** Type `string` · maxLength `50`."},"compartments":{"type":"integer","minimum":1,"maximum":60,"default":8,"description":"Compartments. Field in the JSON request body.\n\n**Details:** Type `integer` · Default: `8` · min `1` · max `60`."},"grid_length_cm":{"type":"number","minimum":5,"maximum":300,"default":60,"description":"Grid length cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · Default: `60` · min `5` · max `300`."},"grid_width_cm":{"type":"number","minimum":5,"maximum":300,"default":50,"description":"Grid width cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · Default: `50` · min `5` · max `300`."},"grid_height_cm":{"type":"number","minimum":5,"maximum":300,"default":40,"description":"Grid height cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · Default: `40` · min `5` · max `300`."},"weight_limit_kg":{"type":["number","null"],"exclusiveMinimum":0,"maximum":1000,"description":"Load limit of each compartment. Omitted leaves the cabinet with no limit, and weight then never refuses a parcel here.\n\n**Details:** Type `number` · Nullable · max `1000` · exclusiveMin `0`."}}},"example":{"location_id":101,"name":"Dev Cabinet","compartments":8,"weight_limit_kg":5}}}},"responses":{"201":{"description":"Mock locker created; data.locker.device_id identifies it"},"404":{"description":"LOCKER_MOCK_LOCATION_INVALID"},"422":{"description":"LOCKER_MOCK_LIMIT_REACHED or invalid compartments/dimensions"},"429":{"description":"LOCKER_RATE_LIMITED"}}}},"/v1/third-party-delivery/locker-mock/lockers/{deviceId}/door":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Force a mock compartment door open or closed","description":"Simulates the physical world: action=close mimics the driver shutting the door after a deposit (letting the door-verification cycle settle the compartment); action=open mimics a hardware fault or manual opening. Leaving a door open blocks that compartment for future openings exactly like real hardware.","operationId":"setPartnerLockerMockDoor","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deviceId","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.\n\n**Example:** `MOCK-AB12CD34EF`.","examples":["MOCK-AB12CD34EF"]},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.\n\n**Example:** `MOCK-AB12CD34EF`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["compartment","action"],"properties":{"compartment":{"type":"integer","description":"**Required.**\n\nCompartment. Field in the JSON request body.\n\n**Details:** Type `integer`."},"action":{"type":"string","enum":["open","close"],"description":"**Required.**\n\nEnum values:\n- `open` — Open the door\n- `close` — Close the door\n\n**Details:** Type `string`.","x-enumDescriptions":["Open the door","Close the door"]}}},"example":{"compartment":1,"action":"close"}}}},"responses":{"200":{"description":"Updated locker with compartment states"},"404":{"description":"LOCKER_MOCK_LOCKER_NOT_FOUND or LOCKER_MOCK_COMPARTMENT_NOT_FOUND"},"422":{"description":"Invalid action"},"429":{"description":"LOCKER_RATE_LIMITED"}}}},"/v1/third-party-delivery/locker-mock/lockers/{deviceId}/device":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Toggle a mock locker online or offline","description":"Offline mock lockers reject door-open commands with DEVICE_OFFLINE and report offline to eligibility checks, letting partners test failure handling.","operationId":"setPartnerLockerMockDevice","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deviceId","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["online"],"properties":{"online":{"type":"boolean","description":"**Required.**\n\nOnline. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}},"example":{"online":false}}}},"responses":{"200":{"description":"Updated locker state"},"404":{"description":"LOCKER_MOCK_LOCKER_NOT_FOUND"},"422":{"description":"online must be a boolean"},"429":{"description":"LOCKER_RATE_LIMITED"}}}},"/v1/third-party-delivery/locker-mock/lockers/{deviceId}/features":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Switch cabinet flows on a mock locker","description":"A mock locker is a whole cabinet: it is created with every terminal flow enabled, exactly as a real cabinet can be configured. This replaces the enabled set with the flows sent, so a partner can rehearse against a cabinet that offers only some of them. Sending an empty list disables every flow. Unknown keys are rejected.","operationId":"setPartnerLockerMockFeatures","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deviceId","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["features"],"properties":{"features":{"type":"array","description":"**Required.**\n\nCabinet flows to enable. Allowed values: dropoff, package_query, pickup_package, pickup_by_code, carrier_stockin, stockin_by_code, collect_inbound. 'dropoff' covers shipping, storage, return and partner locker delivery.\n\n**Details:** Type `array`, items `string`.","items":{"type":"string","description":"Features. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."}}}},"example":{"features":["dropoff","package_query","pickup_by_code"]}}}},"responses":{"200":{"description":"Updated locker state, including its enabled flows"},"404":{"description":"LOCKER_MOCK_LOCKER_NOT_FOUND"},"422":{"description":"One or more flows are unknown"},"429":{"description":"LOCKER_RATE_LIMITED"}}}},"/v1/third-party-delivery/locker-mock/lockers/{deviceId}/compartments":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Resize mock compartments or set their load limit","description":"Sets the size and the load limit of a sandbox cabinet's compartments — the two limits a real cabinet refuses a parcel on, so both refusals can be rehearsed. Size and limit move independently: sending only weight_limit_kg leaves the measurements alone, and the three edges must be sent together. weight_limit_kg null clears the limit, after which weight never refuses a parcel in those compartments. Omit compartments to change every compartment of the cabinet.","operationId":"setPartnerLockerMockCompartments","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deviceId","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"compartments":{"type":"array","description":"Compartment numbers to change; omit for every compartment of the cabinet.\n\n**Details:** Type `array`, items `integer`.","items":{"type":"integer","description":"Compartments. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."}},"grid_length_cm":{"type":"number","minimum":5,"maximum":300,"description":"Grid length cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · min `5` · max `300`."},"grid_width_cm":{"type":"number","minimum":5,"maximum":300,"description":"Grid width cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · min `5` · max `300`."},"grid_height_cm":{"type":"number","minimum":5,"maximum":300,"description":"Grid height cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · min `5` · max `300`."},"weight_limit_kg":{"type":["number","null"],"exclusiveMinimum":0,"maximum":1000,"description":"Load limit of each named compartment; null clears it.\n\n**Details:** Type `number` · Nullable · max `1000` · exclusiveMin `0`."}}},"example":{"compartments":[1,2],"weight_limit_kg":5}}}},"responses":{"200":{"description":"Updated locker state; each compartment reports length_mm, width_mm, height_mm and weight_limit_g (null for no limit)"},"404":{"description":"LOCKER_MOCK_LOCKER_NOT_FOUND or LOCKER_MOCK_COMPARTMENT_NOT_FOUND"},"422":{"description":"LOCKER_INPUT_INVALID — dimensions outside 5–300 cm, only some of the three edges, a load limit outside 0–1000 kg, or neither a size nor a limit to change"},"429":{"description":"LOCKER_RATE_LIMITED"}}}},"/v1/third-party-delivery/locker-mock/lockers/{deviceId}/parcels":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Place a test parcel in a mock locker","description":"Puts a parcel in the first free compartment of a sandbox cabinet so the pickup and query flows have something to find, without having to run a delivery first. The row is written exactly as a confirmed deposit writes it — same inventory type, the provider's own managed carrier, the same per-carrier sequence — and the returned pickup_code is the ordinary inventory code the pickup-by-code screen resolves. Requires the provider to have a managed carrier (bound when locker access is enabled).","operationId":"seedPartnerLockerMockParcel","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deviceId","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","maxLength":50,"description":"Carrier reference to file the parcel under. Generated when omitted.\n\n**Details:** Type `string` · maxLength `50`."}}},"example":{"reference":"MOCK-TEST-1"}}}},"responses":{"201":{"description":"Parcel placed: compartment, reference and pickup_code, plus the updated locker state"},"404":{"description":"LOCKER_MOCK_LOCKER_NOT_FOUND"},"422":{"description":"LOCKER_MOCK_CABINET_FULL or LOCKER_MOCK_CARRIER_NOT_CONFIGURED"},"429":{"description":"LOCKER_RATE_LIMITED"}}},"delete":{"tags":["ThirdPartyDelivery"],"summary":"Empty a mock locker cabinet","description":"Takes every test parcel back out of a sandbox cabinet and releases its pickup code, and frees any compartment a sandbox delivery is still holding (leased or opened but never confirmed). A mock cabinet holds nothing but test data, so this covers parcels the console seeded AND parcels a rehearsed delivery or a terminal flow placed. Pass compartments to limit it to single compartments; omit it to empty the whole cabinet.","operationId":"clearPartnerLockerMockParcels","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deviceId","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"removed (parcels taken out), released (held compartments freed), plus the updated locker state"},"404":{"description":"LOCKER_MOCK_LOCKER_NOT_FOUND or LOCKER_MOCK_COMPARTMENT_NOT_FOUND"},"429":{"description":"LOCKER_RATE_LIMITED"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"compartments":{"type":"array","items":{"type":"integer","description":"Compartments. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Compartment numbers to empty. Omit or leave empty to empty the whole cabinet.\n\n**Details:** Type `array`, items `integer`."}}},"example":{"compartments":[1,3]}}}}}},"/v1/third-party-delivery/locker-mock/lockers/{deviceId}/parcels/taken":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Declare mock compartment parcels physically taken","description":"The closing move after a forced door open on an occupied mock compartment: declares the parcels in the named compartments physically taken. Runs the full pickup settlement including the delivery-level finalization — the delivery advances to picked_up and the picked_up webhook fires — while console-seeded parcels are simply removed. Doors close and every verification/business blocker on the compartments is resolved, so they are immediately usable again. At least one compartment is required: taking is a per-door physical event, never a whole-cabinet default.","operationId":"markPartnerLockerMockParcelsTaken","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deviceId","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["compartments"],"properties":{"compartments":{"type":"array","items":{"type":"integer","description":"Compartments. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"minItems":1,"description":"Compartment numbers whose parcels were physically taken. At least one is required.\n\n**Details:** Type `array`, items `integer` · minItems `1`."}}},"example":{"compartments":[1]}}}},"responses":{"200":{"description":"taken (parcels settled as physically taken, pickup loop closed), plus the updated locker state"},"404":{"description":"LOCKER_MOCK_LOCKER_NOT_FOUND or LOCKER_MOCK_COMPARTMENT_NOT_FOUND"},"422":{"description":"LOCKER_INPUT_INVALID (compartments missing or empty)"},"429":{"description":"LOCKER_RATE_LIMITED"}}}},"/v1/third-party-delivery/locker-mock/lockers/{deviceId}":{"delete":{"tags":["ThirdPartyDelivery"],"summary":"Delete a mock locker cabinet","description":"Removes the virtual cabinet and its compartments. Refused while any compartment still holds inventory or an active allocation.","operationId":"deletePartnerLockerMockLocker","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"deviceId","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Mock locker deleted"},"404":{"description":"LOCKER_MOCK_LOCKER_NOT_FOUND"},"409":{"description":"LOCKER_MOCK_LOCKER_IN_USE"},"429":{"description":"LOCKER_RATE_LIMITED"}}}},"/v1/loading-plans":{"get":{"tags":["Loading Planner"],"summary":"List loading plans","operationId":"loadingPlans","security":[{"passport":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `100`."},"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `100`."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","ready","queued","solving","candidates_ready","finalized"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `draft` — Editable draft\n- `ready` — Ready to queue for solving\n- `queued` — Queued for the solver worker\n- `solving` — Solver is running\n- `candidates_ready` — Candidate solutions ready for review\n- `finalized` — Plan finalized / locked\n\n**Details:** Optional · Type `string`.","x-enumDescriptions":["Editable draft","Ready to queue for solving","Queued for the solver worker","Solver is running","Candidate solutions ready for review","Plan finalized / locked"]},"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `draft` — Editable draft\n- `ready` — Ready to queue for solving\n- `queued` — Queued for the solver worker\n- `solving` — Solver is running\n- `candidates_ready` — Candidate solutions ready for review\n- `finalized` — Plan finalized / locked\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"Paginated loading plans of the authenticated business","content":{"application/json":{"example":{"success":true,"data":{"plans":[{"id":12,"name":"July sea shipment","reference":"LP-2026-001","status":"draft","loading_method":"direct_container","transport_mode":"sea","space_strategy":"legacy_single","leftover_policy":"allow_loose","unloading_mode":"none","loading_direction":"rear_to_front","rehandle_penalty":25,"container_preset":"40hc","container_inner_length_cm":1203.2,"container_inner_width_cm":235.2,"container_inner_height_cm":269.8,"container_max_payload_kg":26500,"container_corner_cm":null,"container_quantity_limit":5,"target_utilization_percent":85,"input_revision":1,"linked_order_id":null,"linked_order_reference":null,"final_candidate_id":null,"finalized_at":null,"item_count":1,"created_at":"2026-07-27T10:00:00-04:00","updated_at":"2026-07-27T10:05:00-04:00"}],"pagination":{"page":1,"per_page":20,"total":1,"last_page":1}}}}}}}},"post":{"tags":["Loading Planner"],"summary":"Create a loading plan","operationId":"createLoadingPlan","security":[{"passport":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","loading_method","container_preset","container_inner_length_cm","container_inner_width_cm","container_inner_height_cm","container_max_payload_kg","target_utilization_percent"],"properties":{"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"reference":{"type":["string","null"],"maxLength":100,"description":"External reference, unique per business\n\n**Details:** Type `string` · Nullable · maxLength `100`."},"linked_order_id":{"type":["integer","null"],"description":"Linked order id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"loading_method":{"type":"string","enum":["direct_container","palletize_then_container"],"description":"**Required.**\n\nHow cargo is staged into the transport space for a loading plan.\n\nEnum values (from deployed code):\n- `direct_container` — Pack cargo directly into the container / vehicle space\n- `palletize_then_container` — Build pallets first, then load pallets into the space\n\n**Details:** Type `string`.","x-enumDescriptions":["Pack cargo directly into the space","Palletize first, then load"]},"leftover_policy":{"type":"string","enum":["allow_loose","keep_unloaded"],"description":"What the solver does with items that do not fit a packing unit.\n\nEnum values (from deployed code):\n- `allow_loose` — Leftover items may travel loose (not on a pallet)\n- `keep_unloaded` — Items that do not fit stay unloaded\n\n**Details:** Type `string`.","x-enumDescriptions":["Leftover items may travel loose","Items that do not fit stay unloaded"]},"unloading_mode":{"type":"string","enum":["none","unload_sequence"],"description":"Whether unload / stop sequence constraints are enforced while packing.\n\nEnum values (from deployed code):\n- `none` — No unload sequencing constraints\n- `unload_sequence` — Honor stop / unload sequence when packing\n\n**Details:** Type `string`.","x-enumDescriptions":["No unload sequencing","Honor unload sequence"]},"loading_direction":{"type":"string","enum":["rear_to_front","front_to_rear"],"description":"Direction cargo is loaded along the long axis of the space.\n\nEnum values (from deployed code):\n- `rear_to_front` — Load from the rear door toward the front\n- `front_to_rear` — Load from the front toward the rear\n\n**Details:** Type `string`.","x-enumDescriptions":["Load rear → front","Load front → rear"]},"rehandle_penalty":{"type":"number","minimum":0,"maximum":1000,"description":"Rehandle penalty. Field in the JSON request body.\n\n**Details:** Type `number` · min `0` · max `1000`."},"container_preset":{"type":"string","enum":["20gp","40gp","40hc","45hc","custom"],"description":"**Required.**\n\nAllowed values: `20gp` · `40gp` · `40hc` · `45hc` · `custom`.\n\n**Details:** Type `string`."},"container_inner_length_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nContainer inner length cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"container_inner_width_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nContainer inner width cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"container_inner_height_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nContainer inner height cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"container_max_payload_kg":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nContainer max payload kg. Field in the JSON request body.\n\n**Details:** Type `number` · exclusiveMin `0`."},"container_corner_cm":{"type":["number","null"],"minimum":0,"description":"Container corner cm. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable · min `0`."},"container_quantity_limit":{"type":"integer","minimum":1,"maximum":100,"description":"Container quantity limit. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · min `1` · max `100`."},"target_utilization_percent":{"type":"number","minimum":1,"maximum":100,"description":"**Required.**\n\nTarget utilization percent. Field in the JSON request body.\n\n**Details:** Type `number` · min `1` · max `100`."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."}}},"example":{"name":"July sea shipment","reference":"LP-2026-001","loading_method":"direct_container","leftover_policy":"allow_loose","unloading_mode":"none","loading_direction":"rear_to_front","rehandle_penalty":25,"container_preset":"40hc","container_inner_length_cm":1203.2,"container_inner_width_cm":235.2,"container_inner_height_cm":269.8,"container_max_payload_kg":26500,"container_quantity_limit":5,"target_utilization_percent":85}}}},"responses":{"201":{"description":"Loading plan created","content":{"application/json":{"example":{"success":true,"data":{"plan":{"id":12,"name":"July sea shipment","reference":"LP-2026-001","status":"draft","loading_method":"direct_container","transport_mode":"sea","space_strategy":"legacy_single","leftover_policy":"allow_loose","unloading_mode":"none","loading_direction":"rear_to_front","rehandle_penalty":25,"container_preset":"40hc","container_inner_length_cm":1203.2,"container_inner_width_cm":235.2,"container_inner_height_cm":269.8,"container_max_payload_kg":26500,"container_corner_cm":null,"container_quantity_limit":5,"target_utilization_percent":85,"input_revision":1,"linked_order_id":null,"linked_order_reference":null,"final_candidate_id":null,"finalized_at":null,"item_count":1,"created_at":"2026-07-27T10:00:00-04:00","updated_at":"2026-07-27T10:05:00-04:00"}}}}}},"422":{"description":"Validation failed (error.code VALIDATION_FAILED with per-field messages in error.fields)"}}}},"/v1/loading-plans/{plan}":{"get":{"tags":["Loading Planner"],"summary":"Get a loading plan with items and equipment summary","operationId":"loadingPlan","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Loading plan detail including items[] and equipment_summary[]","content":{"application/json":{"example":{"success":true,"data":{"plan":{"id":12,"name":"July sea shipment","reference":"LP-2026-001","status":"draft","loading_method":"direct_container","transport_mode":"sea","space_strategy":"legacy_single","leftover_policy":"allow_loose","unloading_mode":"none","loading_direction":"rear_to_front","rehandle_penalty":25,"container_preset":"40hc","container_inner_length_cm":1203.2,"container_inner_width_cm":235.2,"container_inner_height_cm":269.8,"container_max_payload_kg":26500,"container_corner_cm":null,"container_quantity_limit":5,"target_utilization_percent":85,"input_revision":1,"linked_order_id":null,"linked_order_reference":null,"final_candidate_id":null,"finalized_at":null,"item_count":1,"created_at":"2026-07-27T10:00:00-04:00","updated_at":"2026-07-27T10:05:00-04:00","notes":null,"items":[{"id":101,"loading_plan_id":12,"external_item_id":"PO-88-LINE-1","name":"Carton of spare parts","sku":"SKU-1001","packaging_type":"carton","cargo_form":"loose","auto_palletize":false,"orientation":"any","prohibit_mixed_pallet":false,"pallet_profile_id":null,"unload_stop_id":null,"unload_priority":null,"quantity":120,"length_cm":60,"width_cm":40,"height_cm":40,"weight_kg":12.5,"can_rotate":true,"stackable":true,"max_stack_layers":4,"bearing_level":null,"notes":null,"created_at":"2026-07-27T10:01:00-04:00","updated_at":"2026-07-27T10:01:00-04:00"}],"equipment_summary":[{"id":3,"code":"CNTR-1","name":"40HC container","equipment_kind":"sea_container","preset_code":"40hc","quantity":1,"sequence":1,"space_count":1}]}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"}}},"put":{"tags":["Loading Planner"],"summary":"Update a loading plan","operationId":"updateLoadingPlan","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","loading_method","container_preset","container_inner_length_cm","container_inner_width_cm","container_inner_height_cm","container_max_payload_kg","target_utilization_percent"],"properties":{"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"reference":{"type":["string","null"],"maxLength":100,"description":"External reference, unique per business\n\n**Details:** Type `string` · Nullable · maxLength `100`."},"linked_order_id":{"type":["integer","null"],"description":"Linked order id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"loading_method":{"type":"string","enum":["direct_container","palletize_then_container"],"description":"**Required.**\n\nHow cargo is staged into the transport space for a loading plan.\n\nEnum values (from deployed code):\n- `direct_container` — Pack cargo directly into the container / vehicle space\n- `palletize_then_container` — Build pallets first, then load pallets into the space\n\n**Details:** Type `string`.","x-enumDescriptions":["Pack cargo directly into the space","Palletize first, then load"]},"leftover_policy":{"type":"string","enum":["allow_loose","keep_unloaded"],"description":"What the solver does with items that do not fit a packing unit.\n\nEnum values (from deployed code):\n- `allow_loose` — Leftover items may travel loose (not on a pallet)\n- `keep_unloaded` — Items that do not fit stay unloaded\n\n**Details:** Type `string`.","x-enumDescriptions":["Leftover items may travel loose","Items that do not fit stay unloaded"]},"unloading_mode":{"type":"string","enum":["none","unload_sequence"],"description":"Whether unload / stop sequence constraints are enforced while packing.\n\nEnum values (from deployed code):\n- `none` — No unload sequencing constraints\n- `unload_sequence` — Honor stop / unload sequence when packing\n\n**Details:** Type `string`.","x-enumDescriptions":["No unload sequencing","Honor unload sequence"]},"loading_direction":{"type":"string","enum":["rear_to_front","front_to_rear"],"description":"Direction cargo is loaded along the long axis of the space.\n\nEnum values (from deployed code):\n- `rear_to_front` — Load from the rear door toward the front\n- `front_to_rear` — Load from the front toward the rear\n\n**Details:** Type `string`.","x-enumDescriptions":["Load rear → front","Load front → rear"]},"rehandle_penalty":{"type":"number","minimum":0,"maximum":1000,"description":"Rehandle penalty. Field in the JSON request body.\n\n**Details:** Type `number` · min `0` · max `1000`."},"container_preset":{"type":"string","enum":["20gp","40gp","40hc","45hc","custom"],"description":"**Required.**\n\nAllowed values: `20gp` · `40gp` · `40hc` · `45hc` · `custom`.\n\n**Details:** Type `string`."},"container_inner_length_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nContainer inner length cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"container_inner_width_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nContainer inner width cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"container_inner_height_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nContainer inner height cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"container_max_payload_kg":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nContainer max payload kg. Field in the JSON request body.\n\n**Details:** Type `number` · exclusiveMin `0`."},"container_corner_cm":{"type":["number","null"],"minimum":0,"description":"Container corner cm. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable · min `0`."},"container_quantity_limit":{"type":"integer","minimum":1,"maximum":100,"description":"Container quantity limit. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · min `1` · max `100`."},"target_utilization_percent":{"type":"number","minimum":1,"maximum":100,"description":"**Required.**\n\nTarget utilization percent. Field in the JSON request body.\n\n**Details:** Type `number` · min `1` · max `100`."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."}}},"example":{"name":"July sea shipment","reference":"LP-2026-001","loading_method":"direct_container","leftover_policy":"allow_loose","unloading_mode":"none","loading_direction":"rear_to_front","rehandle_penalty":25,"container_preset":"40hc","container_inner_length_cm":1203.2,"container_inner_width_cm":235.2,"container_inner_height_cm":269.8,"container_max_payload_kg":26500,"container_quantity_limit":5,"target_utilization_percent":85}}}},"responses":{"200":{"description":"Loading plan updated","content":{"application/json":{"example":{"success":true,"data":{"plan":{"id":12,"name":"July sea shipment","reference":"LP-2026-001","status":"draft","loading_method":"direct_container","transport_mode":"sea","space_strategy":"legacy_single","leftover_policy":"allow_loose","unloading_mode":"none","loading_direction":"rear_to_front","rehandle_penalty":25,"container_preset":"40hc","container_inner_length_cm":1203.2,"container_inner_width_cm":235.2,"container_inner_height_cm":269.8,"container_max_payload_kg":26500,"container_corner_cm":null,"container_quantity_limit":5,"target_utilization_percent":85,"input_revision":1,"linked_order_id":null,"linked_order_reference":null,"final_candidate_id":null,"finalized_at":null,"item_count":1,"created_at":"2026-07-27T10:00:00-04:00","updated_at":"2026-07-27T10:05:00-04:00"}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"},"409":{"description":"Plan already finalized (error.code PLAN_FINALIZED)"},"422":{"description":"Validation failed (error.code VALIDATION_FAILED with per-field messages in error.fields)"}}},"delete":{"tags":["Loading Planner"],"summary":"Delete a loading plan","operationId":"deleteLoadingPlan","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Loading plan deleted","content":{"application/json":{"example":{"success":true,"data":{"deleted":true}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"}}}},"/v1/loading-plans/{plan}/items":{"get":{"tags":["Loading Planner"],"summary":"List cargo items of a loading plan","operationId":"loadingPlanItems","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Cargo items of the plan","content":{"application/json":{"example":{"success":true,"data":{"items":[{"id":101,"loading_plan_id":12,"external_item_id":"PO-88-LINE-1","name":"Carton of spare parts","sku":"SKU-1001","packaging_type":"carton","cargo_form":"loose","auto_palletize":false,"orientation":"any","prohibit_mixed_pallet":false,"pallet_profile_id":null,"unload_stop_id":null,"unload_priority":null,"quantity":120,"length_cm":60,"width_cm":40,"height_cm":40,"weight_kg":12.5,"can_rotate":true,"stackable":true,"max_stack_layers":4,"bearing_level":null,"notes":null,"created_at":"2026-07-27T10:01:00-04:00","updated_at":"2026-07-27T10:01:00-04:00"}]}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"}}},"post":{"tags":["Loading Planner"],"summary":"Add a cargo item to a loading plan","operationId":"createLoadingPlanItem","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","packaging_type","quantity","length_cm","width_cm","height_cm","weight_kg"],"properties":{"external_item_id":{"type":["string","null"],"description":"External item id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"sku":{"type":["string","null"],"description":"Stock keeping unit / product code.\n\n**Details:** Type `string` · Nullable."},"packaging_type":{"type":"string","enum":["carton","pallet","crate","other"],"description":"**Required.**\n\nAllowed values: `carton` · `pallet` · `crate` · `other`.\n\n**Details:** Type `string`."},"cargo_form":{"type":"string","enum":["loose","pre_palletized"],"description":"Allowed values: `loose` · `pre_palletized`.\n\n**Details:** Type `string`."},"auto_palletize":{"type":"boolean","description":"Auto palletize. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"orientation":{"type":"string","enum":["any","upright_only","side_only"],"description":"Allowed values: `any` · `upright_only` · `side_only`.\n\n**Details:** Type `string`."},"prohibit_mixed_pallet":{"type":"boolean","description":"Prohibit mixed pallet. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"pallet_profile_id":{"type":["integer","null"],"description":"Pallet profile id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"unload_stop_id":{"type":["integer","null"],"description":"Unload stop id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"unload_priority":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"Unload priority. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable · min `1` · max `1000`."},"quantity":{"type":"integer","minimum":1,"maximum":1000000,"description":"**Required.**\n\nQuantity of units.\n\n**Details:** Type `integer` · min `1` · max `1000000`."},"length_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nLength cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"width_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nWidth cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"height_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nHeight cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_kg":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nWeight kg. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"can_rotate":{"type":"boolean","description":"Can rotate. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"stackable":{"type":"boolean","description":"Stackable. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"max_stack_layers":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"Max stack layers. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable · min `1` · max `1000`."},"bearing_level":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Bearing level. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable · min `1` · max `100`."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."}}},"example":{"external_item_id":"PO-88-LINE-1","name":"Carton of spare parts","sku":"SKU-1001","packaging_type":"carton","cargo_form":"loose","orientation":"any","quantity":120,"length_cm":60,"width_cm":40,"height_cm":40,"weight_kg":12.5,"can_rotate":true,"stackable":true,"max_stack_layers":4}}}},"responses":{"201":{"description":"Cargo item created","content":{"application/json":{"example":{"success":true,"data":{"item":{"id":101,"loading_plan_id":12,"external_item_id":"PO-88-LINE-1","name":"Carton of spare parts","sku":"SKU-1001","packaging_type":"carton","cargo_form":"loose","auto_palletize":false,"orientation":"any","prohibit_mixed_pallet":false,"pallet_profile_id":null,"unload_stop_id":null,"unload_priority":null,"quantity":120,"length_cm":60,"width_cm":40,"height_cm":40,"weight_kg":12.5,"can_rotate":true,"stackable":true,"max_stack_layers":4,"bearing_level":null,"notes":null,"created_at":"2026-07-27T10:01:00-04:00","updated_at":"2026-07-27T10:01:00-04:00"}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"},"409":{"description":"Plan already finalized (error.code PLAN_FINALIZED)"},"422":{"description":"Validation failed (error.code VALIDATION_FAILED with per-field messages in error.fields)"}}}},"/v1/loading-plans/{plan}/items/{item}":{"put":{"tags":["Loading Planner"],"summary":"Update a loading plan cargo item","operationId":"updateLoadingPlanItem","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"item","required":true,"schema":{"type":"integer","description":"Item. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Item. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","packaging_type","quantity","length_cm","width_cm","height_cm","weight_kg"],"properties":{"external_item_id":{"type":["string","null"],"description":"External item id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"sku":{"type":["string","null"],"description":"Stock keeping unit / product code.\n\n**Details:** Type `string` · Nullable."},"packaging_type":{"type":"string","enum":["carton","pallet","crate","other"],"description":"**Required.**\n\nAllowed values: `carton` · `pallet` · `crate` · `other`.\n\n**Details:** Type `string`."},"cargo_form":{"type":"string","enum":["loose","pre_palletized"],"description":"Allowed values: `loose` · `pre_palletized`.\n\n**Details:** Type `string`."},"auto_palletize":{"type":"boolean","description":"Auto palletize. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"orientation":{"type":"string","enum":["any","upright_only","side_only"],"description":"Allowed values: `any` · `upright_only` · `side_only`.\n\n**Details:** Type `string`."},"prohibit_mixed_pallet":{"type":"boolean","description":"Prohibit mixed pallet. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"pallet_profile_id":{"type":["integer","null"],"description":"Pallet profile id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"unload_stop_id":{"type":["integer","null"],"description":"Unload stop id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"unload_priority":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"Unload priority. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable · min `1` · max `1000`."},"quantity":{"type":"integer","minimum":1,"maximum":1000000,"description":"**Required.**\n\nQuantity of units.\n\n**Details:** Type `integer` · min `1` · max `1000000`."},"length_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nLength cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"width_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nWidth cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"height_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nHeight cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_kg":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nWeight kg. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"can_rotate":{"type":"boolean","description":"Can rotate. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"stackable":{"type":"boolean","description":"Stackable. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"max_stack_layers":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"Max stack layers. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable · min `1` · max `1000`."},"bearing_level":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Bearing level. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable · min `1` · max `100`."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."}}},"example":{"external_item_id":"PO-88-LINE-1","name":"Carton of spare parts","sku":"SKU-1001","packaging_type":"carton","cargo_form":"loose","orientation":"any","quantity":120,"length_cm":60,"width_cm":40,"height_cm":40,"weight_kg":12.5,"can_rotate":true,"stackable":true,"max_stack_layers":4}}}},"responses":{"200":{"description":"Cargo item updated","content":{"application/json":{"example":{"success":true,"data":{"item":{"id":101,"loading_plan_id":12,"external_item_id":"PO-88-LINE-1","name":"Carton of spare parts","sku":"SKU-1001","packaging_type":"carton","cargo_form":"loose","auto_palletize":false,"orientation":"any","prohibit_mixed_pallet":false,"pallet_profile_id":null,"unload_stop_id":null,"unload_priority":null,"quantity":120,"length_cm":60,"width_cm":40,"height_cm":40,"weight_kg":12.5,"can_rotate":true,"stackable":true,"max_stack_layers":4,"bearing_level":null,"notes":null,"created_at":"2026-07-27T10:01:00-04:00","updated_at":"2026-07-27T10:01:00-04:00"}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"},"409":{"description":"Plan already finalized (error.code PLAN_FINALIZED)"},"422":{"description":"Validation failed (error.code VALIDATION_FAILED with per-field messages in error.fields)"}}},"delete":{"tags":["Loading Planner"],"summary":"Delete a loading plan cargo item","operationId":"deleteLoadingPlanItem","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"item","required":true,"schema":{"type":"integer","description":"Item. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Item. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Cargo item deleted","content":{"application/json":{"example":{"success":true,"data":{"deleted":true}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"},"409":{"description":"Plan already finalized (error.code PLAN_FINALIZED)"}}}},"/v1/loading-plans/{plan}/equipment":{"get":{"tags":["Loading Planner"],"summary":"Get equipment, cargo spaces, and volume policy","operationId":"loadingPlanEquipment","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Equipment configuration with heterogeneous rectangular cargo spaces"},"404":{"description":"Not found in authenticated business"}}},"put":{"tags":["Loading Planner"],"summary":"Replace equipment, cargo spaces, and volume policy","operationId":"updateLoadingPlanEquipment","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expected_input_revision","transport_mode","volume_profile","volume_display_unit","volume_denominator","volume_rounding_mode","volume_rounding_precision","equipments"],"properties":{"expected_input_revision":{"type":"integer","minimum":1,"description":"**Required.**\n\nExpected input revision. Field in the JSON request body.\n\n**Details:** Type `integer` · min `1`."},"transport_mode":{"type":"string","enum":["sea","air","road","breakbulk"],"description":"**Required.**\n\nAllowed values: `sea` · `air` · `road` · `breakbulk`.\n\n**Details:** Type `string`."},"volume_profile":{"type":"string","enum":["precise","route_legacy"],"description":"**Required.**\n\nAllowed values: `precise` · `route_legacy`.\n\n**Details:** Type `string`."},"volume_display_unit":{"type":"string","enum":["m3","l","ft3","cm3","in3"],"description":"**Required.**\n\nAllowed values: `m3` · `l` · `ft3` · `cm3` · `in3`.\n\n**Details:** Type `string`."},"volume_denominator":{"type":"string","enum":["nominal_internal","effective_usable","configured_capacity"],"description":"**Required.**\n\nAllowed values: `nominal_internal` · `effective_usable` · `configured_capacity`.\n\n**Details:** Type `string`."},"volume_rounding_mode":{"type":"string","enum":["none","round","floor","ceil"],"description":"**Required.**\n\nAllowed values: `none` · `round` · `floor` · `ceil`.\n\n**Details:** Type `string`."},"volume_rounding_precision":{"type":"integer","minimum":0,"maximum":9,"description":"**Required.**\n\nVolume rounding precision. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer` · min `0` · max `9`."},"equipments":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["code","name","equipment_kind","quantity","sequence","spaces"],"properties":{"code":{"type":"string","maxLength":50,"description":"**Required.**\n\nStable machine code for this resource.\n\n**Details:** Type `string` · maxLength `50`."},"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"equipment_kind":{"type":"string","enum":["sea_container","air_uld","vehicle","truck_body","breakbulk_space","custom_space"],"description":"**Required.**\n\nAllowed values: `sea_container` · `air_uld` · `vehicle` · `truck_body` · `breakbulk_space` · `custom_space`.\n\n**Details:** Type `string`."},"preset_code":{"type":["string","null"],"description":"Preset code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"quantity":{"type":"integer","minimum":1,"maximum":20,"description":"**Required.**\n\nQuantity of units.\n\n**Details:** Type `integer` · min `1` · max `20`."},"sequence":{"type":"integer","minimum":1,"description":"**Required.**\n\nSequence. Field in the JSON request body.\n\n**Details:** Type `integer` · min `1`."},"spaces":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["code","name","quantity","sequence","inner_length_cm","inner_width_cm","inner_height_cm","max_payload_kg","volume_utilization_percent","access_face"],"properties":{"code":{"type":"string","description":"**Required.**\n\nStable machine code for this resource.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`."},"quantity":{"type":"integer","minimum":1,"description":"**Required.**\n\nQuantity of units.\n\n**Details:** Type `integer` · min `1`."},"sequence":{"type":"integer","minimum":1,"description":"**Required.**\n\nSequence. Field in the JSON request body.\n\n**Details:** Type `integer` · min `1`."},"inner_length_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nInner length cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"inner_width_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nInner width cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"inner_height_cm":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nInner height cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · exclusiveMin `0`."},"corner_cm":{"type":["number","null"],"minimum":0,"description":"Optional corner casting size; blocks cargo at all four vertical corners of the space. Null or 0 disables corner posts.\n\n**Details:** Type `number` · Nullable · min `0`."},"max_payload_kg":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nMax payload kg. Field in the JSON request body.\n\n**Details:** Type `number` · exclusiveMin `0`."},"volume_utilization_percent":{"type":"number","minimum":0,"maximum":100,"description":"**Required.**\n\nVolume utilization percent. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · min `0` · max `100`."},"capacity_override_m3":{"type":["number","null"],"exclusiveMinimum":0,"description":"Capacity override m3. Address component used for geocoding and delivery.\n\n**Details:** Type `number` · Nullable · exclusiveMin `0`."},"access_face":{"type":"string","enum":["x_min","x_max"],"description":"**Required.**\n\nAllowed values: `x_min` · `x_max`.\n\n**Details:** Type `string`."}}},"description":"**Required.**\n\nSpaces. Field in the JSON request body.\n\n**Details:** Type `array`, items `object` · minItems `1` · maxItems `20`."}}},"description":"**Required.**\n\nEquipments. Field in the JSON request body.\n\n**Details:** Type `array`, items `object` · minItems `1` · maxItems `20`."}}},"example":{"expected_input_revision":1,"transport_mode":"road","volume_profile":"route_legacy","volume_display_unit":"l","volume_denominator":"effective_usable","volume_rounding_mode":"floor","volume_rounding_precision":0,"equipments":[{"code":"VEHICLE-1","name":"Road vehicle","equipment_kind":"vehicle","quantity":1,"sequence":1,"spaces":[{"code":"MAIN","name":"Main cargo space","quantity":1,"sequence":1,"inner_length_cm":600,"inner_width_cm":240,"inner_height_cm":240,"corner_cm":null,"max_payload_kg":5000,"volume_utilization_percent":85,"capacity_override_m3":null,"access_face":"x_min"}]}]}}}},"responses":{"200":{"description":"Configuration replaced or idempotently replayed"},"409":{"description":"Finalized plan or input revision conflict"},"422":{"description":"Invalid equipment or space configuration"}}}},"/v1/loading-plans/{plan}/unload-sequence":{"get":{"tags":["Loading Planner"],"summary":"Get unload sequence settings","operationId":"loadingPlanUnloadSequence","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Unload stops, item priorities, direction and rehandle penalty"}}},"put":{"tags":["Loading Planner"],"summary":"Replace unload sequence settings","operationId":"updateLoadingPlanUnloadSequence","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expected_input_revision","unloading_mode","loading_direction","rehandle_penalty"],"properties":{"expected_input_revision":{"type":"integer","description":"**Required.**\n\nExpected input revision. Field in the JSON request body.\n\n**Details:** Type `integer`."},"unloading_mode":{"type":"string","enum":["none","unload_sequence"],"description":"**Required.**\n\nWhether unload / stop sequence constraints are enforced while packing.\n\nEnum values (from deployed code):\n- `none` — No unload sequencing constraints\n- `unload_sequence` — Honor stop / unload sequence when packing\n\n**Details:** Type `string`.","x-enumDescriptions":["No unload sequencing","Honor unload sequence"]},"loading_direction":{"type":"string","enum":["rear_to_front","front_to_rear"],"description":"**Required.**\n\nDirection cargo is loaded along the long axis of the space.\n\nEnum values (from deployed code):\n- `rear_to_front` — Load from the rear door toward the front\n- `front_to_rear` — Load from the front toward the rear\n\n**Details:** Type `string`.","x-enumDescriptions":["Load rear → front","Load front → rear"]},"rehandle_penalty":{"type":"number","description":"**Required.**\n\nRehandle penalty. Field in the JSON request body.\n\n**Details:** Type `number`."},"stops":{"type":"array","items":{"type":"object","description":"Stops. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Stops. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"responses":{"200":{"description":"Sequence replaced or idempotently replayed"},"409":{"description":"Input revision conflict"},"422":{"description":"Incomplete or invalid sequence"}}}},"/v1/loading-plans/{plan}/solve":{"post":{"tags":["Loading Planner"],"summary":"Queue an independent container loading solve","operationId":"startLoadingPlanSolve","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","maxLength":100,"description":"Idempotency key. Stable machine-readable code.\n\n**Details:** Required · Type `string` · maxLength `100`."},"description":"Idempotency key. Stable machine-readable code.\n\n**Details:** Required · Type `string` · maxLength `100`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"callback_url and callback_secret are optional, but must be supplied together. The callback target must be a resolvable public HTTPS endpoint. callback_format and callback_signature are optional and need a callback: ce_binary adds CloudEvents 1.0 ce-* headers, ce_structured sends the body as a CloudEvent (Content-Type application/cloudevents+json, native body in data), standard_webhooks adds webhook-id / webhook-timestamp / webhook-signature keyed with callback_secret. The native headers and signature are always sent. Omitted or native gives the callback exactly as before.","properties":{"candidate_limit":{"type":"integer","minimum":1,"maximum":3,"default":3,"description":"Candidate limit. Field in the JSON request body.\n\n**Details:** Type `integer` · Default: `3` · min `1` · max `3`."},"callback_url":{"type":"string","format":"uri","maxLength":2048,"description":"Callback url. Absolute or relative URL.\n\n**Details:** Type `string`, format `uri` · maxLength `2048`."},"callback_secret":{"type":"string","minLength":32,"maxLength":200,"writeOnly":true,"description":"Callback secret. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string` · Write-only · minLength `32` · maxLength `200`."},"callback_format":{"type":"string","enum":["native","ce_binary","ce_structured"],"default":"native","description":"Allowed values: `native` · `ce_binary` · `ce_structured`.\n\n**Details:** Type `string` · Default: `native`."},"callback_signature":{"type":"string","enum":["native","standard_webhooks"],"default":"native","description":"Allowed values: `native` · `standard_webhooks`.\n\n**Details:** Type `string` · Default: `native`."}}},"example":{"candidate_limit":3,"callback_url":"https://events.example.com/loading-plan","callback_secret":"replace-with-at-least-32-characters"}}}},"responses":{"202":{"description":"Solve queued","content":{"application/json":{"example":{"success":true,"data":{"run":{"id":42,"request_id":"998c2298-70a6-4d51-b18d-20325f609f48","status":"queued","progress_percent":0,"input_revision":3,"poll_after_seconds":2,"webhook":{"configured":true,"deliveries":[]}}}}}}},"409":{"description":"Active run or idempotency conflict"},"422":{"description":"Invalid or oversized loading input"},"429":{"description":"Per-user or per-business solve limit exceeded. Retry-After is returned as an HTTP header and retry_after_seconds in the error body."}}}},"/v1/loading-plans/{plan}/solve-runs/{run}":{"get":{"tags":["Loading Planner"],"summary":"Get solve status and progress","operationId":"loadingPlanSolveRun","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"run","required":true,"schema":{"type":"integer","description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Run status, request ID, queue wait, solver duration, heartbeat, recovery timestamp and webhook delivery summaries"},"404":{"description":"Not found in authenticated business"}}}},"/v1/loading-plans/{plan}/solve-runs/{run}/cancel":{"post":{"tags":["Loading Planner"],"summary":"Cancel a queued or solving run","operationId":"cancelLoadingPlanSolve","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"run","required":true,"schema":{"type":"integer","description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Cancellation accepted"},"409":{"description":"Run is terminal"}}}},"/v1/loading-plans/{plan}/solve-runs/{run}/candidates":{"get":{"tags":["Loading Planner"],"summary":"List independently validated candidates","operationId":"loadingPlanCandidates","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"run","required":true,"schema":{"type":"integer","description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Candidate summaries","content":{"application/json":{"example":{"success":true,"data":{"candidates":[{"id":7,"rank":1,"container_count":1,"volume_utilization_percent":82.5,"validation_status":"passed"}]}}}}}}}},"/v1/loading-plans/{plan}/solve-runs/{run}/candidates/{candidate}":{"get":{"tags":["Loading Planner"],"summary":"Get candidate placements, 3D scene data, and unplaced reasons","operationId":"loadingPlanCandidate","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"run","required":true,"schema":{"type":"integer","description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"candidate","required":true,"schema":{"type":"integer","description":"Candidate. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Required · Type `integer`."},"description":"Candidate. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Validated candidate with a versioned shared scene for Three.js, top, side and door projections. All scene coordinates are centimetres from the frozen solver-run space origin.","content":{"application/json":{"example":{"success":true,"data":{"candidate":{"id":7,"placements":[],"unplaced":[],"scene":{"schema_version":"loading-scene-1.0","coordinate_system":{"unit":"cm"},"spaces":[{"space_key":"CONTAINER-1/MAIN-1","size_cm":[1203,235,269],"projections":{"top":{"rectangles":[]},"side":{"rectangles":[]},"door":{"rectangles":[]}}}],"placements":[],"checksum":"scene-sha256"}}}}}}},"404":{"description":"Not found in authenticated business"}}}},"/v1/loading-plans/{plan}/solve-runs/{run}/candidates/{candidate}/finalize":{"post":{"tags":["Loading Planner"],"summary":"Finalize a validated candidate","operationId":"finalizeLoadingPlanCandidate","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"run","required":true,"schema":{"type":"integer","description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Run. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"candidate","required":true,"schema":{"type":"integer","description":"Candidate. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Required · Type `integer`."},"description":"Candidate. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["candidate_checksum","acknowledge_warnings"],"properties":{"candidate_checksum":{"type":"string","minLength":64,"maxLength":64,"description":"**Required.**\n\nCandidate checksum. Field in the JSON request body.\n\n**Details:** Type `string` · minLength `64` · maxLength `64`."},"acknowledge_warnings":{"type":"boolean","description":"**Required.**\n\nAcknowledge warnings. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}},"example":{"candidate_checksum":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","acknowledge_warnings":true}}}},"responses":{"200":{"description":"Candidate finalized"},"409":{"description":"Stale, invalid, or already finalized candidate"},"422":{"description":"Warnings not acknowledged"}}}},"/v1/loading-plans/{plan}/final-plan":{"get":{"tags":["Loading Planner"],"summary":"Get the finalized independent container loading plan","operationId":"loadingPlanFinalPlan","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Final candidate and scene"},"404":{"description":"No final plan in authenticated business"}}}},"/v1/packing-plans":{"get":{"tags":["Packing Plans"],"summary":"List packing plans","operationId":"packingPlans","security":[{"passport":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `100`."},"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `100`."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","solved","finalized"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `draft` — Editable draft\n- `solved` — Solver finished with candidate packing\n- `finalized` — Plan finalized / locked\n\n**Details:** Optional · Type `string`.","x-enumDescriptions":["Editable draft","Solver finished with candidate packing","Plan finalized / locked"]},"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `draft` — Editable draft\n- `solved` — Solver finished with candidate packing\n- `finalized` — Plan finalized / locked\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"Paginated packing plans of the authenticated business","content":{"application/json":{"example":{"success":true,"data":{"plans":[{"id":7,"name":"Retail order 4512 split","reference":"PP-2026-001","status":"draft","target_utilization_percent":85,"item_count":1,"latest_result_id":null,"latest_package_count":null,"created_at":"2026-07-27T09:00:00-04:00","updated_at":"2026-07-27T09:10:00-04:00"}],"pagination":{"page":1,"per_page":20,"total":1,"last_page":1}}}}}}}},"post":{"tags":["Packing Plans"],"summary":"Create a packing plan with candidate packaging selections","operationId":"createPackingPlan","security":[{"passport":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Candidate packagings come from packaging_type_ids (whole packaging categories), packaging_ids (specific packagings) and custom_packagings. An empty selection means every active packaging of the business is a candidate.","required":["name"],"properties":{"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"reference":{"type":["string","null"],"maxLength":100,"description":"External reference, unique per business\n\n**Details:** Type `string` · Nullable · maxLength `100`."},"target_utilization_percent":{"type":"number","minimum":10,"maximum":100,"default":85,"description":"Hard cap on how full each package may be packed\n\n**Details:** Type `number` · Default: `85` · min `10` · max `100`."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."},"packaging_type_ids":{"type":"array","description":"Select whole packaging categories as candidates\n\n**Details:** Type `array`, items `integer`.","items":{"type":"integer","description":"Packaging type ids. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."}},"packaging_ids":{"type":"array","description":"Select specific packagings as candidates\n\n**Details:** Type `array`, items `integer`.","items":{"type":"integer","description":"Packaging ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."}},"custom_packagings":{"type":"array","maxItems":30,"description":"Ad-hoc packaging sizes stored only inside this plan. Dimensions are given in dimension_unit, weights in weight_unit; values are stored both as typed and converted to canonical mm/g.\n\n**Details:** Type `array`, items `object` · maxItems `30`.","items":{"type":"object","required":["name","inner_length","inner_width","inner_height"],"properties":{"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"dimension_unit":{"type":"integer","enum":[1,2,3,4],"default":2,"description":"Input unit for inner_length/inner_width/inner_height: 1=mm, 2=cm, 3=m, 4=inch\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `2`."},"inner_length":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nInner length in dimension_unit\n\n**Details:** Type `number` · exclusiveMin `0`."},"inner_width":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nInner width in dimension_unit\n\n**Details:** Type `number` · exclusiveMin `0`."},"inner_height":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nInner height in dimension_unit\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_unit":{"type":"integer","enum":[1,2,3,4],"default":2,"description":"Input unit for max_payload/tare_weight: 1=g, 2=kg, 3=oz, 4=lb\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `2`."},"max_payload":{"type":["number","null"],"exclusiveMinimum":0,"description":"Maximum payload in weight_unit\n\n**Details:** Type `number` · Nullable · exclusiveMin `0`."},"tare_weight":{"type":["number","null"],"minimum":0,"description":"Tare weight in weight_unit\n\n**Details:** Type `number` · Nullable · min `0`."},"unit_cost":{"type":["number","null"],"minimum":0,"description":"Unit cost. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number` · Nullable · min `0`."},"quantity_limit":{"type":["integer","null"],"minimum":1,"maximum":200,"description":"Quantity limit. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable · min `1` · max `200`."}}}}}},"example":{"name":"Retail order 4512 split","reference":"PP-2026-001","target_utilization_percent":85,"packaging_type_ids":[2],"packaging_ids":[15],"custom_packagings":[{"name":"Slim mailer box","dimension_unit":2,"inner_length":40,"inner_width":30,"inner_height":15,"weight_unit":2,"max_payload":12,"tare_weight":0.35,"unit_cost":1.2,"quantity_limit":10}]}}}},"responses":{"201":{"description":"Packing plan created","content":{"application/json":{"example":{"success":true,"data":{"plan":{"id":7,"name":"Retail order 4512 split","reference":"PP-2026-001","status":"draft","target_utilization_percent":85,"item_count":1,"latest_result_id":null,"latest_package_count":null,"created_at":"2026-07-27T09:00:00-04:00","updated_at":"2026-07-27T09:10:00-04:00","notes":null,"packaging_type_ids":[2],"packaging_ids":[15],"custom_packagings":[{"name":"Slim mailer box","dimension_unit":2,"weight_unit":2,"inner_length_mm":400,"inner_width_mm":300,"inner_height_mm":150,"inner_length":40,"inner_width":30,"inner_height":15,"max_payload_g":12000,"max_payload":12,"tare_weight_g":350,"tare_weight":0.35,"unit_cost":1.2,"quantity_limit":10}]}}}}}},"422":{"description":"Validation failed (error.code VALIDATION_FAILED with per-field messages in error.fields)"}}}},"/v1/packing-plans/{plan}":{"get":{"tags":["Packing Plans"],"summary":"Get a packing plan with its packaging selections","operationId":"packingPlan","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Packing plan detail including packaging_type_ids[], packaging_ids[] and custom_packagings[]","content":{"application/json":{"example":{"success":true,"data":{"plan":{"id":7,"name":"Retail order 4512 split","reference":"PP-2026-001","status":"draft","target_utilization_percent":85,"item_count":1,"latest_result_id":null,"latest_package_count":null,"created_at":"2026-07-27T09:00:00-04:00","updated_at":"2026-07-27T09:10:00-04:00","notes":null,"packaging_type_ids":[2],"packaging_ids":[15],"custom_packagings":[{"name":"Slim mailer box","dimension_unit":2,"weight_unit":2,"inner_length_mm":400,"inner_width_mm":300,"inner_height_mm":150,"inner_length":40,"inner_width":30,"inner_height":15,"max_payload_g":12000,"max_payload":12,"tare_weight_g":350,"tare_weight":0.35,"unit_cost":1.2,"quantity_limit":10}]}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"}}},"put":{"tags":["Packing Plans"],"summary":"Update a packing plan and replace its packaging selections","operationId":"updatePackingPlan","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Candidate packagings come from packaging_type_ids (whole packaging categories), packaging_ids (specific packagings) and custom_packagings. An empty selection means every active packaging of the business is a candidate.","required":["name"],"properties":{"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"reference":{"type":["string","null"],"maxLength":100,"description":"External reference, unique per business\n\n**Details:** Type `string` · Nullable · maxLength `100`."},"target_utilization_percent":{"type":"number","minimum":10,"maximum":100,"default":85,"description":"Hard cap on how full each package may be packed\n\n**Details:** Type `number` · Default: `85` · min `10` · max `100`."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."},"packaging_type_ids":{"type":"array","description":"Select whole packaging categories as candidates\n\n**Details:** Type `array`, items `integer`.","items":{"type":"integer","description":"Packaging type ids. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."}},"packaging_ids":{"type":"array","description":"Select specific packagings as candidates\n\n**Details:** Type `array`, items `integer`.","items":{"type":"integer","description":"Packaging ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."}},"custom_packagings":{"type":"array","maxItems":30,"description":"Ad-hoc packaging sizes stored only inside this plan. Dimensions are given in dimension_unit, weights in weight_unit; values are stored both as typed and converted to canonical mm/g.\n\n**Details:** Type `array`, items `object` · maxItems `30`.","items":{"type":"object","required":["name","inner_length","inner_width","inner_height"],"properties":{"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"dimension_unit":{"type":"integer","enum":[1,2,3,4],"default":2,"description":"Input unit for inner_length/inner_width/inner_height: 1=mm, 2=cm, 3=m, 4=inch\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `2`."},"inner_length":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nInner length in dimension_unit\n\n**Details:** Type `number` · exclusiveMin `0`."},"inner_width":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nInner width in dimension_unit\n\n**Details:** Type `number` · exclusiveMin `0`."},"inner_height":{"type":"number","exclusiveMinimum":0,"description":"**Required.**\n\nInner height in dimension_unit\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_unit":{"type":"integer","enum":[1,2,3,4],"default":2,"description":"Input unit for max_payload/tare_weight: 1=g, 2=kg, 3=oz, 4=lb\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `2`."},"max_payload":{"type":["number","null"],"exclusiveMinimum":0,"description":"Maximum payload in weight_unit\n\n**Details:** Type `number` · Nullable · exclusiveMin `0`."},"tare_weight":{"type":["number","null"],"minimum":0,"description":"Tare weight in weight_unit\n\n**Details:** Type `number` · Nullable · min `0`."},"unit_cost":{"type":["number","null"],"minimum":0,"description":"Unit cost. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number` · Nullable · min `0`."},"quantity_limit":{"type":["integer","null"],"minimum":1,"maximum":200,"description":"Quantity limit. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable · min `1` · max `200`."}}}}}},"example":{"name":"Retail order 4512 split","reference":"PP-2026-001","target_utilization_percent":85,"packaging_type_ids":[2],"packaging_ids":[15],"custom_packagings":[{"name":"Slim mailer box","dimension_unit":2,"inner_length":40,"inner_width":30,"inner_height":15,"weight_unit":2,"max_payload":12,"tare_weight":0.35,"unit_cost":1.2,"quantity_limit":10}]}}}},"responses":{"200":{"description":"Packing plan updated","content":{"application/json":{"example":{"success":true,"data":{"plan":{"id":7,"name":"Retail order 4512 split","reference":"PP-2026-001","status":"draft","target_utilization_percent":85,"item_count":1,"latest_result_id":null,"latest_package_count":null,"created_at":"2026-07-27T09:00:00-04:00","updated_at":"2026-07-27T09:10:00-04:00","notes":null,"packaging_type_ids":[2],"packaging_ids":[15],"custom_packagings":[{"name":"Slim mailer box","dimension_unit":2,"weight_unit":2,"inner_length_mm":400,"inner_width_mm":300,"inner_height_mm":150,"inner_length":40,"inner_width":30,"inner_height":15,"max_payload_g":12000,"max_payload":12,"tare_weight_g":350,"tare_weight":0.35,"unit_cost":1.2,"quantity_limit":10}]}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"},"409":{"description":"Plan already finalized (error.code PLAN_FINALIZED)"},"422":{"description":"Validation failed (error.code VALIDATION_FAILED with per-field messages in error.fields)"}}},"delete":{"tags":["Packing Plans"],"summary":"Delete a packing plan","operationId":"deletePackingPlan","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Packing plan deleted","content":{"application/json":{"example":{"success":true,"data":{"deleted":true}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"}}}},"/v1/packing-plans/{plan}/items":{"get":{"tags":["Packing Plans"],"summary":"List items of a packing plan","operationId":"packingPlanItems","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Items of the plan","content":{"application/json":{"example":{"success":true,"data":{"items":[{"id":31,"packing_plan_id":7,"product_id":null,"name":"Ceramic mug","sku":"MUG-01","quantity":24,"length_mm":119.38,"width_mm":88.9,"height_mm":104.14,"weight_g":421.841,"dimension_unit":4,"weight_unit":4,"length":4.7,"width":3.5,"height":4.1,"weight":0.93,"can_rotate":true,"stackable":true,"max_stack_layers":null,"orientation":"any","notes":null}]}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"}}},"post":{"tags":["Packing Plans"],"summary":"Add an item to a packing plan","operationId":"createPackingPlanItem","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Dimensions and weight are mandatory: provide either length/width/height and weight in the selected dimension_unit/weight_unit (preferred), or the canonical length_mm/width_mm/height_mm and weight_g fields directly. When the canonical mm/g fields are submitted, dimension_unit/weight_unit default to 1 (mm/g).","required":["name","quantity"],"properties":{"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"sku":{"type":["string","null"],"description":"Stock keeping unit / product code.\n\n**Details:** Type `string` · Nullable."},"product_id":{"type":["integer","null"],"description":"Product id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"quantity":{"type":"integer","minimum":1,"maximum":20000,"description":"**Required.**\n\nQuantity of units.\n\n**Details:** Type `integer` · min `1` · max `20000`."},"dimension_unit":{"type":"integer","enum":[1,2,3,4],"default":2,"description":"Input unit for length/width/height: 1=mm, 2=cm, 3=m, 4=inch\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `2`."},"length":{"type":"number","exclusiveMinimum":0,"description":"Length in dimension_unit; required unless length_mm is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"width":{"type":"number","exclusiveMinimum":0,"description":"Width in dimension_unit; required unless width_mm is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"height":{"type":"number","exclusiveMinimum":0,"description":"Height in dimension_unit; required unless height_mm is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_unit":{"type":"integer","enum":[1,2,3,4],"default":2,"description":"Input unit for weight: 1=g, 2=kg, 3=oz, 4=lb\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `2`."},"weight":{"type":"number","exclusiveMinimum":0,"description":"Weight in weight_unit; required unless weight_g is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"length_mm":{"type":"number","exclusiveMinimum":0,"description":"Canonical millimeters; required unless length is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"width_mm":{"type":"number","exclusiveMinimum":0,"description":"Canonical millimeters; required unless width is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"height_mm":{"type":"number","exclusiveMinimum":0,"description":"Canonical millimeters; required unless height is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_g":{"type":"number","exclusiveMinimum":0,"description":"Canonical grams; required unless weight is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"can_rotate":{"type":"boolean","default":true,"description":"Can rotate. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean` · Default: `true`."},"stackable":{"type":"boolean","default":true,"description":"Stackable. Field in the JSON request body.\n\n**Details:** Type `boolean` · Default: `true`."},"max_stack_layers":{"type":["integer","null"],"minimum":1,"description":"Max stack layers. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable · min `1`."},"orientation":{"type":"string","enum":["any","upright_only","side_only"],"description":"Allowed values: `any` · `upright_only` · `side_only`.\n\n**Details:** Type `string`."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."}}},"example":{"name":"Ceramic mug","sku":"MUG-01","quantity":24,"dimension_unit":4,"length":4.7,"width":3.5,"height":4.1,"weight_unit":4,"weight":0.93,"can_rotate":true,"stackable":true,"orientation":"any"}}}},"responses":{"201":{"description":"Item created","content":{"application/json":{"example":{"success":true,"data":{"item":{"id":31,"packing_plan_id":7,"product_id":null,"name":"Ceramic mug","sku":"MUG-01","quantity":24,"length_mm":119.38,"width_mm":88.9,"height_mm":104.14,"weight_g":421.841,"dimension_unit":4,"weight_unit":4,"length":4.7,"width":3.5,"height":4.1,"weight":0.93,"can_rotate":true,"stackable":true,"max_stack_layers":null,"orientation":"any","notes":null}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"},"409":{"description":"Plan already finalized (error.code PLAN_FINALIZED)"},"422":{"description":"Validation failed (error.code VALIDATION_FAILED with per-field messages in error.fields)"}}}},"/v1/packing-plans/{plan}/items/{item}":{"put":{"tags":["Packing Plans"],"summary":"Update a packing plan item","operationId":"updatePackingPlanItem","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"item","required":true,"schema":{"type":"integer","description":"Item. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Item. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Dimensions and weight are mandatory: provide either length/width/height and weight in the selected dimension_unit/weight_unit (preferred), or the canonical length_mm/width_mm/height_mm and weight_g fields directly. When the canonical mm/g fields are submitted, dimension_unit/weight_unit default to 1 (mm/g).","required":["name","quantity"],"properties":{"name":{"type":"string","maxLength":150,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `150`."},"sku":{"type":["string","null"],"description":"Stock keeping unit / product code.\n\n**Details:** Type `string` · Nullable."},"product_id":{"type":["integer","null"],"description":"Product id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"quantity":{"type":"integer","minimum":1,"maximum":20000,"description":"**Required.**\n\nQuantity of units.\n\n**Details:** Type `integer` · min `1` · max `20000`."},"dimension_unit":{"type":"integer","enum":[1,2,3,4],"default":2,"description":"Input unit for length/width/height: 1=mm, 2=cm, 3=m, 4=inch\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `2`."},"length":{"type":"number","exclusiveMinimum":0,"description":"Length in dimension_unit; required unless length_mm is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"width":{"type":"number","exclusiveMinimum":0,"description":"Width in dimension_unit; required unless width_mm is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"height":{"type":"number","exclusiveMinimum":0,"description":"Height in dimension_unit; required unless height_mm is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_unit":{"type":"integer","enum":[1,2,3,4],"default":2,"description":"Input unit for weight: 1=g, 2=kg, 3=oz, 4=lb\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `2`."},"weight":{"type":"number","exclusiveMinimum":0,"description":"Weight in weight_unit; required unless weight_g is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"length_mm":{"type":"number","exclusiveMinimum":0,"description":"Canonical millimeters; required unless length is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"width_mm":{"type":"number","exclusiveMinimum":0,"description":"Canonical millimeters; required unless width is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"height_mm":{"type":"number","exclusiveMinimum":0,"description":"Canonical millimeters; required unless height is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_g":{"type":"number","exclusiveMinimum":0,"description":"Canonical grams; required unless weight is provided\n\n**Details:** Type `number` · exclusiveMin `0`."},"can_rotate":{"type":"boolean","default":true,"description":"Can rotate. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean` · Default: `true`."},"stackable":{"type":"boolean","default":true,"description":"Stackable. Field in the JSON request body.\n\n**Details:** Type `boolean` · Default: `true`."},"max_stack_layers":{"type":["integer","null"],"minimum":1,"description":"Max stack layers. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable · min `1`."},"orientation":{"type":"string","enum":["any","upright_only","side_only"],"description":"Allowed values: `any` · `upright_only` · `side_only`.\n\n**Details:** Type `string`."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."}}},"example":{"name":"Ceramic mug","sku":"MUG-01","quantity":24,"dimension_unit":4,"length":4.7,"width":3.5,"height":4.1,"weight_unit":4,"weight":0.93,"can_rotate":true,"stackable":true,"orientation":"any"}}}},"responses":{"200":{"description":"Item updated","content":{"application/json":{"example":{"success":true,"data":{"item":{"id":31,"packing_plan_id":7,"product_id":null,"name":"Ceramic mug","sku":"MUG-01","quantity":24,"length_mm":119.38,"width_mm":88.9,"height_mm":104.14,"weight_g":421.841,"dimension_unit":4,"weight_unit":4,"length":4.7,"width":3.5,"height":4.1,"weight":0.93,"can_rotate":true,"stackable":true,"max_stack_layers":null,"orientation":"any","notes":null}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"},"409":{"description":"Plan already finalized (error.code PLAN_FINALIZED)"},"422":{"description":"Validation failed (error.code VALIDATION_FAILED with per-field messages in error.fields)"}}},"delete":{"tags":["Packing Plans"],"summary":"Delete a packing plan item","operationId":"deletePackingPlanItem","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"item","required":true,"schema":{"type":"integer","description":"Item. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Item. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Item deleted","content":{"application/json":{"example":{"success":true,"data":{"deleted":true}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"},"409":{"description":"Plan already finalized (error.code PLAN_FINALIZED)"}}}},"/v1/packing-plans/{plan}/solve":{"post":{"tags":["Packing Plans"],"summary":"Solve a packing plan synchronously","description":"Runs the carton packing solver synchronously and stores a new result. Candidates are ranked: pack everything first, then smallest total outer volume, then fewest packages, then lowest cost. Each package's metrics include a gravity object: cog_x_mm/cog_y_mm/cog_z_mm (weighted center of gravity in mm from the package origin), offset_x_percent/offset_y_percent (horizontal offset from the floor center as percent of the half side; flagged at >=20), cog_height_percent (CoG height as percent of inner height; above 60 is flagged top-heavy) and balanced (bool). Candidate-level warnings[] may contain GRAVITY_IMBALANCED.","operationId":"solvePackingPlan","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"201":{"description":"Solve completed; full solver output is included in data.result.output","content":{"application/json":{"example":{"success":true,"data":{"result":{"id":21,"packing_plan_id":7,"status":"completed","solver_version":"1.0.0","validator_version":"1.0.0","package_count":2,"total_cost":2.4,"checksum":"9f2c1d0b7a8e5f4c3b2a1908d7c6b5a4","created_at":"2026-07-27T09:12:00-04:00","output":{"target_utilization_percent":85,"unpackable":[],"candidates":[{"rank":1,"strategy":"mixed","totals":{"package_count":2,"total_outer_volume_mm3":48000000,"total_inner_volume_mm3":43200000,"packed_volume_mm3":27216000,"wasted_volume_mm3":15984000,"overall_utilization_percent":63,"total_net_weight_g":10080,"total_gross_weight_g":10780,"total_cost":2.4,"unplaced_quantity":0},"warnings":[],"unplaced":[],"packages":[{"package_index":1,"packaging":{"key":"packaging:15","name":"Medium carton","inner_length_mm":400,"inner_width_mm":300,"inner_height_mm":180,"outer_volume_mm3":24000000,"max_payload_g":15000,"tare_weight_g":350,"unit_cost":1.2},"items":[{"item_id":31,"name":"Ceramic mug","sku":"MUG-01","quantity":12}],"metrics":{"unit_count":12,"packed_volume_mm3":13608000,"inner_volume_mm3":21600000,"utilization_percent":63,"net_weight_g":5040,"gross_weight_g":5390,"gravity":{"cog_x_mm":205,"cog_y_mm":152.7,"cog_z_mm":58.5,"offset_x_percent":2.5,"offset_y_percent":1.8,"cog_height_percent":32.5,"balanced":true}},"placements":[{"x_mm":0,"y_mm":0,"z_mm":0,"length_mm":120,"width_mm":90,"height_mm":105,"weight_g":420,"rotation_key":"LWH","item_id":31,"name":"Ceramic mug","unit_sequence":1}],"validation":{"passed":true},"checksum":"1a2b3c4d5e6f708192a3b4c5d6e7f809"}]}]}}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"},"409":{"description":"Plan already finalized (error.code PLAN_FINALIZED)"},"422":{"description":"Domain validation failed (error.code one of NO_CANDIDATE_PACKAGING, PACKAGING_CANDIDATE_LIMIT, NO_ITEMS, ITEM_ROW_LIMIT, ITEM_UNIT_LIMIT, PACKAGING_DIMENSIONS_INVALID, or VALIDATION_FAILED)"}}}},"/v1/packing-plans/{plan}/results":{"get":{"tags":["Packing Plans"],"summary":"List solve results of a packing plan","operationId":"packingPlanResults","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Result summaries, newest first","content":{"application/json":{"example":{"success":true,"data":{"results":[{"id":21,"packing_plan_id":7,"status":"completed","solver_version":"1.0.0","validator_version":"1.0.0","package_count":2,"total_cost":2.4,"checksum":"9f2c1d0b7a8e5f4c3b2a1908d7c6b5a4","created_at":"2026-07-27T09:12:00-04:00"}]}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"}}}},"/v1/packing-plans/{plan}/results/{result}":{"get":{"tags":["Packing Plans"],"summary":"Get one solve result with ranked candidates","description":"Candidates are ranked: pack everything first, then smallest total outer volume, then fewest packages, then lowest cost. Each package's metrics include a gravity object: cog_x_mm/cog_y_mm/cog_z_mm (weighted center of gravity in mm from the package origin), offset_x_percent/offset_y_percent (horizontal offset from the floor center as percent of the half side; flagged at >=20), cog_height_percent (CoG height as percent of inner height; above 60 is flagged top-heavy) and balanced (bool). Candidate-level warnings[] may contain GRAVITY_IMBALANCED.","operationId":"packingPlanResult","security":[{"passport":[]}],"parameters":[{"in":"path","name":"plan","required":true,"schema":{"type":"integer","description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},"description":"Loading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"result","required":true,"schema":{"type":"integer","description":"Result. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Result. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Result detail including output with ranked candidates, packages and placements","content":{"application/json":{"example":{"success":true,"data":{"result":{"id":21,"packing_plan_id":7,"status":"completed","solver_version":"1.0.0","validator_version":"1.0.0","package_count":2,"total_cost":2.4,"checksum":"9f2c1d0b7a8e5f4c3b2a1908d7c6b5a4","created_at":"2026-07-27T09:12:00-04:00","output":{"target_utilization_percent":85,"unpackable":[],"candidates":[{"rank":1,"strategy":"mixed","totals":{"package_count":2,"total_outer_volume_mm3":48000000,"total_inner_volume_mm3":43200000,"packed_volume_mm3":27216000,"wasted_volume_mm3":15984000,"overall_utilization_percent":63,"total_net_weight_g":10080,"total_gross_weight_g":10780,"total_cost":2.4,"unplaced_quantity":0},"warnings":[],"unplaced":[],"packages":[{"package_index":1,"packaging":{"key":"packaging:15","name":"Medium carton","inner_length_mm":400,"inner_width_mm":300,"inner_height_mm":180,"outer_volume_mm3":24000000,"max_payload_g":15000,"tare_weight_g":350,"unit_cost":1.2},"items":[{"item_id":31,"name":"Ceramic mug","sku":"MUG-01","quantity":12}],"metrics":{"unit_count":12,"packed_volume_mm3":13608000,"inner_volume_mm3":21600000,"utilization_percent":63,"net_weight_g":5040,"gross_weight_g":5390,"gravity":{"cog_x_mm":205,"cog_y_mm":152.7,"cog_z_mm":58.5,"offset_x_percent":2.5,"offset_y_percent":1.8,"cog_height_percent":32.5,"balanced":true}},"placements":[{"x_mm":0,"y_mm":0,"z_mm":0,"length_mm":120,"width_mm":90,"height_mm":105,"weight_g":420,"rotation_key":"LWH","item_id":31,"name":"Ceramic mug","unit_sequence":1}],"validation":{"passed":true},"checksum":"1a2b3c4d5e6f708192a3b4c5d6e7f809"}]}]}}}}}}},"404":{"description":"Not found in authenticated business (error.code NOT_FOUND)"}}}},"/v1/otep/trackings/{trackingNumber}":{"get":{"tags":["OTEP"],"summary":"Get the OTEP tracking timeline for a tracking number","description":"Public endpoint. Returns the unified OTEP event timeline across self-delivery, third-party and carrier sources. Use ?format=epcis|onerecord|uncefact (or an Accept profile) to project to an external standard; default is native OTEP.","operationId":"otepTracking","parameters":[{"in":"path","name":"trackingNumber","schema":{"type":"string","description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`."},"required":true,"description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`.","example":"SR123456789"},{"in":"query","name":"format","schema":{"type":"string","enum":["otep","epcis","onerecord","uncefact","otlp","aftership","shopify","amazon","walmart","bigcommerce","magento","woocommerce","etsy","sensorthings"],"description":"Output format (default otep)\n\nAllowed values: `otep` · `epcis` · `onerecord` · `uncefact` · `otlp` · `aftership` · `shopify` · `amazon` · `walmart` · `bigcommerce` · `magento` · `woocommerce` · `etsy` · `sensorthings`.\n\n**Details:** Optional · Type `string`."},"required":false,"description":"Output format (default otep)\n\nAllowed values: `otep` · `epcis` · `onerecord` · `uncefact` · `otlp` · `aftership` · `shopify` · `amazon` · `walmart` · `bigcommerce` · `magento` · `woocommerce` · `etsy` · `sensorthings`.\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"format":{"type":"string","description":"Format. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `otep`.","examples":["otep"]},"data":{"type":"object","description":"OTEP timeline (native) or the requested standard projection\n\n**Details:** Type `object`."}}}}}},"404":{"description":"Tracking number not found"}}}},"/v1/otep/trackings/{trackingNumber}/events":{"get":{"tags":["OTEP"],"summary":"Get only the OTEP events for a tracking number","operationId":"otepTrackingEvents","parameters":[{"in":"path","name":"trackingNumber","schema":{"type":"string","description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`."},"required":true,"description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`.","example":"SR123456789"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"type":"object","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"404":{"description":"Tracking number not found"}}}},"/v1/otep/trackings/batch":{"post":{"tags":["OTEP"],"summary":"Get OTEP timelines for many tracking numbers in one call","operationId":"otepTrackingBatch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tracking_numbers"],"properties":{"tracking_numbers":{"type":"array","items":{"type":"string","description":"Tracking numbers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"**Required.**\n\nTracking numbers. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`.","examples":[["SR123456789","SR987654321"]]},"format":{"type":"string","enum":["otep","epcis","onerecord","uncefact","otlp","aftership","shopify","amazon","walmart","bigcommerce","magento","woocommerce","etsy","sensorthings"],"description":"Allowed values: `otep` · `epcis` · `onerecord` · `uncefact` · `otlp` · `aftership` · `shopify` · `amazon` · `walmart` · `bigcommerce` · `magento` · `woocommerce` · `etsy` · `sensorthings`.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"format":{"type":"string","description":"Format. Field in the JSON request body.\n\n**Details:** Type `string`."},"data":{"type":"array","items":{"type":"object","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"truncated":{"type":"boolean","description":"True when the input exceeded the 100-item cap\n\n**Details:** Type `boolean`."}}}}}},"422":{"description":"tracking_numbers (non-empty array) is required"}}}},"/v1/otep/ingest":{"post":{"tags":["OTEP"],"summary":"Ingest inbound OTEP tracking events from a third-party delivery provider","operationId":"otepIngest","description":"The write side of OTEP. A carrier or partner pushes a native OTEP timeline (or the bare {subject, events} form) and each event is normalised and written through the writer that already owns the shipment: the sender's third-party delivery assignment, or a label tracker of the sender's linked shipping method. Events for a self-delivery order are refused; events that resolve to nothing are counted unresolved and logged, never parked.\n\n**Authentication**: the same credentials as the third-party delivery webhook — `Authorization: Bearer <token>` with the provider's dedicated webhook token (also accepted as the bare header value) or the owning customer / client API token. Pass `X-Provider-Id` (or `provider_id`) when the credential owns several webhook-enabled providers.\n\nThe call answers 200 even when some events were refused: the counts and per-event outcomes carry the detail, so no event is ever lost silently.","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Provider-Id","in":"header","required":false,"schema":{"type":"integer","description":"The provider the events speak for, when the credential owns several.\n\n**Details:** Optional · Type `integer`."},"description":"The provider the events speak for, when the credential owns several.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","events"],"properties":{"otep_version":{"type":"string","description":"Defaults to 1.0 when omitted.\n\n**Details:** Type `string`.","examples":["1.0"]},"profile":{"type":"string","description":"Defaults to parcel when omitted.\n\n**Details:** Type `string`.","examples":["parcel"]},"subject":{"type":"object","description":"**Required.**\n\nAt least one of tracking_number / order_id. The tracking number may be the carrier's own number on the assignment, the assignment's external order number, the Superroute tracking number, or the urn:superroute:shipment:{trackingNumber} URN our EPCIS projection emits.\n\n**Details:** Type `object`.","properties":{"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`.\n\n**Example:** `CARRIER-12345`.","examples":["CARRIER-12345"]},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."}}},"events":{"type":"array","description":"**Required.**\n\nOTEP events (Level 1 conformant). Each event needs occurred_at (ISO-8601 with offset), a status_code from the OTEP vocabulary (or null with source.external_event_code and a provider mapping), and source.type.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"occurred_at":{"type":"string","description":"When the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string`.\n\n**Example:** `2026-09-24T10:00:00-04:00`.","examples":["2026-09-24T10:00:00-04:00"]},"status_code":{"type":["string","null"],"description":"Status code. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `delivered`.","examples":["delivered"]},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable."},"location":{"type":["object","null"],"properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}},"description":"Location. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"incident_reason":{"type":["string","null"],"description":"Incident reason. Free-text note.\n\n**Details:** Type `string` · Nullable."},"source":{"type":"object","properties":{"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`.\n\n**Example:** `third_party_delivery`.","examples":["third_party_delivery"]},"external_event_id":{"type":"string","description":"The sender's own event id — the idempotency key. When omitted, a stable digest of the event is used, so a resend still answers duplicate.\n\n**Details:** Type `string`."},"external_event_code":{"type":"string","description":"The sender's raw code, resolved through the provider's event-code mappings when status_code is null.\n\n**Details:** Type `string`."}},"description":"Document or data source selector for this developer-center export.\n\n**Details:** Type `object`."}}}}}}}}},"responses":{"200":{"description":"Processed. Counts and per-event outcomes; refused or unresolved events are reported, not silently lost.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"counts":{"type":"object","properties":{"accepted":{"type":"integer","description":"Accepted. Field in the JSON request body.\n\n**Details:** Type `integer`."},"duplicate":{"type":"integer","description":"Duplicate. Field in the JSON request body.\n\n**Details:** Type `integer`."},"unmapped":{"type":"integer","description":"Unmapped. Field in the JSON request body.\n\n**Details:** Type `integer`."},"refused":{"type":"integer","description":"Refused. Field in the JSON request body.\n\n**Details:** Type `integer`."},"dropped_post_final":{"type":"integer","description":"Dropped post final. Field in the JSON request body.\n\n**Details:** Type `integer`."},"unresolved":{"type":"integer","description":"Unresolved. Field in the JSON request body.\n\n**Details:** Type `integer`."},"missing_occurred_at":{"type":"integer","description":"Missing occurred at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`."}},"description":"Counts. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"events":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Index. Field in the JSON request body.\n\n**Details:** Type `integer`."},"outcome":{"type":"string","description":"Outcome. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `accepted`.","examples":["accepted"]},"otep_code":{"type":["string","null"],"description":"Otep code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"action_code":{"type":["string","null"],"description":"Superroute third-party delivery action code. Maps to order status + tracking event via `ThirdPartyDeliveryActionMap`.\n\nEnum values (from deployed code):\n- `booking_confirmed` — Booking Confirmed\n- `awaiting_pickup` — Awaiting Pickup\n- `received` — Received\n- `a_scan` — A Scan\n- `package_outbound` — Package Outbound\n- `in_transit` — In Transit\n- `loaded` — Loaded\n- `facility_received` — Facility Received\n- `arrived_at_facility` — Arrived At Facility\n- `on_hold` — On Hold\n- `collection_on_hold` — Collection On Hold\n- `customs_clearance` — Customs Clearance\n- `out_for_delivery` — Out For Delivery\n- `delivered` — Delivered\n- `partial_delivered` — Partial Delivered\n- `delivery_failed` — Delivery Failed\n- `reschedule_required` — Reschedule Required\n- `return_to_sender` — Return To Sender\n- `rejected_by_recipient` — Rejected By Recipient\n- `cancelled` — Cancelled\n\n**Details:** Type `string` · Nullable.","enum":["booking_confirmed","awaiting_pickup","received","a_scan","package_outbound","in_transit","loaded","facility_received","arrived_at_facility","on_hold","collection_on_hold","customs_clearance","out_for_delivery","delivered","partial_delivered","delivery_failed","reschedule_required","return_to_sender","rejected_by_recipient","cancelled",null],"x-enumDescriptions":["Booking Confirmed","Awaiting Pickup","Received","A Scan","Package Outbound","In Transit","Loaded","Facility Received","Arrived At Facility","On Hold","Collection On Hold","Customs Clearance","Out For Delivery","Delivered","Partial Delivered","Delivery Failed","Reschedule Required","Return To Sender","Rejected By Recipient","Cancelled"]},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."}}},"description":"Events. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"counts":{"accepted":1,"duplicate":0,"unmapped":0,"refused":0,"dropped_post_final":0,"unresolved":0,"missing_occurred_at":0},"events":[{"index":0,"outcome":"accepted","otep_code":"delivered","action_code":"delivered","reason":null}]}}}},"401":{"description":"Bad credentials"},"404":{"description":"No webhook-enabled provider matches this credential"},"422":{"description":"The payload does not parse, fails OTEP Level 1 validation, or exceeds the per-request event cap (500)"}}}},"/v1/otep/ingest/epcis":{"post":{"tags":["OTEP"],"summary":"Ingest a GS1 EPCIS 2.0 document of inbound tracking events","operationId":"otepIngestEpcis","description":"Accepts an EPCIS 2.0 EPCISDocument (JSON-LD, Content-Type application/ld+json or application/json). Each ObjectEvent with action OBSERVE or ADD is mapped to the OTEP vocabulary through the built-in (bizStep, disposition) crosswalk — an `otep:statusCode` extension field on the event states the exact code and wins over the table, and the provider's own event-code mapping rows (keys prefixed `epcis:`) win over both. Subjects resolve from epcList / parentID: the urn:superroute:shipment:{trackingNumber} URN our own EPCIS projection emits, or a bare tracking number. An SSCC-only event is counted unresolved, never guessed.\n\n**Authentication**: same as /v1/otep/ingest. The response shape and status codes are the same as /v1/otep/ingest.","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Provider-Id","in":"header","required":false,"schema":{"type":"integer","description":"The provider the events speak for, when the credential owns several.\n\n**Details:** Optional · Type `integer`."},"description":"The provider the events speak for, when the credential owns several.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["epcisBody"],"properties":{"@context":{"type":"array","items":{"type":"string","description":"@context. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"@context. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`.","examples":[["https://ref.gs1.org/standards/epcis/epcis-context.jsonld"]]},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`.\n\n**Example:** `EPCISDocument`.","examples":["EPCISDocument"]},"epcisBody":{"type":"object","properties":{"eventList":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`.\n\n**Example:** `ObjectEvent`.","examples":["ObjectEvent"]},"action":{"type":"string","description":"Action. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `OBSERVE`.","examples":["OBSERVE"]},"eventID":{"type":"string","description":"Event id. Identifier referencing the related record.\n\n**Details:** Type `string`.\n\n**Example:** `urn:uuid:11111111-1111-1111-1111-111111111111`.","examples":["urn:uuid:11111111-1111-1111-1111-111111111111"]},"eventTime":{"type":"string","description":"Event time. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `2026-09-24T14:00:00Z`.","examples":["2026-09-24T14:00:00Z"]},"bizStep":{"type":"string","description":"Biz step. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `urn:epcglobal:cbv:bizstep:receiving`.","examples":["urn:epcglobal:cbv:bizstep:receiving"]},"disposition":{"type":"string","description":"Disposition. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `urn:epcglobal:cbv:disp:received`.","examples":["urn:epcglobal:cbv:disp:received"]},"epcList":{"type":"array","items":{"type":"string","description":"Epc list. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Epc list. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`.","examples":[["urn:superroute:shipment:CARRIER-12345"]]},"readPoint":{"type":"object","properties":{"id":{"type":"string","description":"Resource identifier.\n\n**Details:** Type `string`."}},"description":"Read point. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"description":"Event list. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"**Required.**\n\nEpcis body. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"Processed. Same counts and per-event outcomes as /v1/otep/ingest.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"counts":{"type":"object","properties":{"accepted":{"type":"integer","description":"Accepted. Field in the JSON request body.\n\n**Details:** Type `integer`."},"duplicate":{"type":"integer","description":"Duplicate. Field in the JSON request body.\n\n**Details:** Type `integer`."},"unmapped":{"type":"integer","description":"Unmapped. Field in the JSON request body.\n\n**Details:** Type `integer`."},"refused":{"type":"integer","description":"Refused. Field in the JSON request body.\n\n**Details:** Type `integer`."},"dropped_post_final":{"type":"integer","description":"Dropped post final. Field in the JSON request body.\n\n**Details:** Type `integer`."},"unresolved":{"type":"integer","description":"Unresolved. Field in the JSON request body.\n\n**Details:** Type `integer`."},"missing_occurred_at":{"type":"integer","description":"Missing occurred at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`."}},"description":"Counts. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"events":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Index. Field in the JSON request body.\n\n**Details:** Type `integer`."},"outcome":{"type":"string","description":"Outcome. Field in the JSON request body.\n\n**Details:** Type `string`."},"otep_code":{"type":["string","null"],"description":"Otep code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"action_code":{"type":["string","null"],"description":"Superroute third-party delivery action code. Maps to order status + tracking event via `ThirdPartyDeliveryActionMap`.\n\nEnum values (from deployed code):\n- `booking_confirmed` — Booking Confirmed\n- `awaiting_pickup` — Awaiting Pickup\n- `received` — Received\n- `a_scan` — A Scan\n- `package_outbound` — Package Outbound\n- `in_transit` — In Transit\n- `loaded` — Loaded\n- `facility_received` — Facility Received\n- `arrived_at_facility` — Arrived At Facility\n- `on_hold` — On Hold\n- `collection_on_hold` — Collection On Hold\n- `customs_clearance` — Customs Clearance\n- `out_for_delivery` — Out For Delivery\n- `delivered` — Delivered\n- `partial_delivered` — Partial Delivered\n- `delivery_failed` — Delivery Failed\n- `reschedule_required` — Reschedule Required\n- `return_to_sender` — Return To Sender\n- `rejected_by_recipient` — Rejected By Recipient\n- `cancelled` — Cancelled\n\n**Details:** Type `string` · Nullable.","enum":["booking_confirmed","awaiting_pickup","received","a_scan","package_outbound","in_transit","loaded","facility_received","arrived_at_facility","on_hold","collection_on_hold","customs_clearance","out_for_delivery","delivered","partial_delivered","delivery_failed","reschedule_required","return_to_sender","rejected_by_recipient","cancelled",null],"x-enumDescriptions":["Booking Confirmed","Awaiting Pickup","Received","A Scan","Package Outbound","In Transit","Loaded","Facility Received","Arrived At Facility","On Hold","Collection On Hold","Customs Clearance","Out For Delivery","Delivered","Partial Delivered","Delivery Failed","Reschedule Required","Return To Sender","Rejected By Recipient","Cancelled"]},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."}}},"description":"Events. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"401":{"description":"Bad credentials"},"404":{"description":"No webhook-enabled provider matches this credential"},"422":{"description":"The document does not parse or exceeds the per-request event cap (500)"}}}},"/v1/ohp/capabilities":{"get":{"tags":["OHP"],"operationId":"ohpCapabilities","summary":"OHP discovery: version, conformance, profiles, chain ceiling","description":"OHP (Open Order Handoff Protocol, docs/standards/ohp.md) discovery. Public: the protocol-level answer needs no credential. Presenting an OHP token (Authorization: Bearer, or X-Resale-Token) additionally lists the caller's own capabilities — its live grants. A sender MUST read discovery before its first offer and MUST NOT use a feature the receiver did not declare.","responses":{"200":{"description":"The receiver's declaration","content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"Ohp version. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `0.3`.","examples":["0.3"]},"conformance":{"type":"string","description":"Conformance. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `L3`.","examples":["L3"]},"profiles":{"type":"array","items":{"type":"string","description":"Profiles. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Profiles. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`.","examples":[["parcel","task","moving","storage"]]},"acceptance":{"type":"string","description":"Acceptance. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `sync`.","examples":["sync"]},"push":{"type":"boolean","description":"Push. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"chain_ceiling":{"type":"integer","description":"Chain ceiling. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","examples":[3]},"operations":{"type":"array","items":{"type":"string","description":"Operations. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Operations. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"capabilities":{"type":"array","items":{"type":"object","description":"Capabilities. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Only with a valid token: the caller's live grants\n\n**Details:** Type `array`, items `object`."}}}}}}}}},"/v1/ohp/validate":{"post":{"tags":["OHP"],"operationId":"ohpValidate","summary":"Validate an OHP message against the protocol","description":"The OHP conformance validator. Public: a partner checks a message it produces before sending it. Pass ?operation=quote|handoff|cancel to check the body shape too. Always answers 200; the verdict is in the body.","parameters":[{"in":"query","name":"operation","required":false,"schema":{"type":"string","enum":["quote","handoff","cancel"],"description":"Allowed values: `quote` · `handoff` · `cancel`.\n\n**Details:** Optional · Type `string`."},"description":"Allowed values: `quote` · `handoff` · `cancel`.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The OHP envelope to check"}}}},"responses":{"200":{"description":"The verdict","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","description":"Valid. Identifier referencing the related record.\n\n**Details:** Type `boolean`."},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Path. Field in the JSON request body.\n\n**Details:** Type `string`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"description":"Errors. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"warnings":{"type":"array","items":{"type":"object","description":"Warnings. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Warnings. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}}}}},"/v1/ohp/quotes":{"post":{"tags":["OHP"],"operationId":"ohpQuote","summary":"Quote an OHP shipment","description":"What a described shipment would cost against the caller's capabilities. The body is an OHP envelope whose body.shipment follows the parcel profile; weights and dimensions must state their units (kg/lb, cm/in) — an unstated unit is refused, never assumed. Chain-extending: a chain in the envelope is checked. Failures use the OHP error shape {error: {code, message, retryable}}.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ohp_version","profile","body"],"properties":{"ohp_version":{"type":"string","description":"**Required.**\n\nOhp version. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `0.2`.","examples":["0.2"]},"profile":{"type":"string","description":"parcel (default), or task (0.2, spec 7.1): pickup + drop, with shipment.pickup required. 0.3: moving (spec 7.2: origin, destination, date, window, estimated_hours, items) or storage (spec 7.3: stay {from, to?}, items, optional pickup / return legs); both need service.capability_id naming a capability of that profile, and a profile that does not fit the capability is refused as unsupported_feature.\n\n**Details:** Type `string`.","examples":["parcel"]},"message_id":{"type":"string","description":"Message id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"chain":{"type":"object","properties":{"hops":{"type":"integer","description":"Hops. Field in the JSON request body.\n\n**Details:** Type `integer`."},"trail":{"type":"array","items":{"type":"string","description":"Trail. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Trail. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}},"description":"Chain. Field in the JSON request body.\n\n**Details:** Type `object`."},"body":{"type":"object","properties":{"shipment":{"type":"object","description":"Shipment. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"**Required.**\n\nBody. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"The quote","content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":["string","null"],"description":"Quote id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"capability_id":{"type":"string","description":"Capability id. Identifier referencing the related record.\n\n**Details:** Type `string`.\n\n**Example:** `grant:42`.","examples":["grant:42"]},"amount":{"type":"object","properties":{"value":{"type":"number","description":"Value. Field in the JSON request body.\n\n**Details:** Type `number`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."}},"description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"valid_until":{"type":["string","null"],"description":"Valid until. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"basis":{"type":["array","null"],"items":{"type":"object","description":"Basis. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Basis. Field in the JSON request body.\n\n**Details:** Type `array`, items `object` · Nullable."}}}}}},"401":{"description":"unauthorized — the OHP error shape"},"409":{"description":"chain_cycle or chain_too_deep; 0.3: no_capacity — a moving capability has no crew or vehicle for the date (not retryable)"},"422":{"description":"invalid_payload, with the validator's errors listed"}}}},"/v1/ohp/handoffs":{"post":{"tags":["OHP"],"operationId":"ohpHandoff","summary":"Offer an order across the network boundary","description":"Hand an order over for the receiver to deliver (docs/standards/ohp.md §5). The answer is status accepted (the order exists now), or — when the capability's acceptance is manual (L2, design D5) — status offered with a handoff_ref and expires_at: the offer waits for a person, and the sender polls the handoff until it reads accepted, rejected or expired. An offer past expires_at is expired, and the sender treats it as refused. Idempotency-Key is mandatory and strict: the same key with the same payload replays the current answer with replayed true; the same key with a different payload is refused as idempotency_conflict (422). A chain in the envelope is refused when it contains the receiver's own fingerprint (chain_cycle) or exceeds its ceiling (chain_too_deep), both 409. A customer id in the shipment is dropped: a handoff never creates a customer on either side. Profile task (spec 7.1): shipment.pickup is required and the receiver collects there before delivering; on parcel a present pickup block means the same, and the resulting order carries the pickup leg (need_pick_up) in the receiver's account. 0.3 profile moving: handoff_ref starts mvh_; the capability's acceptance decides (auto: accepted at once or refused as no_capacity; manual: offered). Profile storage: handoff_ref starts sth_ and the answer is always offered — a person accepts it and names the warehouse when the capability leaves it open; amount is the first billing period.","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","description":"Derived from the sender's own stable ids\n\n**Details:** Required · Type `string`."},"description":"Derived from the sender's own stable ids\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ohp_version","profile","body"],"properties":{"ohp_version":{"type":"string","description":"**Required.**\n\nOhp version. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `0.2`.","examples":["0.2"]},"profile":{"type":"string","description":"parcel (default), or task (0.2, spec 7.1): pickup + drop, with shipment.pickup required. 0.3: moving (spec 7.2: origin, destination, date, window, estimated_hours, items) or storage (spec 7.3: stay {from, to?}, items, optional pickup / return legs); both need service.capability_id naming a capability of that profile, and a profile that does not fit the capability is refused as unsupported_feature.\n\n**Details:** Type `string`.","examples":["parcel"]},"message_id":{"type":"string","description":"Message id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"chain":{"type":"object","properties":{"hops":{"type":"integer","description":"Hops. Field in the JSON request body.\n\n**Details:** Type `integer`."},"trail":{"type":"array","items":{"type":"string","description":"Trail. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Trail. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}},"description":"Chain. Field in the JSON request body.\n\n**Details:** Type `object`."},"body":{"type":"object","required":["shipment"],"properties":{"shipment":{"type":"object","description":"**Required.**\n\nThe parcel-profile shipment: sender_ref, dropoff {address, contact, window, instructions, access_code}, packages [{ref, weight {value, unit}, dimensions {l, w, h, unit}, identifiers}], service {capability_id}\n\n**Details:** Type `object`."}},"description":"**Required.**\n\nBody. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"Accepted (sync), or a replay of the first acceptance","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`.","examples":["accepted"]},"handoff_ref":{"type":"string","description":"Handoff ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"capability_id":{"type":"string","description":"Capability id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"amount":{"type":["object","null"],"properties":{"value":{"type":"number","description":"Value. Field in the JSON request body.\n\n**Details:** Type `number`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."}},"description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object` · Nullable."},"tracking_numbers":{"type":"array","items":{"type":"string","description":"Tracking numbers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Tracking numbers. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"replayed":{"type":"boolean","description":"Present only on an idempotent replay\n\n**Details:** Type `boolean`."}}}}}},"401":{"description":"unauthorized"},"409":{"description":"chain_cycle or chain_too_deep; 0.3: no_capacity — a moving capability has no crew or vehicle for the date (not retryable)"},"422":{"description":"invalid_payload or idempotency_conflict"}}}},"/v1/ohp/handoffs/{ref}":{"get":{"tags":["OHP"],"operationId":"ohpHandoffRead","summary":"Read one handoff's commercial state","description":"The handoff's state (accepted, cancelled, refused), price and tracking numbers. The OHP token reaches only its own handoffs.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"ref","required":true,"schema":{"type":"string","description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"The handoff","content":{"application/json":{"schema":{"type":"object","properties":{"handoff_ref":{"type":"string","description":"Handoff ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"capability_id":{"type":"string","description":"Capability id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"amount":{"type":["object","null"],"description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object` · Nullable."},"tracking_numbers":{"type":"array","items":{"type":"string","description":"Tracking numbers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Tracking numbers. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"created_at":{"type":["string","null"],"description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"cancelled_at":{"type":["string","null"],"description":"Cancelled at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}}}}}},"401":{"description":"unauthorized"},"404":{"description":"not_found"}}}},"/v1/ohp/handoffs/{ref}/timeline":{"get":{"tags":["OHP"],"operationId":"ohpHandoffTimeline","summary":"The handoff's OTEP timeline","description":"Status is OTEP (docs/standards/otep.md): the receiver exposes each handoff's journey as an OTEP timeline, never an internal code list. A handoff not yet scanned answers an empty timeline, not an error.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"ref","required":true,"schema":{"type":"string","description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"An OTEP timeline","content":{"application/json":{"schema":{"type":"object","properties":{"otep_version":{"type":"string","description":"Otep version. Field in the JSON request body.\n\n**Details:** Type `string`."},"profile":{"type":"string","description":"Profile. Field in the JSON request body.\n\n**Details:** Type `string`."},"subject":{"type":"object","description":"Subject. Field in the JSON request body.\n\n**Details:** Type `object`."},"events":{"type":"array","items":{"type":"object","description":"Events. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Events. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"401":{"description":"unauthorized"},"404":{"description":"not_found"}}}},"/v1/ohp/handoffs/{ref}/cancel":{"post":{"tags":["OHP"],"operationId":"ohpHandoffCancel","summary":"Request cancellation of a handoff","description":"The receiver answers cancelled, or refused with a reason; a refusal is a protocol answer (200), not a transport error. Cancelling something already cancelled is a truthful success (already_cancelled). Idempotent.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"ref","required":true,"schema":{"type":"string","description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`.\n\n**Example:** `customer_cancelled`.","examples":["customer_cancelled"]}}}}}},"responses":{"200":{"description":"cancelled, or refused with the reason","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`.\n\n**Example:** `cancelled`.","examples":["cancelled"]},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."}}}}}},"401":{"description":"unauthorized"},"404":{"description":"not_found"}}}},"/v1/ohp/handoffs/{ref}/amendments":{"post":{"tags":["OHP"],"operationId":"ohpAmendmentPropose","summary":"Propose an amendment to an accepted handoff","description":"A PROPOSAL, never an edit (design D11): body.changes carries any of dropoff, window, packages, instructions, plus an optional reason. 0.3: on a moving handoff the keys are date, window, estimated_hours, items, origin, destination; on a storage handoff stay, items, pickup, return — a stay.to on or before today ends the stay once accepted, and a started stay can only be ended this way (its cancel answers refused with reason started). Only an accepted handoff can be amended. At most one open proposal per handoff — a new proposal supersedes the open one. The receiver's answer arrives on the amendment's own read: accepted (with any price_delta, which becomes a settlement line), rejected, or still proposed.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"ref","required":true,"schema":{"type":"string","description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"Ohp version. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `0.2`.","examples":["0.2"]},"body":{"type":"object","properties":{"changes":{"type":"object","description":"Any of: dropoff (address / contact / access_code / instructions), window {from, to}, packages, instructions\n\n**Details:** Type `object`."},"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."}},"description":"Body. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"The proposal","content":{"application/json":{"schema":{"type":"object","properties":{"amendment_id":{"type":"integer","description":"Amendment id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`.\n\n**Example:** `proposed`.","examples":["proposed"]},"changes":{"type":"object","description":"Changes. Field in the JSON request body.\n\n**Details:** Type `object`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."}}}}}},"401":{"description":"unauthorized"},"404":{"description":"not_found"},"409":{"description":"conflict_state — the handoff is not accepted"},"422":{"description":"invalid_payload — no recognised change"}}}},"/v1/ohp/handoffs/{ref}/amendments/{id}":{"get":{"tags":["OHP"],"operationId":"ohpAmendmentRead","summary":"Read one amendment's state","description":"proposed, accepted (with any price_delta and the receiver's note), rejected, or superseded by a newer proposal.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"ref","required":true,"schema":{"type":"string","description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The amendment","content":{"application/json":{"schema":{"type":"object","properties":{"amendment_id":{"type":"integer","description":"Amendment id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"string","enum":["proposed","accepted","rejected","superseded"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `proposed` · `accepted` · `rejected` · `superseded`.\n\n**Details:** Type `string`."},"changes":{"type":"object","description":"Changes. Field in the JSON request body.\n\n**Details:** Type `object`."},"price_delta":{"type":["number","null"],"description":"Price delta. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"answer_note":{"type":["string","null"],"description":"Answer note. Free-text note.\n\n**Details:** Type `string` · Nullable."},"answered_at":{"type":["string","null"],"description":"Answered at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}}}}}},"401":{"description":"unauthorized"},"404":{"description":"not_found"}}}},"/v1/ohp/handoffs/{ref}/proofs":{"get":{"tags":["OHP"],"operationId":"ohpProofsList","summary":"The handoff's shared proofs of delivery","description":"Metadata plus short-lived signed URLs (design D14). Shared per GRANT and default OFF (owner decision Q4): a capability that never opted in answers 403, never an empty list — silence must not read as no proof was taken. A sender MUST NOT assume a proof exists.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"ref","required":true,"schema":{"type":"string","description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"The shared proofs","content":{"application/json":{"schema":{"type":"object","properties":{"proofs":{"type":"array","items":{"type":"object","properties":{"proof_id":{"type":"integer","description":"Proof id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"kind":{"type":"string","enum":["photo","signature"],"description":"Allowed values: `photo` · `signature`.\n\n**Details:** Type `string`."},"taken_at":{"type":["string","null"],"description":"Taken at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"otep_event_id":{"type":["string","null"],"description":"Otep event id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"url":{"type":"string","description":"A temporary signed URL; expires with url_expires_at\n\n**Details:** Type `string`."},"url_expires_at":{"type":"string","description":"Url expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."}}},"description":"Proofs. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"401":{"description":"unauthorized"},"403":{"description":"forbidden_capability — the grant did not opt into proof sharing"},"404":{"description":"not_found"}}}},"/v1/ohp/settlement-lines":{"get":{"tags":["OHP"],"operationId":"ohpSettlementLinesList","summary":"Settlement lines since a cursor","description":"The wire form of the receiver's corrections (design D13): price adjustments, cancellation fees and credits per handoff — and, 0.3, the price line of each moving / storage handoff (one per storage billing period, with period_start / period_end), pulled with the ANSWERING side's clock as the cursor — store as_of and send it back as since next time. Pull is the record; a line is never edited, a correction is a new line.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"since","required":false,"schema":{"type":"string","description":"The as_of the previous pull answered (inclusive)\n\n**Details:** Optional · Type `string`."},"description":"The as_of the previous pull answered (inclusive)\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","maximum":500,"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · max `500`."},"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · max `500`."}],"responses":{"200":{"description":"The lines and the next cursor","content":{"application/json":{"schema":{"type":"object","properties":{"settlement_lines":{"type":"array","items":{"type":"object","properties":{"line_id":{"type":"string","description":"Line id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"handoff_ref":{"type":"string","description":"Handoff ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"kind":{"type":"string","enum":["adjustment","cancellation_fee","credit","price"],"description":"Allowed values: `adjustment` · `cancellation_fee` · `credit` · `price`.\n\n**Details:** Type `string`."},"amount":{"type":"number","description":"Signed: positive = the sender owes more, negative = a credit\n\n**Details:** Type `number`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"created_at":{"type":["string","null"],"description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"period_start":{"type":"string","format":"date","description":"0.3, storage: first day of the billing period this line covers. Absent on other lines.\n\n**Details:** Type `string`, format `date`."},"period_end":{"type":"string","format":"date","description":"0.3, storage: last day of the billing period (inclusive). Absent on other lines.\n\n**Details:** Type `string`, format `date`."}}},"description":"Settlement lines. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"as_of":{"type":"string","description":"Send back as since on the next pull\n\n**Details:** Type `string`."}}}}}},"401":{"description":"unauthorized"}}}},"/v1/ohp/proof-files/{fileId}":{"get":{"tags":["OHP"],"operationId":"ohpProofFileFetch","summary":"Fetch one proof file by its signed URL","description":"The URL a proofs listing hands out, valid for its stated lifetime. The temporary signature is the whole authorisation — it was minted only for a token that passed the per-grant opt-in. An unsigned or expired request answers 403.","parameters":[{"in":"path","name":"fileId","required":true,"schema":{"type":"integer","description":"File id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"File id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The file","content":{"image/*":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"403":{"description":"Missing, invalid or expired signature"},"404":{"description":"not_found"}}}},"/v1/ohp/service-proof-files/{kind}/{fileId}":{"get":{"tags":["OHP"],"operationId":"ohpServiceProofFileFetch","summary":"Fetch one moving / storage proof photo by its signed URL","description":"0.3: the URL a proofs listing of a moving (mvh_) or storage (sth_) handoff hands out, valid for its stated lifetime. As for parcel proof files, the temporary signature is the whole authorisation. An unsigned or expired request answers 403.","parameters":[{"in":"path","name":"kind","required":true,"schema":{"type":"string","enum":["moving","storage"],"description":"Allowed values: `moving` · `storage`.\n\n**Details:** Required · Type `string`."},"description":"Allowed values: `moving` · `storage`.\n\n**Details:** Required · Type `string`."},{"in":"path","name":"fileId","required":true,"schema":{"type":"integer","description":"File id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"File id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The file","content":{"image/*":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"403":{"description":"Missing, invalid or expired signature"},"404":{"description":"not_found"}}}},"/v1/ohp/subscriptions":{"post":{"tags":["OHP"],"operationId":"ohpSubscriptionCreate","summary":"Subscribe an endpoint to OHP pushes (L3)","description":"Registers a public HTTPS endpoint for signed pushes of lifecycle changes, OTEP tracking events and new settlement lines (docs/standards/ohp.md §3.8). Before the subscription exists the receiver POSTs a subscription.verify push whose body.data.challenge the endpoint must echo back — an endpoint that cannot is refused. The secret (min 16 characters) signs every push (X-Ohp-Signature: v1= + hex HMAC-SHA256 of \"{timestamp}.{raw body}\"). message_id in every pushed envelope is stable across retries; dedupe on it. Pull stays the record — a missed push loses nothing. Subscribing the same URL again replaces the subscription and restarts its cursors at now.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","secret"],"properties":{"url":{"type":"string","description":"**Required.**\n\nUrl. Absolute or relative URL.\n\n**Details:** Type `string`.\n\n**Example:** `https://tms.example.com/hooks/ohp`.","examples":["https://tms.example.com/hooks/ohp"]},"secret":{"type":"string","description":"**Required.**\n\nSigns every push; at least 16 characters\n\n**Details:** Type `string`."},"events":{"type":"array","items":{"type":"string","enum":["handoff.accepted","handoff.rejected","handoff.expired","handoff.cancelled","amendment.accepted","amendment.rejected","handoff.tracking","settlement_line.created"],"description":"Allowed values: `handoff.accepted` · `handoff.rejected` · `handoff.expired` · `handoff.cancelled` · `amendment.accepted` · `amendment.rejected` · `handoff.tracking` · `settlement_line.created`.\n\n**Details:** Type `string`."},"description":"Omitted = all\n\n**Details:** Type `array`, items `string`."},"format":{"type":"string","enum":["native","ce_binary","ce_structured"],"description":"Allowed values: `native` · `ce_binary` · `ce_structured`.\n\n**Details:** Type `string`."},"signature":{"type":"string","enum":["native","standard_webhooks"],"description":"Allowed values: `native` · `standard_webhooks`.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"integer","description":"Subscription id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"url":{"type":"string","description":"Url. Absolute or relative URL.\n\n**Details:** Type `string`."},"events":{"type":["array","null"],"items":{"type":"string","description":"Events. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Events. Field in the JSON request body.\n\n**Details:** Type `array`, items `string` · Nullable."},"format":{"type":"string","description":"Format. Field in the JSON request body.\n\n**Details:** Type `string`."},"signature":{"type":"string","description":"Signature. Field in the JSON request body.\n\n**Details:** Type `string`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`.\n\n**Example:** `active`.","examples":["active"]}}}}}},"401":{"description":"unauthorized"},"422":{"description":"invalid_payload — unsafe URL, failed challenge, missing secret or unknown event"}}},"get":{"tags":["OHP"],"operationId":"ohpSubscriptionList","summary":"List the token's active push subscriptions","description":"The secret is never repeated.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"type":"object","properties":{"subscription_id":{"type":"integer","description":"Subscription id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"url":{"type":"string","description":"Url. Absolute or relative URL.\n\n**Details:** Type `string`."},"events":{"type":["array","null"],"items":{"type":"string","description":"Events. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Events. Field in the JSON request body.\n\n**Details:** Type `array`, items `string` · Nullable."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"last_delivered_at":{"type":["string","null"],"description":"Last delivered at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}}},"description":"Subscriptions. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"401":{"description":"unauthorized"}}}},"/v1/ohp/subscriptions/{id}":{"delete":{"tags":["OHP"],"operationId":"ohpSubscriptionRevoke","summary":"Revoke a push subscription","description":"Nothing is pushed to it again; the row stays for the audit.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}}}}},"401":{"description":"unauthorized"},"404":{"description":"not_found"}}}},"/v1/ohp/inbound-push/{providerId}":{"post":{"tags":["OHP"],"operationId":"ohpInboundPush","summary":"Receive an OHP push from a peer (sender side)","description":"Where THIS installation receives pushes for an OHP provider it subscribed at a peer. No auth middleware: the push signature (X-Ohp-Signature over \"{timestamp}.{raw body}\" with the provider's configured push secret) is the whole credential. Deliveries are deduplicated by the envelope's message_id; a duplicate is acknowledged and does nothing twice. A valid push only accelerates the next tracking pull — pull stays the record.","parameters":[{"in":"path","name":"providerId","required":true,"schema":{"type":"integer","description":"Provider id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Provider id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},{"in":"header","name":"X-Ohp-Timestamp","required":true,"schema":{"type":"string","description":"X ohp timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Required · Type `string`."},"description":"X ohp timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Ohp-Signature","required":true,"schema":{"type":"string","description":"v1= + hex HMAC-SHA256 of \"{timestamp}.{raw body}\" with the provider's push secret\n\n**Details:** Required · Type `string`."},"description":"v1= + hex HMAC-SHA256 of \"{timestamp}.{raw body}\" with the provider's push secret\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message_id"],"properties":{"ohp_version":{"type":"string","description":"Ohp version. Field in the JSON request body.\n\n**Details:** Type `string`."},"message_id":{"type":"string","description":"**Required.**\n\nMessage id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"body":{"type":"object","description":"Body. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"Acknowledged","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"duplicate":{"type":"boolean","description":"Present, true, when this message_id was already processed\n\n**Details:** Type `boolean`."}}}}}},"401":{"description":"No push secret configured, or the signature does not verify"},"422":{"description":"The push carries no message_id"}}}},"/v1/third-party-delivery/orders":{"get":{"tags":["ThirdPartyDelivery"],"summary":"List assigned third-party delivery orders","description":"Returns orders assigned to the authenticated third-party delivery provider. The provider can be a flagged customer or another Superroute client. Each order carries a `legs` array — the external orders booked for it: one whole-order booking (package_id null) for carriers that accept multi-piece shipments, one booking per package otherwise — and each package carries `package_id`, `third_party_order_number` and `outcome` (delivered / failed / returned / rejected / lost / cancelled, null while unresolved). All of these are additive; existing fields are unchanged.","operationId":"thirdPartyDeliveryOrders","security":[{"bearerAuth":[]}],"parameters":[{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","description":"Items per page, maximum 100\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `50`.","examples":[50]},"description":"Items per page, maximum 100\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `50`."}],"responses":{"200":{"description":"Assigned orders"},"401":{"description":"Unauthorized"}}}},"/v1/third-party-delivery/orders/{assignmentNo}":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Get one assigned third-party delivery order","description":"Returns one assignment for the authenticated provider and marks it as pulled. The payload carries the same additive `legs` array and per-package `outcome` as the list endpoint.","operationId":"thirdPartyDeliveryOrder","security":[{"bearerAuth":[]}],"parameters":[{"name":"assignmentNo","in":"path","required":true,"schema":{"type":"string","description":"Assignment number\n\n**Details:** Required · Type `string`.\n\n**Example:** `TPD20260501120000ABC123`.","examples":["TPD20260501120000ABC123"]},"description":"Assignment number\n\n**Details:** Required · Type `string`.\n\n**Example:** `TPD20260501120000ABC123`."}],"responses":{"200":{"description":"Assigned order"},"404":{"description":"Assignment not found"}}}},"/v1/third-party-delivery/orders/{assignmentNo}/accept":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Accept a third-party delivery assignment","description":"Marks an assignment as accepted by the authenticated provider.","operationId":"thirdPartyDeliveryAcceptOrder","security":[{"bearerAuth":[]}],"parameters":[{"name":"assignmentNo","in":"path","required":true,"schema":{"type":"string","description":"Assignment number\n\n**Details:** Required · Type `string`.\n\n**Example:** `TPD20260501120000ABC123`.","examples":["TPD20260501120000ABC123"]},"description":"Assignment number\n\n**Details:** Required · Type `string`.\n\n**Example:** `TPD20260501120000ABC123`."}],"responses":{"200":{"description":"Assignment accepted"},"404":{"description":"Assignment not found"}}}},"/v1/third-party-delivery/orders/{assignmentNo}/reject":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Reject a third-party delivery assignment","description":"Rejects an assignment. Superroute will attempt the next matching provider; if none remain, the order falls back to self-delivery. Passing leg_no or external_order_number rejects only that booking of a split push; the remaining bookings keep running and an alert is raised for the refused package.","operationId":"thirdPartyDeliveryRejectOrder","security":[{"bearerAuth":[]}],"parameters":[{"name":"assignmentNo","in":"path","required":true,"schema":{"type":"string","description":"Assignment number\n\n**Details:** Required · Type `string`.\n\n**Example:** `TPD20260501120000ABC123`.","examples":["TPD20260501120000ABC123"]},"description":"Assignment number\n\n**Details:** Required · Type `string`.\n\n**Example:** `TPD20260501120000ABC123`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason_code":{"type":"string","description":"Reason code. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `OUT_OF_AREA`.","examples":["OUT_OF_AREA"]},"reason_text":{"type":"string","description":"Free-text failure or exception reason from the external system.\n\n**Details:** Type `string`.\n\n**Example:** `Address is outside delivery coverage`.","examples":["Address is outside delivery coverage"]},"leg_no":{"type":"integer","description":"Optional. Reject only this booking of a split push (see the legs array on GET /orders). Omit to reject the whole assignment, which is the previous behaviour.\n\n**Details:** Type `integer`.\n\n**Example:** `2`.","examples":[2]},"external_order_number":{"type":"string","description":"Optional. Same as leg_no, identifying the booking by the carrier order number.\n\n**Details:** Type `string`.\n\n**Example:** `CARRIER-557`.","examples":["CARRIER-557"]}}}}}},"responses":{"200":{"description":"Assignment rejected"},"404":{"description":"Assignment not found"}}}},"/v1/third-party-delivery/updates":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Submit a third-party delivery status update","description":"Submits an action_code or external_event_code. Superroute creates the matching order status, tracking event, and operation event. The assignment is located by the (identifier, identifier_type) pair. external_event_code is resolved through the provider's configured event mappings first, then falls back to the adapter's built-in mapping (for example Instadispatch `SHIPMENT_DELIVERED` -> `delivered`). A package reference (package_id / package_number / tracking_number / third_party_package_number, or the `packages` array) scopes the update to those parcels; without one the update applies to the whole order exactly as before. When only some parcels of an order are delivered the order moves to Partial Delivered (23) instead of Successful (8).","operationId":"thirdPartyDeliverySubmitUpdate","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"string","description":"**Required.**\n\nValue used to locate the assignment. Interpreted according to identifier_type.\n\n**Details:** Type `string`.\n\n**Example:** `INS-TRK-9988`.","examples":["INS-TRK-9988"]},"identifier_type":{"type":"string","description":"What identifier holds. Defaults to third_party_tracking_number. external_order_number matches the carrier booking number; when the order was split (one booking per package), it also tells Superroute which package the update is about.\n\nHow to interpret `identifier` when locating a third-party assignment / order. Default: `third_party_tracking_number`.\n\nEnum values (from deployed code):\n- `assignment_no` — Third-party assignment number\n- `order_id` — Superroute order id\n- `external_order_id` — Merchant / external order id on the Superroute order\n- `tracking_number` — Superroute tracking number\n- `third_party_tracking_number` — Carrier / partner tracking number (default)\n- `external_tracking_number` — Legacy alias for third-party tracking number\n\n**Details:** Type `string` · Default: `third_party_tracking_number`.","enum":["assignment_no","order_id","external_order_id","tracking_number","third_party_tracking_number","external_tracking_number","external_order_number"],"default":"third_party_tracking_number","x-enumDescriptions":["Third-party assignment number","Superroute order id","Merchant / external order id on the Superroute order","Superroute tracking number","Carrier / partner tracking number (default)","Legacy alias for third-party tracking number",""],"examples":["third_party_tracking_number"]},"action_code":{"type":"string","description":"Superroute third-party delivery action code. Use partial_delivered together with `packages` when only some parcels of a shipment arrived; carriers that track per parcel should instead send `delivered` with a package reference.\n\nSuperroute third-party delivery action code. Maps to order status + tracking event via `ThirdPartyDeliveryActionMap`.\n\nEnum values (from deployed code):\n- `received` — Received\n- `a_scan` — A Scan\n- `facility_received` — Facility Received\n- `arrived_at_facility` — Arrived At Facility\n- `package_outbound` — Package Outbound\n- `loaded` — Loaded\n- `in_transit` — In Transit\n- `on_hold` — On Hold\n- `collection_on_hold` — Collection On Hold\n- `customs_clearance` — Customs Clearance\n- `out_for_delivery` — Out For Delivery\n- `delivered` — Delivered\n- `partial_delivered` — Partial Delivered\n- `delivery_failed` — Delivery Failed\n- `reschedule_required` — Reschedule Required\n- `return_to_sender` — Return To Sender\n- `rejected_by_recipient` — Rejected By Recipient\n- `cancelled` — Cancelled\n\n**Details:** Type `string`.","enum":["received","a_scan","facility_received","arrived_at_facility","package_outbound","loaded","in_transit","on_hold","collection_on_hold","customs_clearance","out_for_delivery","delivered","partial_delivered","delivery_failed","reschedule_required","return_to_sender","rejected_by_recipient","cancelled"],"x-enumDescriptions":["Received","A Scan","Facility Received","Arrived At Facility","Package Outbound","Loaded","In Transit","On Hold","Collection On Hold","Customs Clearance","Out For Delivery","Delivered","Partial Delivered","Delivery Failed","Reschedule Required","Return To Sender","Rejected By Recipient","Cancelled"],"examples":["delivered"]},"package_id":{"type":"integer","description":"Optional. Apply this update to a single package of the order. Omit for an order-level update (previous behaviour).\n\n**Details:** Type `integer`.\n\n**Example:** `4451`.","examples":[4451]},"package_number":{"type":"string","description":"Optional. Same as package_id, matched on the package number.\n\n**Details:** Type `string`.\n\n**Example:** `PKG-2`.","examples":["PKG-2"]},"tracking_number":{"type":"string","description":"Optional. Same as package_id, matched on the package's Superroute tracking number.\n\n**Details:** Type `string`.\n\n**Example:** `TRK-1002`.","examples":["TRK-1002"]},"third_party_package_number":{"type":"string","description":"Optional. Same as package_id, matched on the carrier's own package number.\n\n**Details:** Type `string`.\n\n**Example:** `CARRIER-557`.","examples":["CARRIER-557"]},"packages":{"type":"array","description":"Optional. Report several parcels in one call. Each item identifies a package the same way as the scalar fields above and may carry its own action_code; without one it inherits the top-level action_code (a partial_delivered top level means the listed parcels were delivered).\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"package_id":{"type":"integer","description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `4451`.","examples":[4451]},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`.\n\n**Example:** `TRK-1001`.","examples":["TRK-1001"]},"third_party_package_number":{"type":"string","description":"Third party package number. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `CARRIER-556`.","examples":["CARRIER-556"]},"action_code":{"type":"string","description":"Superroute third-party delivery action code. Maps to order status + tracking event via `ThirdPartyDeliveryActionMap`.\n\nEnum values (from deployed code):\n- `booking_confirmed` — Booking Confirmed\n- `awaiting_pickup` — Awaiting Pickup\n- `received` — Received\n- `a_scan` — A Scan\n- `package_outbound` — Package Outbound\n- `in_transit` — In Transit\n- `loaded` — Loaded\n- `facility_received` — Facility Received\n- `arrived_at_facility` — Arrived At Facility\n- `on_hold` — On Hold\n- `collection_on_hold` — Collection On Hold\n- `customs_clearance` — Customs Clearance\n- `out_for_delivery` — Out For Delivery\n- `delivered` — Delivered\n- `partial_delivered` — Partial Delivered\n- `delivery_failed` — Delivery Failed\n- `reschedule_required` — Reschedule Required\n- `return_to_sender` — Return To Sender\n- `rejected_by_recipient` — Rejected By Recipient\n- `cancelled` — Cancelled\n\n**Details:** Type `string`.","enum":["booking_confirmed","awaiting_pickup","received","a_scan","package_outbound","in_transit","loaded","facility_received","arrived_at_facility","on_hold","collection_on_hold","customs_clearance","out_for_delivery","delivered","partial_delivered","delivery_failed","reschedule_required","return_to_sender","rejected_by_recipient","cancelled"],"x-enumDescriptions":["Booking Confirmed","Awaiting Pickup","Received","A Scan","Package Outbound","In Transit","Loaded","Facility Received","Arrived At Facility","On Hold","Collection On Hold","Customs Clearance","Out For Delivery","Delivered","Partial Delivered","Delivery Failed","Reschedule Required","Return To Sender","Rejected By Recipient","Cancelled"],"examples":["delivered"]}}}},"external_event_code":{"type":"string","description":"Provider-native event code (e.g. Instadispatch SHIPMENT_DELIVERED). Resolved via DB mapping, then adapter mapping.\n\n**Details:** Type `string`.","examples":["SHIPMENT_DELIVERED"]},"occurred_at":{"type":"string","description":"When the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string`.\n\n**Example:** `2026-05-01 10:30:00`.","examples":["2026-05-01 10:30:00"]},"warehouse_name":{"type":"string","description":"Human-readable warehouse / hub name reported by the external system.\n\n**Details:** Type `string`.\n\n**Example:** `Toronto Hub`.","examples":["Toronto Hub"]},"driver_name":{"type":"string","description":"Human-readable driver / courier name reported by the external system.\n\n**Details:** Type `string`.\n\n**Example:** `External Driver`.","examples":["External Driver"]},"reason_text":{"type":"string","description":"Free-text failure or exception reason from the external system.\n\n**Details:** Type `string`.\n\n**Example:** `Recipient unavailable`.","examples":["Recipient unavailable"]},"pod":{"type":"object","description":"Proof-of-delivery payload (photos, signature, metadata).\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"Update accepted"},"422":{"description":"Invalid action or mapping"}}}},"/v1/third-party-delivery/pod":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Submit third-party delivery POD","description":"Uploads POD photos/signature for an assigned order. Supports JSON base64 payloads and multipart files. The assignment is located by (identifier, identifier_type). The target operation event is optionally located by (event_reference, event_reference_type) — external_event_code is resolved through the provider's configured event mappings first, then falls back to the adapter's built-in mapping.","operationId":"thirdPartyDeliverySubmitPod","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["identifier","pod"],"properties":{"identifier":{"type":"string","description":"**Required.**\n\nValue used to locate the assignment. Interpreted according to identifier_type.\n\n**Details:** Type `string`.\n\n**Example:** `INS-TRK-9988`.","examples":["INS-TRK-9988"]},"identifier_type":{"type":"string","description":"What identifier holds. Defaults to third_party_tracking_number.\n\nHow to interpret `identifier` when locating a third-party assignment / order. Default: `third_party_tracking_number`.\n\nEnum values (from deployed code):\n- `assignment_no` — Third-party assignment number\n- `order_id` — Superroute order id\n- `external_order_id` — Merchant / external order id on the Superroute order\n- `tracking_number` — Superroute tracking number\n- `third_party_tracking_number` — Carrier / partner tracking number (default)\n- `external_tracking_number` — Legacy alias for third-party tracking number\n\n**Details:** Type `string` · Default: `third_party_tracking_number`.","enum":["assignment_no","order_id","external_order_id","tracking_number","third_party_tracking_number","external_tracking_number"],"default":"third_party_tracking_number","x-enumDescriptions":["Third-party assignment number","Superroute order id","Merchant / external order id on the Superroute order","Superroute tracking number","Carrier / partner tracking number (default)","Legacy alias for third-party tracking number"],"examples":["third_party_tracking_number"]},"event_reference":{"type":"string","description":"Optional value used to locate the operation event the POD should attach to. Interpreted according to event_reference_type.\n\n**Details:** Type `string`.\n\n**Example:** `100`.","examples":[100]},"event_reference_type":{"type":"string","description":"What event_reference holds. Defaults to operation_event_id.\n\nHow to interpret `event_reference` when attaching POD or updates to an operation event.\n\nEnum values (from deployed code):\n- `operation_event_id` — Superroute operation event id (default)\n- `external_event_code` — Provider-native event code\n- `action_code` — Superroute third-party action code\n\n**Details:** Type `string` · Default: `operation_event_id`.","enum":["operation_event_id","external_event_id","external_event_code","action_code"],"default":"operation_event_id","x-enumDescriptions":["Superroute operation event id (default)","","Provider-native event code","Superroute third-party action code"],"examples":["operation_event_id"]},"pod":{"type":"object","description":"**Required.**\n\nProof-of-delivery payload (photos, signature, metadata).\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"POD accepted"},"404":{"description":"Assignment not found"}}}},"/third-party-delivery/webhook/{providerId}":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Inbound third-party delivery webhook receiver (provider in URL)","description":"Preferred inbound endpoint for a third-party delivery provider. The provider ID is in the URL so carriers that cannot send custom headers still identify which provider the event belongs to. The adapter (Instadispatch, Intelcom, partner Superroute client, customer-as-carrier, etc.) is resolved from that provider's settings.\n\n**Authentication**: send `Authorization: Bearer <token>`. A dedicated webhook token is also accepted as the bare header value (`Authorization: <token>`), for carrier consoles that offer one free-text header field and no place for a scheme. The token may be the Superroute API token of the customer or client that owns the provider, or a dedicated webhook token generated on that provider. Dedicated webhook tokens can call only this webhook (and the shared legacy URL for the same provider) and cannot call any other Superroute API. Custom headers such as `X-Provider-Id` are not required.\n\n**Provider resolution**: Superroute looks up the provider id from the path among webhook-enabled providers where `target_business_id` matches the authenticated user (client-type providers) or `customer_id` matches a Customers row whose `users_info_id` is the authenticated user (customer-type providers).\n\n**Auto-handover**: If the inbound event arrives while the assignment is still in `assigned/pulled/accepted` state, Superroute automatically marks the order as `HANDED_OVER_TO_THE_THIRD_PARTY_CARRIER` before applying the event's action code. Both transitions are recorded in the lifecycle timeline.","operationId":"thirdPartyDeliveryWebhookByProvider","security":[{"bearerAuth":[]}],"parameters":[{"name":"providerId","in":"path","required":true,"schema":{"type":"integer","description":"Third-party delivery provider ID. Shown on the provider's Webhook Registration URL.\n\n**Details:** Required · Type `integer`."},"description":"Third-party delivery provider ID. Shown on the provider's Webhook Registration URL.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_code":{"type":"string","description":"Event code. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `SHIPMENT_DELIVERED`.","examples":["SHIPMENT_DELIVERED"]},"load_identity":{"type":"string","description":"Load identity. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `INST-2026-12345`.","examples":["INST-2026-12345"]},"occurred_at":{"type":"string","format":"date-time","description":"When the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string`, format `date-time`."}}}}}},"responses":{"200":{"description":"Event accepted (or harmlessly ignored if assignment not found)"},"401":{"description":"Unauthorized: missing or invalid API token"},"404":{"description":"No webhook-enabled provider matches the authenticated credential and path provider id"},"422":{"description":"Bad or unrecognized payload"},"500":{"description":"Internal error processing the event"}}}},"/third-party-delivery/webhook":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Inbound third-party delivery webhook receiver (legacy shared URL)","description":"Legacy shared inbound endpoint kept for existing registrations. Prefer `POST /third-party-delivery/webhook/{providerId}`, which puts the provider ID in the URL so carriers that cannot send custom headers still identify the provider. The adapter (Instadispatch, Intelcom, partner Superroute client, customer-as-carrier, etc.) is resolved from the provider settings on the Superroute side.\n\n**Authentication**: send `Authorization: Bearer <token>`. A dedicated webhook token is also accepted as the bare header value (`Authorization: <token>`), for carrier consoles that offer one free-text header field and no place for a scheme. The token may be the Superroute API token of the customer or client that owns the provider, or a dedicated webhook token generated on that provider. Dedicated webhook tokens can call only the TPD webhook endpoints and cannot call any other Superroute API. When using a dedicated token the provider is taken from the token, so `X-Provider-Id` is not required.\n\n**Provider resolution**: Superroute looks up providers where `target_business_id` matches the authenticated user (client-type providers) or `customer_id` matches a Customers row whose `users_info_id` is the authenticated user (customer-type providers). If exactly one webhook-enabled provider matches, it is selected automatically. If multiple match, the request MUST also pass `provider_id` (in the JSON body, in `?provider_id=`, or as the `X-Provider-Id` header) to disambiguate.\n\n**Auto-handover**: If the inbound event arrives while the assignment is still in `assigned/pulled/accepted` state, Superroute automatically marks the order as `HANDED_OVER_TO_THE_THIRD_PARTY_CARRIER` before applying the event's action code. Both transitions are recorded in the lifecycle timeline.","operationId":"thirdPartyDeliveryWebhook","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Provider-Id","in":"header","required":false,"schema":{"type":"integer","description":"Optional provider ID. Required on this shared URL only when the authenticated account owns more than one webhook-enabled provider. Prefer putting the id in the path instead.\n\n**Details:** Optional · Type `integer`."},"description":"Optional provider ID. Required on this shared URL only when the authenticated account owns more than one webhook-enabled provider. Prefer putting the id in the path instead.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider_id":{"type":"integer","description":"Optional fallback provider identifier; same purpose as the X-Provider-Id header.\n\n**Details:** Type `integer`."},"event_code":{"type":"string","description":"Event code. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `SHIPMENT_DELIVERED`.","examples":["SHIPMENT_DELIVERED"]},"load_identity":{"type":"string","description":"Load identity. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `INST-2026-12345`.","examples":["INST-2026-12345"]},"occurred_at":{"type":"string","format":"date-time","description":"When the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string`, format `date-time`."}}}}}},"responses":{"200":{"description":"Event accepted (or harmlessly ignored if assignment not found)"},"401":{"description":"Unauthorized: missing or invalid API token"},"404":{"description":"No webhook-enabled provider matches the authenticated credential; pass X-Provider-Id when multiple providers exist"},"422":{"description":"Bad or unrecognized payload"},"500":{"description":"Internal error processing the event"}}}},"/smart-locker/{provider}/webhook":{"post":{"tags":["SmartLocker"],"summary":"Inbound smart locker provider webhook receiver","description":"Receives provider-specific smart locker webhooks and routes them through the shared SmartLocker provider layer. For Mibox, Superroute verifies `X-MiBox-Timestamp` and `X-MiBox-Signature` with the Webhook Secret configured on the Mibox smart locker account, normalizes `grids.changed` events, updates local door status, and records close events.","operationId":"smartLockerProviderWebhook","parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","description":"Smart locker provider key configured in Superroute.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Smart locker provider key configured in Superroute.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"X-MiBox-Event","in":"header","required":false,"schema":{"type":"string","description":"Mibox event name. The payload event field is also accepted.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `grids.changed`.","examples":["grids.changed"]},"description":"Mibox event name. The payload event field is also accepted.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `grids.changed`."},{"name":"X-MiBox-Timestamp","in":"header","required":true,"schema":{"type":"string","description":"Mibox webhook timestamp in milliseconds or seconds.\n\n**Details:** Required · Type `string`.\n\n**Example:** `1779907200000`.","examples":[1779907200000]},"description":"Mibox webhook timestamp in milliseconds or seconds.\n\n**Details:** Required · Type `string`.\n\n**Example:** `1779907200000`."},{"name":"X-MiBox-Signature","in":"header","required":true,"schema":{"type":"string","description":"HMAC SHA-256 signature over `{timestamp}.{rawBody}`.\n\n**Details:** Required · Type `string`."},"description":"HMAC SHA-256 signature over `{timestamp}.{rawBody}`.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","smart_locker_id","changes"],"properties":{"event":{"type":"string","description":"**Required.**\n\nEvent. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `grids.changed`.","examples":["grids.changed"]},"request_id":{"type":"string","description":"Request id. Identifier referencing the related record.\n\n**Details:** Type `string`.\n\n**Example:** `7d5414d9-8b94-4a61-a51e-a02c3ebfe102`.","examples":["7d5414d9-8b94-4a61-a51e-a02c3ebfe102"]},"smart_locker_id":{"type":"string","description":"**Required.**\n\nSmart locker id. Identifier referencing the related record.\n\n**Details:** Type `string`.\n\n**Example:** `MLK-CPU-0001`.","examples":["MLK-CPU-0001"]},"snapshot_at":{"type":"string","format":"date-time","description":"Snapshot at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"changes":{"type":"array","items":{"type":"object","properties":{"grid_id":{"type":"string","description":"Grid id. Identifier referencing the related record.\n\n**Details:** Type `string`.\n\n**Example:** `1`.","examples":[1]},"before":{"type":"object","properties":{"grid_status":{"type":"string","description":"Grid status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`.\n\n**Example:** `open`.","examples":["open"]},"fault_code":{"type":["string","null"],"description":"Fault code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."}},"description":"Before. Field in the JSON request body.\n\n**Details:** Type `object`."},"after":{"type":"object","properties":{"grid_status":{"type":"string","description":"Grid status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`.\n\n**Example:** `closed`.","examples":["closed"]},"fault_code":{"type":["string","null"],"description":"Fault code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."}},"description":"After. Field in the JSON request body.\n\n**Details:** Type `object`."},"changed_at":{"type":"string","format":"date-time","description":"Changed at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}}},"description":"**Required.**\n\nChanges. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"event":"grids.changed","request_id":"7d5414d9-8b94-4a61-a51e-a02c3ebfe102","smart_locker_id":"MLK-CPU-0001","snapshot_at":"2026-05-27T16:00:00Z","changes":[{"grid_id":1,"before":{"grid_status":"open","fault_code":null},"after":{"grid_status":"closed","fault_code":null},"changed_at":"2026-05-27T16:00:02Z"}]}}}},"responses":{"200":{"description":"Webhook accepted and processed"},"400":{"description":"Unsupported provider event or invalid payload"},"401":{"description":"Missing or invalid provider webhook signature"},"404":{"description":"No active smart locker account matches the webhook locker ID"}}}},"/v1/consolidation/inbound-tracking/webhook":{"post":{"tags":["Consolidation"],"summary":"Inbound tracking webhook for consolidation parcels","description":"A tracking provider pushes scan events for parcels a consolidation warehouse is expecting (declared with an inbound tracking number). No user authentication: the push is verified with `X-Consolidation-Signature`, the hex HMAC-SHA256 of the raw request body under the provider's shared secret configured on the platform. The provider is named by `X-Consolidation-Provider`, or by the body field `provider` for senders that cannot set headers; with neither, `seventeen_track` is assumed. Unknown providers are refused, a provider without a webhook (`manual`) is refused, and an unconfigured secret refuses every push without writing anything. Events are applied to every open tracker under that provider with that tracking number (numbers are released on stock-out, so closed trackers never match). Application is idempotent: each event is keyed by a checksum of its content, so a retried push records nothing twice and the response reports the duplicates. Accepted bodies: the normalized envelope shown here, or 17TRACK's native push (`{\"event\": \"TRACKING_UPDATED\", \"data\": {\"number\": ..., \"track_info\": ...}}`). Event statuses are normalized to: pending, in_transit, out_for_delivery, exception, carrier_delivered, stopped.","operationId":"consolidationInboundTrackingWebhook","parameters":[{"name":"X-Consolidation-Provider","in":"header","required":false,"schema":{"type":"string","enum":["seventeen_track"],"description":"Provider key. Aliases `17track` and `17-track` are accepted. Defaults to `seventeen_track`.\n\nAllowed values: `seventeen_track`.\n\n**Details:** Optional · Type `string`.","examples":["seventeen_track"]},"description":"Provider key. Aliases `17track` and `17-track` are accepted. Defaults to `seventeen_track`.\n\nAllowed values: `seventeen_track`.\n\n**Details:** Optional · Type `string`."},{"name":"X-Consolidation-Signature","in":"header","required":true,"schema":{"type":"string","description":"Lower-case hex HMAC-SHA256 of the raw request body, keyed with the provider's shared secret.\n\n**Details:** Required · Type `string`.\n\n**Example:** `3f8a2c1e0b7d4e9a6c5b1f2d8e7a9c0b4d6e1f3a5c7b9d2e4f6a8c0b1d3e5f7a`.","examples":["3f8a2c1e0b7d4e9a6c5b1f2d8e7a9c0b4d6e1f3a5c7b9d2e4f6a8c0b1d3e5f7a"]},"description":"Lower-case hex HMAC-SHA256 of the raw request body, keyed with the provider's shared secret.\n\n**Details:** Required · Type `string`.\n\n**Example:** `3f8a2c1e0b7d4e9a6c5b1f2d8e7a9c0b4d6e1f3a5c7b9d2e4f6a8c0b1d3e5f7a`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"provider":{"type":"string","description":"Provider key when the header cannot be set.\n\n**Details:** Type `string`.\n\n**Example:** `seventeen_track`.","examples":["seventeen_track"]},"tracking_number":{"type":"string","description":"**Required.**\n\nCarrier tracking number as declared by the member. Compared case-insensitively.\n\n**Details:** Type `string`.\n\n**Example:** `1Z999AA10123456784`.","examples":["1Z999AA10123456784"]},"carrier":{"type":["string","null"],"description":"Carrier. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `ups`.","examples":["ups"]},"provider_ref":{"type":["string","null"],"description":"Provider-side identifier for the subscription, if any.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `1Z999AA10123456784`.","examples":["1Z999AA10123456784"]},"status":{"type":["string","null"],"description":"Provider-level latest status. Applied to the tracker (never over a warehouse receipt).\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `in_transit`.","examples":["in_transit"]},"events":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`.\n\n**Example:** `in_transit`.","examples":["in_transit"]},"occurred_at":{"type":"string","format":"date-time","description":"When the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string`, format `date-time`.\n\n**Example:** `2026-09-01T10:15:00Z`.","examples":["2026-09-01T10:15:00Z"]},"location":{"type":["string","null"],"description":"Location. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Toronto, ON`.","examples":["Toronto, ON"]},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Departed from facility`.","examples":["Departed from facility"]}}},"description":"Events. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"tracking_number":"1Z999AA10123456784","carrier":"ups","status":"in_transit","events":[{"status":"in_transit","occurred_at":"2026-09-01T10:15:00Z","location":"Toronto, ON","description":"Departed from facility"}]}}}},"responses":{"200":{"description":"Push verified and applied. `trackers_matched` is 0 when no open tracker expects the number; the push is still acknowledged so the provider does not retry.","content":{"application/json":{"example":{"result":true,"message":"ok","data":{"provider":"seventeen_track","tracking_number":"1Z999AA10123456784","trackers_matched":1,"events_recorded":1,"events_duplicate":0}}}}},"400":{"description":"Unknown provider (`PROVIDER_UNKNOWN`), provider does not push (`PROVIDER_NOT_WEBHOOK_CAPABLE`), or body is not a JSON object with a tracking number (`PAYLOAD_INVALID`).","content":{"application/json":{"example":{"result":false,"error_code":"PROVIDER_UNKNOWN","message":"Unknown inbound tracking provider."}}}},"401":{"description":"Secret not configured (`WEBHOOK_SECRET_MISSING`), signature header absent (`WEBHOOK_SIGNATURE_MISSING`), or signature does not match (`WEBHOOK_SIGNATURE_INVALID`). Nothing is written.","content":{"application/json":{"example":{"result":false,"error_code":"WEBHOOK_SIGNATURE_INVALID","message":"Invalid webhook signature."}}}},"503":{"description":"Inbound tracking tables are not deployed yet (`TRACKING_UNAVAILABLE`); retry later."}}}},"/v1/driver/routes":{"get":{"tags":["Driver"],"parameters":[{"in":"query","name":"isProcessing","schema":{"type":"integer","enum":[0,1],"description":"Filter flag. `1` = only in-progress items; `0` = exclude or ignore that filter (endpoint-specific).\n\nFilter flag. `1` = only in-progress items; `0` = exclude or ignore that filter (endpoint-specific).\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"Filter flag. `1` = only in-progress items; `0` = exclude or ignore that filter (endpoint-specific).\n\nFilter flag. `1` = only in-progress items; `0` = exclude or ignore that filter (endpoint-specific).\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"isHistory","schema":{"type":"integer","enum":[0,1],"description":"Filter flag. `1` = historical / completed items; `0` = current items.\n\nFilter flag. `1` = historical / completed items; `0` = current items.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"Filter flag. `1` = historical / completed items; `0` = current items.\n\nFilter flag. `1` = historical / completed items; `0` = current items.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"isHistory","schema":{"type":"integer","enum":[0,1],"description":"Filter flag. `1` = historical / completed items; `0` = current items.\n\nFilter flag. `1` = historical / completed items; `0` = current items.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"Filter flag. `1` = historical / completed items; `0` = current items.\n\nFilter flag. `1` = historical / completed items; `0` = current items.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"page","schema":{"type":"integer","description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"per_page","schema":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"sort","schema":{"type":"string","description":"Sort field or sort expression for the listing.\n\n**Details:** Optional · Type `string`."},"required":false,"description":"Sort field or sort expression for the listing.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"id","schema":{"type":"integer","description":"Filter by route ID.\n\nResource identifier.\n\n**Details:** Optional · Type `integer`."},"description":"Filter by route ID.\n\nResource identifier.\n\n**Details:** Optional · Type `integer`.","required":false}],"summary":"Get routes for one driver","description":"Each route's total and per-status count are this driver's orders on that route, not every order on the route. Recurring pickups (additive, after every existing key): recurring_pickup_route tells a route generated from a recurring pickup template; allow_adhoc_pickups and allow_deliveries are its two switches (true for every other route, and before the recurring pickup migrations).","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"route_type":{"type":"integer","description":"Route type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"date":{"type":"string","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`."},"operation_mode":{"type":"integer","description":"Operation mode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"allow_rescheduled_by_same_driver":{"type":"integer","description":"Allow rescheduled by same driver. Field in the JSON request body.\n\n**Details:** Type `integer`."},"allow_hands_off_order_by_driver":{"type":"integer","description":"Allow hands off order by driver. Field in the JSON request body.\n\n**Details:** Type `integer`."},"allow_reset_order_status_by_driver":{"type":"integer","description":"Allow reset order status by driver. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `integer`."},"allow_add_order_by_driver":{"type":"integer","description":"Allow add order by driver. Field in the JSON request body.\n\n**Details:** Type `integer`."},"allow_add_manual_order_by_driver":{"type":"integer","description":"Allow add manual order by driver. Field in the JSON request body.\n\n**Details:** Type `integer`."},"driver_alias":{"type":"string","description":"Driver alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"vehicle_type":{"type":"string","description":"Vehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"]},"distance":{"type":"integer","description":"Distance. Field in the JSON request body.\n\n**Details:** Type `integer`."},"geometry":{"type":["string","null"],"description":"Encoded route geometry; null if the route has no stored geometry.\n\n**Details:** Type `string` · Nullable."},"total":{"type":"integer","description":"Number of orders assigned to this driver on the route, not every order on the route.\n\n**Details:** Type `integer`."},"count":{"type":"object","description":"Per-status counts of this driver's orders on the route.\n\n**Details:** Type `object`.","properties":{"already_planned":{"type":"integer","description":"Already planned. Field in the JSON request body.\n\n**Details:** Type `integer`."}}},"recurring_pickup_route":{"type":"boolean","description":"Generated from a recurring pickup template\n\n**Details:** Type `boolean`."},"allow_adhoc_pickups":{"type":"boolean","description":"Non-recurring pickup orders may join the route (true for every non-recurring route)\n\n**Details:** Type `boolean`."},"allow_deliveries":{"type":"boolean","description":"Delivery orders may join the route (true for every non-recurring route)\n\n**Details:** Type `boolean`."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"data":[{"id":323,"route_type":2,"name":20210220171743,"date":"2021-02-20","operation_mode":0,"allow_rescheduled_by_same_driver":1,"allow_hands_off_order_by_driver":0,"allow_reset_order_status_by_driver":0,"allow_add_order_by_driver":0,"allow_add_manual_order_by_driver":0,"driver_alias":"XXX","vehicle_type":"1 (1: Car, 2: Truck, 3: Motorcycle, 4: Bicycle 5:Pedestrian)","distance":2321231,"geometry":"XXX","total":1,"count":{"already_planned":1},"recurring_pickup_route":false,"allow_adhoc_pickups":true,"allow_deliveries":true},{"id":12,"name":20200511,"date":"2020-05-11","operation_mode":0,"allow_rescheduled_by_same_driver":1,"allow_hands_off_order_by_driver":0,"allow_reset_order_status_by_driver":0,"allow_add_order_by_driver":0,"allow_add_manual_order_by_driver":0,"driver_alias":"XXX","distance":43242321,"geometry":"XXX","total":11,"count":{"already_planned":11},"recurring_pickup_route":false,"allow_adhoc_pickups":true,"allow_deliveries":true}]}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/create-route":{"post":{"summary":"Create a new route by driver","description":"Allows a driver to create a new delivery route if authorized.","tags":["Driver"],"security":[{"bearerAuth":[]}],"requestBody":{"description":"Optional name field to customize the route name","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Custom route name (optional)\n\n**Details:** Type `string`.\n\n**Example:** `route_001`.","examples":["route_001"]}}}}}},"responses":{"200":{"description":"Route created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"route_driver_id":{"type":"integer","description":"Route driver id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `456`.","examples":[456]}}}}}},"400":{"description":"Creation failed due to server or data error","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Exception message`.","examples":["Exception message"]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Unauthorized`.","examples":["Unauthorized"]}}}}}}}}},"/v1/driver/routes/cancel":{"post":{"tags":["Driver"],"summary":"Cancel route by driver","description":"Allows a driver to cancel their own assigned route. Requires business setting 'Allow Cancel Route By Driver' to be enabled. If the route has only one driver, the entire route will be cancelled. If the route has multiple drivers, only this driver's orders will be cancelled.","operationId":"cancelRouteByDriver","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["route_id"],"properties":{"route_id":{"type":"integer","description":"**Required.**\n\nID of the route to cancel\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]}}}}}},"responses":{"200":{"description":"Route cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Route cancelled successfully`.","examples":["Route cancelled successfully"]}}}}}},"400":{"description":"Bad Request - Route ID is required or cancellation failed","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"error":{"type":"string","description":"Error. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `Route ID is required`.","examples":["Route ID is required"]}}}}}},"401":{"description":"Unauthorized - Missing or invalid authorization token","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"error":{"type":"string","description":"Error. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `Missing Authorization Token`.","examples":["Missing Authorization Token"]}}}}}},"403":{"description":"Forbidden - Driver not assigned to route or not allowed to cancel","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"error":{"type":"string","description":"Error. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `You are not allowed to cancel routes`.","examples":["You are not allowed to cancel routes"]}}}}}},"404":{"description":"Not Found - Route does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"error":{"type":"string","description":"Error. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `Route not found`.","examples":["Route not found"]}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/driver/routes/{routeId}/orders":{"get":{"tags":["Driver"],"summary":"Get orders on route for one driver","parameters":[{"in":"path","name":"routeId","schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"ids","schema":{"type":"string","description":"Ids. List of identifiers for the related records.\n\n**Details:** Optional · Type `string`."},"required":false,"description":"Ids. List of identifiers for the related records.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"isHideSuccess","schema":{"type":"integer","description":"Is hide success. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Is hide success. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`."},"order_type":{"type":"string","description":"Order type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nEnum values (from deployed code):\n- `D` — Delivery\n- `P` — Pickup\n- `L` — Label Service\n- `P2P` — Peer to Peer\n- `S` — Storage Order\n- `M` — Moving Order\n- `SH` — Shipping Service\n- `SO` — Shipout\n- `LTL` — LTL Service\n- `I` — Instant Delivery\n\n**Details:** Type `string`.","enum":["D","P","L","P2P","S","M","SH","SO","LTL","I"],"x-enumDescriptions":["Delivery","Pickup","Label Service","Peer to Peer","Storage Order","Moving Order","Shipping Service","Shipout","LTL Service","Instant Delivery"]},"is_p2p":{"type":"integer","description":"Is p2p. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_locked":{"type":"integer","description":"Is locked. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"scan_count":{"type":"integer","description":"Driver loading scans on this stop (driver app only).\n\n**Details:** Type `integer`."},"sorting_scan_count":{"type":"integer","description":"Depot sorting scans on this stop (sorting pages, shipping API, warehouse app). Added additively; 0 when never sorted.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"business_name":{"type":"string","description":"Business name. Human-readable label.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"address_type":{"type":"string","description":"Address type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"signature_option":{"type":"integer","description":"Signature option. Field in the JSON request body.\n\n**Details:** Type `integer`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"buzz_code":{"type":"string","description":"Buzz code. Stable machine-readable code.\n\n**Details:** Type `string`."},"latitude":{"type":"string","description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"longitude":{"type":"string","description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"email":{"type":["string","null"],"description":"Account email address.\n\n**Details:** Type `string` · Nullable."},"telephone":{"type":["string","null"],"description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string` · Nullable."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."},"driver_alias":{"type":"string","description":"Driver alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"stop_number":{"type":"integer","description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"driver_id":{"type":"integer","description":"Driver id.\n\n**Details:** Type `integer`."},"leg_number":{"type":["string","null"],"description":"Number of the driver's leg of this route: the fleet code followed by a sequence (\"ACME-2\"), or \"L-<n>\" when the fleet has no code, numbered across the whole route. Assigned on first read and then kept. Additive; null before a number exists.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"packages":{"type":"integer","description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `integer`."},"notification_language":{"type":"string","description":"Notification language. Field in the JSON request body.\n\n**Details:** Type `string`."},"return_reason_id":{"type":["string","null"],"description":"Return reason id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"orders_status_id":{"type":"integer","description":"Order lifecycle status id (`orders.orders_status_id`). Source: `OrdersStatusInput`.\n\nEnum values (from deployed code):\n- `1` — Need Update Address (`need_update_address`)\n- `2` — New Order (`new_order`)\n- `3` — Waiting To Plan (`waiting_to_plan`)\n- `4` — Planning (`planning`)\n- `5` — Already Planned (`already_planned`)\n- `6` — Plan Failed (`plan_failed`)\n- `14` — Already Pickup (`already_pickup`)\n- `8` — Successful (`successful`)\n- `9` — Redelivered Later (`redelivered_later`)\n- `10` — Need Rescheduled (`need_rescheduled`)\n- `11` — Rescheduled (`rescheduled`)\n- `12` — Cancelled (`cancelled`)\n- `16` — Need To Pick Up (`need_to_pick_up`)\n- `7` — Already Pickup (`already_pickup`)\n- `20` — Out For Delivery (`out_for_delivery`)\n- `21` — Out For Pickup (`out_for_pickup`)\n- `17` — Waiting For Self Pickup (`waiting_for_self_pickup`)\n- `19` — Return To Customer (`return_to_customer`)\n- `25` — Hand Off (`hand_off`)\n- `18` — Self Pickup Completed (`self_pickup_completed`)\n- `22` — Partial Received (`partial_received`)\n- `23` — Partial Delivered (`partial_delivered`)\n- `24` — Partial Pickuped (`partial_pickuped`)\n- `26` — Review (`review`)\n- `27` — Destroyed (`destroyed`)\n- `29` — In Transit (`in_transit`)\n- `30` — Package Lost (`package_lost`)\n- `31` — Package Damaged (`package_damaged`)\n- `32` — Waiting Customer Options (`waiting_customer_options`)\n- `33` — Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)\n- `34` — Waiting Batch Pickup (`waiting_batch_pickup`)\n- `28` — Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)\n- `35` — Payment Required (`payment_required`)\n- `36` — Bulk Transshipment Pending (`bulk_transshipment_pending`)\n- `37` — Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)\n- `38` — Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)\n- `39` — Inbound Scan Required (`inbound_scan_required`)\n- `40` — Rejected By Recipient (`rejected_by_recipient`)\n- `41` — Package Outbound (`package_outbound`)\n- `42` — Waiting For Quote (`waiting_for_quote`)\n- `43` — Waiting Third Party Handover (`waiting_third_party_handover`)\n- `44` — Waiting For Assignment (`waiting_for_assignment`)\n- `45` — Start Pickup (`start_pickup`)\n- `46` — Start Delivery (`start_delivery`)\n- `47` — Out Of Delivery Area (`out_of_delivery_area`)\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5,6,14,8,9,10,11,12,16,7,20,21,17,19,25,18,22,23,24,26,27,29,30,31,32,33,34,28,35,36,37,38,39,40,41,42,43,44,45,46,47],"x-enumDescriptions":["Need Update Address (`need_update_address`)","New Order (`new_order`)","Waiting To Plan (`waiting_to_plan`)","Planning (`planning`)","Already Planned (`already_planned`)","Plan Failed (`plan_failed`)","Already Pickup (`already_pickup`)","Successful (`successful`)","Redelivered Later (`redelivered_later`)","Need Rescheduled (`need_rescheduled`)","Rescheduled (`rescheduled`)","Cancelled (`cancelled`)","Need To Pick Up (`need_to_pick_up`)","Already Pickup (`already_pickup`)","Out For Delivery (`out_for_delivery`)","Out For Pickup (`out_for_pickup`)","Waiting For Self Pickup (`waiting_for_self_pickup`)","Return To Customer (`return_to_customer`)","Hand Off (`hand_off`)","Self Pickup Completed (`self_pickup_completed`)","Partial Received (`partial_received`)","Partial Delivered (`partial_delivered`)","Partial Pickuped (`partial_pickuped`)","Review (`review`)","Destroyed (`destroyed`)","In Transit (`in_transit`)","Package Lost (`package_lost`)","Package Damaged (`package_damaged`)","Waiting Customer Options (`waiting_customer_options`)","Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)","Waiting Batch Pickup (`waiting_batch_pickup`)","Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)","Payment Required (`payment_required`)","Bulk Transshipment Pending (`bulk_transshipment_pending`)","Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)","Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)","Inbound Scan Required (`inbound_scan_required`)","Rejected By Recipient (`rejected_by_recipient`)","Package Outbound (`package_outbound`)","Waiting For Quote (`waiting_for_quote`)","Waiting Third Party Handover (`waiting_third_party_handover`)","Waiting For Assignment (`waiting_for_assignment`)","Start Pickup (`start_pickup`)","Start Delivery (`start_delivery`)","Out Of Delivery Area (`out_of_delivery_area`)"]},"current_route_id":{"type":"integer","description":"Current route id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"related_order_type":{"type":["integer","null"],"description":"How this order links to another business document (`orders.related_order_type`). Source: `RelatedOrderTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Batch Pickup\n- `2` — Super Proxy\n- `3` — Storage Order\n- `4` — Return Request\n- `5` — Moving Order\n- `6` — Kiosk Pickup\n- `7` — Smart Locker Pickup\n- `8` — Product Purchase\n- `9` — Shipping Order\n- `10` — Storage Shipout\n- `11` — Return Label\n- `12` — Third-party Delivery Transfer\n- `16` — Sales Order\n- `17` — Third-party Partial Delivery Split\n- `18` — Order Split\n\n**Details:** Type `integer` · Nullable.","enum":[1,2,3,4,5,6,7,8,9,10,11,12,16,17,18,null],"x-enumDescriptions":["Batch Pickup","Super Proxy","Storage Order","Return Request","Moving Order","Kiosk Pickup","Smart Locker Pickup","Product Purchase","Shipping Order","Storage Shipout","Return Label","Third-party Delivery Transfer","Sales Order","Third-party Partial Delivery Split","Order Split"]},"related_order_id":{"type":["integer","null"],"description":"Id of the related document pointed to by `related_order_type` (storage order, shipping order, sales order, …).\n\n**Details:** Type `integer` · Nullable."},"allow_dropoff":{"type":"integer","description":"Allow dropoff. Field in the JSON request body.\n\n**Details:** Type `integer`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"driverNotes":{"type":"array","items":{"type":"string","description":"Driver notes. Free-text note.\n\n**Details:** Type `string`."},"description":"Driver notes. Free-text note.\n\n**Details:** Type `array`, items `string`."},"files":{"type":"object","properties":{"photo_urls":{"type":"array","items":{"type":"string","description":"Photo urls. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Photo urls. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"signature_urls":{"type":"array","items":{"type":"string","description":"Signature urls. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Signature urls. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}},"description":"Files. Field in the JSON request body.\n\n**Details:** Type `object`."},"is_finished":{"type":"integer","description":"Is finished. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_postponed":{"type":"integer","description":"Is postponed. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"full_address":{"type":"string","description":"Full address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"operation_mode":{"type":"integer","description":"Operation mode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"is_multiple":{"type":"integer","description":"Is multiple. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"total_orders":{"type":"integer","description":"Total orders. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"current_order":{"type":"integer","description":"Current order. Field in the JSON request body.\n\n**Details:** Type `integer`."},"is_recurring_pickup":{"type":"boolean","description":"A mandatory recurring pickup stop\n\n**Details:** Type `boolean`."},"can_hand_off":{"type":"boolean","description":"The driver may hand this stop off: the route allows hand-off and the stop is not a mandatory recurring pickup\n\n**Details:** Type `boolean`."}}}},"example":[{"id":299545,"type":"P","order_type":"P2P","is_p2p":1,"is_locked":0,"ref":"T1","carrier_name":"DEMO","business_name":"DEMO","address_1":"DMEO","address_2":"","address_type":"","signature_option":0,"city":"Saint-Jerome","province":"QC","country":"Canada","postcode":"J5L0E1","buzz_code":"","latitude":"45.797655","longitude":"-74.049801","name":"y","email":null,"telephone":null,"tracking_number":"SR904766214130","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":1,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"related_order_type":null,"related_order_id":null,"allow_dropoff":1,"pin_required":0,"created_at":"2024-01-15 10:30:00","driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"DEMO,Montreal,QC,H4E3R3","operation_mode":0,"is_multiple":1,"total_orders":2,"current_order":2,"is_recurring_pickup":false,"can_hand_off":false},{"id":299548,"type":"P","order_type":"P","is_p2p":0,"is_locked":0,"ref":"","carrier_name":"DEMO","business_name":"DEMO","address_1":"DEMO","address_2":"","city":"Saint-Jerome","province":"QC","country":"Canada","postcode":"J5L0E1","buzz_code":"","latitude":"45.797655","longitude":"-74.049801","name":"X","email":"","telephone":"","tracking_number":"SR270017412103","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":2,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"allow_dropoff":1,"pin_required":0,"created_at":"2024-01-15 11:00:00","driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"DEMO,Saint-Jerome,QC,J5L0E1","operation_mode":0,"is_multiple":1,"total_orders":3,"current_order":1,"is_recurring_pickup":false,"can_hand_off":false},{"id":299546,"type":"D","order_type":"D","is_p2p":0,"is_locked":0,"ref":1231,"carrier_name":"DEMO","business_name":"DEMO","address_1":"DEMO","address_2":"","city":"Saint-Jerome","province":"QC","country":"Canada","postcode":"J5L0E1","buzz_code":"","latitude":"45.797655","longitude":"-74.049801","name":"","email":"","telephone":"","tracking_number":"SR662910478770","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":3,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"allow_dropoff":1,"pin_required":1,"created_at":"2024-01-15 11:30:00","driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"DEMO,Saint-Jerome,QC,J5L0E1","operation_mode":0,"is_multiple":1,"total_orders":3,"current_order":2,"is_recurring_pickup":false,"can_hand_off":false},{"id":299547,"type":"P","order_type":"D","is_p2p":0,"is_locked":0,"ref":123,"carrier_name":"DEMO","business_name":"DEMO","address_1":"DEMO","address_2":"","city":"Montreal","province":"QC","country":"Canada","postcode":"H4E3R3","buzz_code":"","latitude":"45.452116","longitude":"-73.591895","name":"X","email":null,"telephone":null,"tracking_number":"SR329762240553","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":4,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"allow_dropoff":1,"pin_required":0,"created_at":"2024-01-15 12:00:00","driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"DEMO,Saint-Jerome,QC,J5L0E1","operation_mode":0,"is_multiple":1,"total_orders":3,"current_order":3,"is_recurring_pickup":false,"can_hand_off":false},{"id":299545,"type":"D","order_type":"P2P","is_p2p":1,"is_locked":1,"ref":"T1","carrier_name":"DEMO","business_name":"DEMO","address_1":"DEMO","address_2":"","city":"Montreal","province":"QC","country":"Canada","postcode":"H4E3R3","buzz_code":"","latitude":"45.452116","longitude":"-73.591895","name":"x","email":"","telephone":"","tracking_number":"SR904766214130","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":5,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"allow_dropoff":1,"pin_required":1,"created_at":"2024-01-15 10:30:00","driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"DEMO,Montreal,QC,H4E3R3","operation_mode":0,"is_multiple":1,"total_orders":2,"current_order":2,"is_recurring_pickup":false,"can_hand_off":false}]}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}],"description":"Recurring pickups (additive, after every existing key): is_recurring_pickup marks a mandatory recurring pickup stop; can_hand_off is false for such a stop and otherwise follows the route's allow_hands_off_order_by_driver (the hand-off endpoints refuse a recurring stop with recurring_pickups.skip_instead either way)."}},"/v1/driver/routes/{routeId}/get-stop-number/{ref}":{"get":{"tags":["Driver"],"summary":"Get order stop number by ref/orderid/trackingnumber","parameters":[{"in":"path","name":"routeId","schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"ref","schema":{"type":"string","description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"required":true,"description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"integer","description":"Result. Field in the JSON request body.\n\n**Details:** Type `integer`."},"stopnumber":{"type":"string","description":"Stopnumber. Field in the JSON request body.\n\n**Details:** Type `string`."},"stop_number":{"type":"integer","description":"The bare stop number. Read this instead of splitting `stopnumber`: a driver alias may itself contain \"-\".\n\n**Details:** Type `integer`."},"order/tracking/operationevents_id":{"type":"integer","description":"Order/tracking/operationevents id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"packages":{"type":"integer","description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"store_grid":{"type":"string","description":"Store grid. Identifier referencing the related record.\n\n**Details:** Type `string`."},"orders_scanned":{"type":"integer","description":"Orders scanned. Field in the JSON request body.\n\n**Details:** Type `integer`."},"orders_unscanned":{"type":"integer","description":"Orders unscanned. Field in the JSON request body.\n\n**Details:** Type `integer`."},"orders_total":{"type":"integer","description":"Orders total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"route_id":{"type":"integer","description":"The route the scan resolved to. For a per-route scan this is the route asked about; when an order was planned on more than one route, labels printed from this answer name this route.\n\n**Details:** Type `integer`."}}},"example":{"result":1,"stopnumber":"driver001-1","stop_number":1,"order/tracking/operationevents_id":18458,"packages":1,"ref":"test-03","tracking_number":"SR585479158593","store_grid":"","orders_scanned":1,"orders_unscanned":49,"orders_total":50,"route_id":1024}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/routes/{routeId}/add-order/{ref}":{"post":{"tags":["Driver"],"summary":"Add order to route by ref/orderid/trackingnumber","parameters":[{"in":"path","name":"routeId","schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"ref","schema":{"type":"string","description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},"required":true,"description":"Ref. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `string`."},{"in":"query","name":"optimize","schema":{"type":"integer","enum":[0,1],"description":"When `1`, the server re-optimizes the route after the mutation; when `0`, the existing stop order is kept.\n\nWhen `1`, the server re-optimizes the route after the mutation; when `0`, the existing stop order is kept.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"When `1`, the server re-optimizes the route after the mutation; when `0`, the existing stop order is kept.\n\nWhen `1`, the server re-optimizes the route after the mutation; when `0`, the existing stop order is kept.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}}},"example":{"message":"Order added to route successfully","order_id":18458,"ref":"test-03","name":"test-03"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/routes/{routeId}/batch-add-orders-by-driver":{"post":{"tags":["Driver"],"summary":"Batch Add Orders to Route by Driver","description":"Allows an authenticated driver to batch assign orders to a specific route using the routeId in the path.","operationId":"batchAddOrdersToRouteByDriver","security":[{"bearerAuth":[]}],"parameters":[{"name":"routeId","in":"path","description":"ID of the route to which orders will be assigned\n\nRoute id (`routes.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `456`.","required":true,"schema":{"type":"integer","description":"ID of the route to which orders will be assigned\n\nRoute id (`routes.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `456`.","examples":[456]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nList of Superroute order ids.\n\n**Details:** Type `array`, items `integer`.","examples":[[101,102,103]]}},"required":["order_ids"]}}}},"responses":{"200":{"description":"Orders successfully added to the route","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Orders successfully added to route`.","examples":["Orders successfully added to route"]},"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"List of Superroute order ids.\n\n**Details:** Type `array`, items `integer`.","examples":[[101,102,103]]}}}}}},"400":{"description":"Missing or invalid route ID or orders","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Route not found`.","examples":["Route not found"]}}}}}},"403":{"description":"User is not assigned as a driver","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Driver not assigned to current user`.","examples":["Driver not assigned to current user"]}}}}}},"409":{"description":"Some orders are already assigned to another route","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Some orders are already assigned to another route`.","examples":["Some orders are already assigned to another route"]},"conflict_order_ids":{"type":"array","items":{"type":"integer","description":"Conflict order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Conflict order ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`.","examples":[[104,105]]}}}}}},"422":{"description":"Validation failed for order_ids","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","description":"Errors. Field in the JSON request body.\n\n**Details:** Type `object`.","examples":[{"order_ids":["The order_ids field is required."]}]}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Failed to add orders to route`.","examples":["Failed to add orders to route"]}}}}}}}}},"/v1/driver/routes/{routeId}/orders/{orderId}/remove":{"post":{"tags":["Driver"],"summary":"Remove order from route by orderId","parameters":[{"in":"path","name":"routeId","schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"orderId","schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"deleted_order_id":{"type":"integer","description":"Deleted order id. Identifier referencing the related record.\n\n**Details:** Type `integer`."}}},"example":{"result":true,"message":"Successful","route_id":123,"deleted_order_id":102223}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/routes/{routeId}/orders/batchremove":{"post":{"summary":"Batch remove orders from a route","description":"Allows a driver to batch remove their own orders from a specific route if allowed.","tags":["Driver"],"parameters":[{"name":"routeId","in":"path","description":"The ID of the route.\n\nRoute id (`routes.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1234`.","required":true,"schema":{"type":"integer","description":"The ID of the route.\n\nRoute id (`routes.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1234`.","examples":[1234]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`.\n\n**Example:** `5678`.","examples":[5678]},"description":"**Required.**\n\nList of order IDs to remove from the route.\n\n**Details:** Type `array`, items `integer`."}},"required":["order_ids"]},"example":{"order_ids":[5678,5679,5680]}}}},"responses":{"200":{"description":"Orders successfully removed from the route.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `1234`.","examples":[1234]},"deleted_order_ids":{"type":"array","items":{"type":"integer","description":"Deleted order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`.\n\n**Example:** `5678`.","examples":[5678]},"description":"Deleted order ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."}}}}}},"400":{"description":"Bad request. Possible reasons: missing fields, route not found, not allowed to remove, no valid orders, or server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Missing Mandatory field order_ids`.","examples":["Missing Mandatory field order_ids"]}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/driver/routes/{routeId}/points":{"get":{"tags":["Driver"],"summary":"Get points on route for one driver","parameters":[{"in":"path","name":"routeId","schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"startPoint":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"unique_identifier":{"type":"string","description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"apt":{"type":"string","description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"lat":{"type":"string","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"territory":{"type":"integer","description":"Territory. Field in the JSON request body.\n\n**Details:** Type `integer`."},"is_point":{"type":"integer","description":"Is point. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"territory_info":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"center":{"type":"string","description":"Center. Field in the JSON request body.\n\n**Details:** Type `string`."},"coordinate_array":{"type":"string","description":"Coordinate array. Field in the JSON request body.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}},"description":"Territory info. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Start point. Field in the JSON request body.\n\n**Details:** Type `object`."},"endPoint":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"unique_identifier":{"type":"string","description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"apt":{"type":"string","description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"lat":{"type":"string","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"territory":{"type":"integer","description":"Territory. Field in the JSON request body.\n\n**Details:** Type `integer`."},"is_point":{"type":"integer","description":"Is point. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"territory_info":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"center":{"type":"string","description":"Center. Field in the JSON request body.\n\n**Details:** Type `string`."},"coordinate_array":{"type":"string","description":"Coordinate array. Field in the JSON request body.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}},"description":"Territory info. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"End point. Field in the JSON request body.\n\n**Details:** Type `object`."},"breaks":{"type":"array","description":"Additive. The driver breaks planned on this driver's run, earliest first; an empty array when the run has none. Every other field is unchanged.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"start":{"type":"string","description":"When the break starts (Y-m-d H:i:s, the route's local time).\n\n**Details:** Type `string`.\n\n**Example:** `2026-09-14 12:10:00`.","examples":["2026-09-14 12:10:00"]},"end":{"type":"string","description":"When the break ends (Y-m-d H:i:s, the route's local time).\n\n**Details:** Type `string`.\n\n**Example:** `2026-09-14 12:40:00`.","examples":["2026-09-14 12:40:00"]},"minutes":{"type":"integer","description":"Break length in minutes.\n\n**Details:** Type `integer`.\n\n**Example:** `30`.","examples":[30]},"after_stop_number":{"type":["integer","null"],"description":"Stop number the break follows; null means before the first stop.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `7`.","examples":[7]},"addressbook_id":{"type":["integer","null"],"description":"Additive, sRoute 2T 1.0.21: present only for a break taken at one of its places, the address book entry of that place (null when not known).\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `31`.","examples":[31]},"name":{"type":["string","null"],"description":"Additive, sRoute 2T 1.0.21: present only for a break at a place, the place's address book name.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Coffee stop`.","examples":["Coffee stop"]},"latitude":{"type":["number","null"],"description":"Additive, sRoute 2T 1.0.21: present only for a break at a place.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `45.5088`.","examples":[45.5088]},"longitude":{"type":["number","null"],"description":"Additive, sRoute 2T 1.0.21: present only for a break at a place.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `-73.5878`.","examples":[-73.5878]}}}},"reload_stops":{"type":"array","description":"Additive (phase P3). The reloads at a depot planned between the trips of this driver's run, earliest first: sequential trips on sRoute and sRoute 2 (phase P3) or the reload stops sRoute 2T 1.0.20 plans itself, in the same shape; an empty array when the run has none. Every other field is unchanged.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"start":{"type":"string","description":"When the vehicle is at the depot (Y-m-d H:i:s, the route's local time).\n\n**Details:** Type `string`.\n\n**Example:** `2026-09-14 13:05:00`.","examples":["2026-09-14 13:05:00"]},"end":{"type":"string","description":"When loading is done.\n\n**Details:** Type `string`.\n\n**Example:** `2026-09-14 13:25:00`.","examples":["2026-09-14 13:25:00"]},"minutes":{"type":"integer","description":"Loading time in minutes.\n\n**Details:** Type `integer`.\n\n**Example:** `20`.","examples":[20]},"after_stop_number":{"type":["integer","null"],"description":"Stop number the reload follows; null = before the first stop.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `12`.","examples":[12]},"trip":{"type":["integer","null"],"description":"The trip the reload ends (1 = after the first trip).\n\n**Details:** Type `integer` · Nullable.","examples":[1]},"addressbook_id":{"type":["integer","null"],"description":"The depot's address book id.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `12`.","examples":[12]},"name":{"type":["string","null"],"description":"The depot's name.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Main warehouse`.","examples":["Main warehouse"]},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `45.5017`.","examples":[45.5017]},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `-73.5673`.","examples":[-73.5673]}}}},"delivery_alternatives":{"type":"array","description":"Additive. The stops of this driver's run delivered at one of the order's alternative delivery locations instead of the order's own address (the order's address is unchanged), in stop order; an empty array when there are none. Every other field is unchanged.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `1234`.","examples":[1234]},"stop_number":{"type":["integer","null"],"description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `4`.","examples":[4]},"alternative_id":{"type":"integer","description":"The order's delivery alternative the stop is served at.\n\n**Details:** Type `integer`.\n\n**Example:** `88`.","examples":[88]},"addressbook_id":{"type":["integer","null"],"description":"Addressbook id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable.","examples":[null]},"name":{"type":["string","null"],"description":"The address book name, for an alternative that is an address book entry.\n\n**Details:** Type `string` · Nullable.","examples":[null]},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`.\n\n**Example:** `100 Rue Sainte-Catherine, Montreal`.","examples":["100 Rue Sainte-Catherine, Montreal"]},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `45.5075`.","examples":[45.5075]},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `-73.5605`.","examples":[-73.5605]},"time_window_start":{"type":["string","null"],"description":"Time window start. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-14 13:00:00`.","examples":["2026-09-14 13:00:00"]},"time_window_end":{"type":["string","null"],"description":"Time window end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-14 15:00:00`.","examples":["2026-09-14 15:00:00"]}}}},"recurring_pickup_route":{"type":"boolean","description":"Generated from a recurring pickup template\n\n**Details:** Type `boolean`."},"allow_adhoc_pickups":{"type":"boolean","description":"Non-recurring pickup orders may join the route (true for every non-recurring route)\n\n**Details:** Type `boolean`."},"allow_deliveries":{"type":"boolean","description":"Delivery orders may join the route (true for every non-recurring route)\n\n**Details:** Type `boolean`."},"shifts":{"type":"array","description":"Additive, after every existing key. The shifts the driver's run is split into (up to six), in order; an empty array when the run is one shift. Every other field is unchanged.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"shift":{"type":"integer","description":"1 = the first shift.\n\n**Details:** Type `integer`.","examples":[1]},"start":{"type":"string","description":"Shift start (HH:MM, the route's local time).\n\n**Details:** Type `string`.\n\n**Example:** `08:00`.","examples":["08:00"]},"end":{"type":"string","description":"Shift end (HH:MM).\n\n**Details:** Type `string`.\n\n**Example:** `12:00`.","examples":["12:00"]},"start_address":{"type":["object","null"],"description":"Where the shift starts (start_address) or ends (end_address); null = the run's own start or end address.\n\n**Details:** Type `object` · Nullable.","properties":{"addressbook_id":{"type":"integer","description":"Addressbook id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `12`.","examples":[12]},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Main warehouse`.","examples":["Main warehouse"]},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `45.5017`.","examples":[45.5017]},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `-73.5673`.","examples":[-73.5673]}}},"end_address":{"type":["object","null"],"description":"Where the shift starts (start_address) or ends (end_address); null = the run's own start or end address.\n\n**Details:** Type `object` · Nullable.","properties":{"addressbook_id":{"type":"integer","description":"Addressbook id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `12`.","examples":[12]},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Main warehouse`.","examples":["Main warehouse"]},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `45.5017`.","examples":[45.5017]},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `-73.5673`.","examples":[-73.5673]}}},"planned_start":{"type":["string","null"],"description":"When the planned run starts this shift (Y-m-d H:i:s); null for the first shift and before planning.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-14 13:00:00`.","examples":["2026-09-14 13:00:00"]},"planned_end":{"type":["string","null"],"description":"When the planned run comes back at the end of this shift (Y-m-d H:i:s); null before planning.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-14 11:50:00`.","examples":["2026-09-14 11:50:00"]},"starts_after_stop_number":{"type":["integer","null"],"description":"Stop number the shift starts after; null = before the first stop.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `7`.","examples":[7]},"ends_after_stop_number":{"type":["integer","null"],"description":"Stop number the shift ends after.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `7`.","examples":[7]}}}}}}},"example":[{"startPoint":{"id":2,"name":"Home","unique_identifier":"home","business_id":2,"description":"","postcode":"H9S2H9","street_number":40,"street_name":"BOUL Des Sources","apt":"D","city":"Pointe-claire","province":"Quebec","country":"Canada","lat":"45.4484317","lng":"-73.7799527","telephone":5144444444,"territory":1,"is_point":1,"status":1,"created_at":"2020-05-10 17:21:43.00","updated_at":"2020-05-10 17:21:43.00","territory_info":{"id":1,"name":"Great Montreal Area","center":"[24.886,-70.268]","coordinate_array":"","business_id":0,"status":1}},"endPoint":{"id":2,"name":"Home","unique_identifier":"home","business_id":2,"description":"","postcode":"H9S2H9","street_number":40,"street_name":"BOUL Des Sources","apt":"D","city":"Pointe-claire","province":"Quebec","country":"Canada","lat":"45.4484317","lng":"-73.7799527","telephone":5144444444,"territory":1,"is_point":1,"status":1,"created_at":"2020-05-10 17:21:43.00","updated_at":"2020-05-10 17:21:43.00","territory_info":{"id":1,"name":"Great Montreal Area","center":"[24.886,-70.268]","coordinate_array":"","business_id":0,"status":1}},"breaks":[{"start":"2026-09-14 12:10:00","end":"2026-09-14 12:40:00","minutes":30,"after_stop_number":7}],"reload_stops":[{"start":"2026-09-14 13:05:00","end":"2026-09-14 13:25:00","minutes":20,"after_stop_number":12,"trip":1,"addressbook_id":12,"name":"Main warehouse","latitude":45.5017,"longitude":-73.5673}],"delivery_alternatives":[{"order_id":1234,"stop_number":4,"alternative_id":88,"addressbook_id":null,"name":null,"address":"100 Rue Sainte-Catherine, Montreal","latitude":45.5075,"longitude":-73.5605,"time_window_start":"2026-09-14 13:00:00","time_window_end":"2026-09-14 15:00:00"}],"recurring_pickup_route":false,"allow_adhoc_pickups":true,"allow_deliveries":true,"shifts":[{"shift":1,"start":"08:00","end":"12:00","start_address":null,"end_address":{"addressbook_id":12,"name":"Main warehouse","latitude":45.5017,"longitude":-73.5673},"planned_start":null,"planned_end":"2026-09-14 11:50:00","starts_after_stop_number":null,"ends_after_stop_number":7},{"shift":2,"start":"13:00","end":"17:00","start_address":{"addressbook_id":12,"name":"Main warehouse","latitude":45.5017,"longitude":-73.5673},"end_address":null,"planned_start":"2026-09-14 13:00:00","planned_end":null,"starts_after_stop_number":7,"ends_after_stop_number":null}]}]}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}],"description":"Start and end point, scan counts and geometry of the acting driver's run on the route. `breaks` (additive) lists the driver breaks planned on the run: start, end, minutes and after_stop_number (null = before the first stop); it is an empty array when the run has no breaks. `reload_stops` (additive, phase P3) lists the reloads at a depot planned between the trips of the run: start, end, minutes, after_stop_number, trip, and the depot (addressbook_id, name, latitude, longitude); it is an empty array when the run has none. A break taken at one of its places (sRoute 2T 1.0.21) also carries addressbook_id, name, latitude and longitude. `delivery_alternatives` (additive) lists the stops delivered at one of the order's alternative delivery locations: order_id, stop_number, alternative_id, addressbook_id, name, address, latitude, longitude, time_window_start and time_window_end; it is an empty array when there are none. Recurring pickups (additive, after every existing key): recurring_pickup_route tells a route generated from a recurring pickup template; allow_adhoc_pickups and allow_deliveries are its two switches (true for every other route, and before the recurring pickup migrations). `shifts` (additive, after every existing key) lists the shifts the run is split into, each with shift, start and end (HH:MM), start_address and end_address (null = the run's own start or end address), planned_start, planned_end, starts_after_stop_number and ends_after_stop_number; an empty array when the run is one shift."}},"/v1/address/{postcode}":{"post":{"tags":["Address"],"summary":"Get address by postcode","parameters":[{"in":"path","name":"postcode","schema":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Required · Type `string`."},"required":true,"description":"Postal / ZIP code.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"multiple":{"type":"boolean","description":"Whether to return multiple matches\n\n**Details:** Type `boolean` · Default: `false`.","default":false}}}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`."},"province_name":{"type":"string","description":"Province name. Human-readable label.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"cities":{"type":"array","items":{"type":"string","description":"Cities. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Cities. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Successful","postcode":"J5L0E1","type":"CA","province_name":"Quebec","province":"QC","cities":["SAINT-JEROME"],"country":"CA"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/structuredAddressSearch":{"post":{"tags":["Address"],"summary":"Search address by structured address","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Required. Street address to search.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"Optional. City name.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Optional. Province/state code.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"Optional. Country code (e.g. CA, US).\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Optional. Postal/zip code.\n\n**Details:** Type `string`."}},"required":["address"]},"example":{"address":"6701,rue hadley","city":"montreal","province":"qc","country":"CA","postcode":"H4E3R3"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."},"count":{"type":"integer","description":"Count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"data":{"type":"object","properties":{"parsed_query":{"type":"object","properties":{"number":{"type":"string","description":"Number. Field in the JSON request body.\n\n**Details:** Type `string`."},"street":{"type":"string","description":"Street. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"unit":{"type":"string","description":"Unit. Field in the JSON request body.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"state":{"type":"string","description":"State. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."}},"description":"Parsed query. Field in the JSON request body.\n\n**Details:** Type `object`."},"addresslist":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"confidence":{"type":"integer","description":"Confidence. Field in the JSON request body.\n\n**Details:** Type `integer`."},"number":{"type":"string","description":"Number. Field in the JSON request body.\n\n**Details:** Type `string`."},"street":{"type":"string","description":"Street. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"state":{"type":"string","description":"State. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"state_code":{"type":"string","description":"State code. Stable machine-readable code.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"country_code":{"type":"string","description":"Country code. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"postcode_match":{"type":"boolean","description":"Postcode match. Stable machine-readable code.\n\n**Details:** Type `boolean`."},"lat":{"type":"number","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`."},"lng":{"type":"number","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`."}}},"description":"Addresslist. Address component used for geocoding and delivery.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"msg":"Success","count":0,"data":{"parsed_query":{"number":6701,"street":",rue hadley","unit":"","city":"montreal","state":"qc","country":"CAN","postcode":"H4E3R3"},"addresslist":[{"address":"6701 Rue Hadley, Montreal, QC, Canada","confidence":1,"number":6701,"street":"Rue Hadley","city":"Montreal","state":"Quebec","state_code":"QC","country":"Canada","country_code":"CAN","postcode":"","postcode_match":false,"lat":45.452116,"lng":-73.591895}]}}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/addressSearch":{"post":{"tags":["Address"],"summary":"Search address by text","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Required. Full address text to search.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"Optional. Country code to narrow search (e.g. CA, US).\n\n**Details:** Type `string`."}},"required":["address"]},"example":{"address":"6701,rue hadley,montreal,qc,ca","country":"CA"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."},"count":{"type":"integer","description":"Count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"data":{"type":"object","properties":{"query":{"type":"string","description":"Query. Field in the JSON request body.\n\n**Details:** Type `string`."},"parsed_query":{"type":"object","properties":{"number":{"type":"string","description":"Number. Field in the JSON request body.\n\n**Details:** Type `string`."},"street":{"type":"string","description":"Street. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"unit":{"type":"string","description":"Unit. Field in the JSON request body.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"state":{"type":"string","description":"State. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."}},"description":"Parsed query. Field in the JSON request body.\n\n**Details:** Type `object`."},"addresslist":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"confidence":{"type":"integer","description":"Confidence. Field in the JSON request body.\n\n**Details:** Type `integer`."},"number":{"type":"string","description":"Number. Field in the JSON request body.\n\n**Details:** Type `string`."},"street":{"type":"string","description":"Street. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"state":{"type":"string","description":"State. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"state_code":{"type":"string","description":"State code. Stable machine-readable code.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"country_code":{"type":"string","description":"Country code. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"lat":{"type":"number","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`."},"lng":{"type":"number","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`."}}},"description":"Addresslist. Address component used for geocoding and delivery.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"msg":"Success","count":1,"data":{"query":"6701,rue hadley,montreal,qc,ca","parsed_query":{"number":6701,"street":"rue hadley","unit":"","city":"montreal","state":"qc","country":"CAN","postcode":""},"addresslist":[{"address":"6701 Rue Hadley, Montreal, QC, Canada","confidence":1,"number":6701,"street":"Rue Hadley","city":"Montreal","state":"Quebec","state_code":"QC","country":"Canada","country_code":"CAN","postcode":"","lat":45.452116,"lng":-73.591895}]}}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders/{orderId}":{"get":{"tags":["Driver"],"summary":"Get order by Id","parameters":[{"in":"path","name":"orderId","schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"buzz_code":{"type":"string","description":"Buzz code. Stable machine-readable code.\n\n**Details:** Type `string`."},"latitude":{"type":"string","description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"longitude":{"type":"string","description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"tracking_number":{"type":["string","null"],"description":"Superroute or carrier tracking number.\n\n**Details:** Type `string` · Nullable."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."},"driver_alias":{"type":"string","description":"Driver alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"stop_number":{"type":"integer","description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"packages":{"type":"integer","description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `integer`."},"notification_language":{"type":"string","description":"Notification language. Field in the JSON request body.\n\n**Details:** Type `string`."},"return_reason_id":{"type":"integer","description":"Return reason id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"files":{"type":"object","properties":{"signature_urls":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"url":{"type":"string","description":"Url. Absolute or relative URL.\n\n**Details:** Type `string`."},"operation_event_id":{"type":["string","null"],"description":"Operation event id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"gps_tracking_id":{"type":["string","null"],"description":"Gps tracking id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."}}},"description":"Signature urls. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"photo_urls":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"url":{"type":"string","description":"Url. Absolute or relative URL.\n\n**Details:** Type `string`."},"operation_event_id":{"type":["string","null"],"description":"Operation event id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"gps_tracking_id":{"type":["string","null"],"description":"Gps tracking id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."}}},"description":"Photo urls. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Files. Field in the JSON request body.\n\n**Details:** Type `object`."},"driverNotes":{"type":"array","items":{"type":"string","description":"Driver notes. Free-text note.\n\n**Details:** Type `string`."},"description":"Driver notes. Free-text note.\n\n**Details:** Type `array`, items `string`."},"full_address":{"type":"string","description":"Full address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"allow_dropoff":{"type":"integer","description":"Allow dropoff. Field in the JSON request body.\n\n**Details:** Type `integer`."},"related_order_type":{"type":["integer","null"],"description":"How this order links to another business document (`orders.related_order_type`). Source: `RelatedOrderTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Batch Pickup\n- `2` — Super Proxy\n- `3` — Storage Order\n- `4` — Return Request\n- `5` — Moving Order\n- `6` — Kiosk Pickup\n- `7` — Smart Locker Pickup\n- `8` — Product Purchase\n- `9` — Shipping Order\n- `10` — Storage Shipout\n- `11` — Return Label\n- `12` — Third-party Delivery Transfer\n- `16` — Sales Order\n- `17` — Third-party Partial Delivery Split\n- `18` — Order Split\n\n**Details:** Type `integer` · Nullable.","enum":[1,2,3,4,5,6,7,8,9,10,11,12,16,17,18,null],"x-enumDescriptions":["Batch Pickup","Super Proxy","Storage Order","Return Request","Moving Order","Kiosk Pickup","Smart Locker Pickup","Product Purchase","Shipping Order","Storage Shipout","Return Label","Third-party Delivery Transfer","Sales Order","Third-party Partial Delivery Split","Order Split"]},"related_order_id":{"type":["integer","null"],"description":"Id of the related document pointed to by `related_order_type` (storage order, shipping order, sales order, …).\n\n**Details:** Type `integer` · Nullable."},"could_edit_items":{"type":"boolean","description":"Whether the driver can edit related order items. True when related_order_type is storage_order (3), moving_order (5), or shipping_order (9).\n\n**Details:** Type `boolean`."},"related_order_items":{"type":["object","null"],"properties":{"related_order_type":{"type":"integer","description":"How this order links to another business document (`orders.related_order_type`). Source: `RelatedOrderTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Batch Pickup\n- `2` — Super Proxy\n- `3` — Storage Order\n- `4` — Return Request\n- `5` — Moving Order\n- `6` — Kiosk Pickup\n- `7` — Smart Locker Pickup\n- `8` — Product Purchase\n- `9` — Shipping Order\n- `10` — Storage Shipout\n- `11` — Return Label\n- `12` — Third-party Delivery Transfer\n- `16` — Sales Order\n- `17` — Third-party Partial Delivery Split\n- `18` — Order Split\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5,6,7,8,9,10,11,12,16,17,18],"x-enumDescriptions":["Batch Pickup","Super Proxy","Storage Order","Return Request","Moving Order","Kiosk Pickup","Smart Locker Pickup","Product Purchase","Shipping Order","Storage Shipout","Return Label","Third-party Delivery Transfer","Sales Order","Third-party Partial Delivery Split","Order Split"]},"related_order_id":{"type":"integer","description":"Id of the related document pointed to by `related_order_type` (storage order, shipping order, sales order, …).\n\n**Details:** Type `integer`."},"related_order_name":{"type":"string","description":"Related order name. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"grouped_items":{"type":"array","items":{"type":"object","properties":{"packaging_id":{"type":["integer","null"],"description":"Packaging id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"packaging_name":{"type":["string","null"],"description":"Packaging name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable."},"length":{"type":["number","null"],"description":"Length dimension.\n\n**Details:** Type `number` · Nullable."},"width":{"type":["number","null"],"description":"Width dimension.\n\n**Details:** Type `number` · Nullable."},"height":{"type":["number","null"],"description":"Height dimension.\n\n**Details:** Type `number` · Nullable."},"dimension_unit":{"type":["integer","null"],"description":"Dimension unit code from `Packages::DIMENSION_UNIT`: 1=mm, 2=cm, 3=m, 4=inch. Default 1.\n\n**Details:** Type `integer` · Nullable."},"weight":{"type":["number","null"],"description":"Weight of the package or shipment.\n\n**Details:** Type `number` · Nullable."},"weight_unit":{"type":["integer","null"],"description":"Weight unit code from `Packages::WEIGHT_UNIT`: 1=g, 2=kg, 3=oz, 4=lb. Default 1.\n\n**Details:** Type `integer` · Nullable."},"value":{"type":["number","null"],"description":"Value. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable."},"qty":{"type":"integer","description":"Qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}}},"description":"Grouped items. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"raw_items":{"type":"array","items":{"type":"object","properties":{"packaging_id":{"type":["integer","null"],"description":"Packaging id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"packaging_name":{"type":["string","null"],"description":"Packaging name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable."},"length":{"type":["number","null"],"description":"Length dimension.\n\n**Details:** Type `number` · Nullable."},"width":{"type":["number","null"],"description":"Width dimension.\n\n**Details:** Type `number` · Nullable."},"height":{"type":["number","null"],"description":"Height dimension.\n\n**Details:** Type `number` · Nullable."},"dimension_unit":{"type":["integer","null"],"description":"Dimension unit code from `Packages::DIMENSION_UNIT`: 1=mm, 2=cm, 3=m, 4=inch. Default 1.\n\n**Details:** Type `integer` · Nullable."},"weight":{"type":["number","null"],"description":"Weight of the package or shipment.\n\n**Details:** Type `number` · Nullable."},"weight_unit":{"type":["integer","null"],"description":"Weight unit code from `Packages::WEIGHT_UNIT`: 1=g, 2=kg, 3=oz, 4=lb. Default 1.\n\n**Details:** Type `integer` · Nullable."},"value":{"type":["number","null"],"description":"Value. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable."}}},"description":"Raw items. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"products":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"integer","description":"Product id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"product_name":{"type":["string","null"],"description":"Product name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`."},"unit_price":{"type":"number","description":"Unit price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"total_price":{"type":"number","description":"Total price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."}}},"description":"Products. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"summary":{"type":"object","properties":{"total_item_count":{"type":"integer","description":"Total item count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"total_group_count":{"type":"integer","description":"Total group count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"total_grouped_quantity":{"type":"integer","description":"Total grouped quantity. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"total_product_quantity":{"type":"integer","description":"Total product quantity. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}},"description":"Summary. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Related order items. Geographic latitude in decimal degrees.\n\n**Details:** Type `object` · Nullable."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."}}},"example":{"id":10410,"ref":84040085,"address_1":"2300 ainsley crescent","address_2":"","city":"Mont-royal","province":"QC","country":"Canada","postcode":"H3P2S7","buzz_code":"","latitude":"45.5261811","longitude":"-73.6496515","name":"Customer 172","email":"172@sr.com","telephone":5144309193,"tracking_number":null,"note":"Note 172","driver_alias":"driver001","stop_number":1,"status":"Successful","packages":1,"notification_language":"","return_reason_id":1,"files":{"signature_urls":[{"id":1555,"url":"https://admin.superroute.ca/storage/2020-08-17/10410_S_In1mB3gI2ntwsKg.jpeg","operation_event_id":null,"gps_tracking_id":null}],"photo_urls":[{"id":1528,"url":"https://admin.superroute.ca/storage/2020-08-16/10410_P_pNQhAWt8d1Ow3NQ.jpeg","operation_event_id":null,"gps_tracking_id":null}]},"driverNotes":[],"full_address":"22 boul des sources, pointe claire, h9s2h9","allow_dropoff":1,"related_order_type":3,"related_order_id":1231,"could_edit_itmes":true,"related_order_items":{"related_order_type":3,"related_order_id":1231,"related_order_name":"storage_order","status":"confirmed","grouped_items":[{"packaging_id":null,"packaging_name":null,"description":"Desk xxx","length":120,"width":60,"height":75,"dimension_unit":1,"weight":null,"weight_unit":null,"value":null,"qty":2}],"raw_items":[{"packaging_id":null,"packaging_name":null,"description":"Desk xxx","length":120,"width":60,"height":75,"dimension_unit":1,"weight":null,"weight_unit":null,"value":null}],"products":[],"summary":{"total_item_count":2,"total_group_count":1,"total_grouped_quantity":2,"total_product_quantity":0}},"pin_required":1,"created_at":"2024-01-15 10:30:00"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders/{orderId}/price-detail":{"get":{"tags":["Driver"],"summary":"Get unified price detail for an order","description":"Returns the latest price breakdown for the order. If the order is linked to a storage, moving, or shipping order, returns the related order's price details in a unified format.","parameters":[{"in":"path","name":"orderId","schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `10001`."},"required":true,"example":10001,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `10001`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `10001`.","examples":[10001]},"price_type":{"type":"string","enum":["delivery","storage_order","moving_order","shipping_order","label_service"],"description":"Allowed values: `delivery` · `storage_order` · `moving_order` · `shipping_order` · `label_service`.\n\n**Details:** Type `string`.","examples":["storage_order"]},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `CAD`.","examples":["CAD"]},"price_details":{"type":"array","description":"Breakdown of individual fee components\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"label":{"type":"string","description":"Label. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `Storage`.","examples":["Storage"]},"amount":{"type":"number","description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `50`.","examples":[50]}}}},"surcharge_items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Stairs`.","examples":["Stairs"]},"amount":{"type":"number","description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `10`.","examples":[10]},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`.\n\n**Example:** `2`.","examples":[2]},"calculated_amount":{"type":"number","description":"Calculated amount. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `20`.","examples":[20]}}},"description":"Surcharge items. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"promotion_discount":{"type":"number","description":"Promotion discount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `5`.","examples":[5]},"total_price":{"type":"number","description":"Total price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `120.5`.","examples":[120.5]},"paid_amount":{"type":["number","null"],"description":"Paid amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `80`.","examples":[80]},"tax":{"type":"object","properties":{"total_tax":{"type":"number","description":"Total tax. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `6.5`.","examples":[6.5]},"tax_details":{"type":"array","description":"Breakdown of individual tax components\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"tax_name":{"type":"string","description":"Tax name. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `GST`.","examples":["GST"]},"tax_rate":{"type":"number","description":"Tax rate. Field in the JSON request body.\n\n**Details:** Type `number`.\n\n**Example:** `5`.","examples":[5]},"tax_amount":{"type":"number","description":"Tax amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `3.25`.","examples":[3.25]}}}}},"description":"Tax. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"404":{"description":"Order not found"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders/{orderId}/related-order-items":{"patch":{"tags":["Driver"],"summary":"Update related storage/moving/shipping order items by driver order id","parameters":[{"in":"path","name":"orderId","schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","description":"**Required.**\n\nTarget quantity for this grouped item. Use 0 to delete the group.\n\n**Details:** Type `integer`."},"packaging_id":{"type":["integer","null"],"description":"Packaging id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable."},"length":{"type":["number","null"],"description":"Length dimension.\n\n**Details:** Type `number` · Nullable."},"width":{"type":["number","null"],"description":"Width dimension.\n\n**Details:** Type `number` · Nullable."},"height":{"type":["number","null"],"description":"Height dimension.\n\n**Details:** Type `number` · Nullable."},"dimension_unit":{"type":["integer","null"],"description":"Dimension unit code from `Packages::DIMENSION_UNIT`: 1=mm, 2=cm, 3=m, 4=inch. Default 1.\n\n**Details:** Type `integer` · Nullable."},"weight":{"type":["number","null"],"description":"Weight of the package or shipment.\n\n**Details:** Type `number` · Nullable."},"weight_unit":{"type":["integer","null"],"description":"Weight unit code from `Packages::WEIGHT_UNIT`: 1=g, 2=kg, 3=oz, 4=lb. Default 1.\n\n**Details:** Type `integer` · Nullable."},"value":{"type":["number","null"],"description":"Value. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable."}},"required":["qty"]},"description":"**Required.**\n\nItems. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"required":["items"]},"example":{"items":[{"qty":1,"description":"Desk xxx","length":120,"width":60,"height":75,"dimension_unit":1,"weight":35,"weight_unit":2},{"qty":2,"description":"Desk xxx","length":120,"width":60,"height":75,"dimension_unit":1,"weight":35,"weight_unit":2},{"description":"Old cabinet","length":80,"width":40,"height":180,"dimension_unit":1,"weight":45,"weight_unit":2,"qty":0}]}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"related_order_type":{"type":"integer","description":"How this order links to another business document (`orders.related_order_type`). Source: `RelatedOrderTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Batch Pickup\n- `2` — Super Proxy\n- `3` — Storage Order\n- `4` — Return Request\n- `5` — Moving Order\n- `6` — Kiosk Pickup\n- `7` — Smart Locker Pickup\n- `8` — Product Purchase\n- `9` — Shipping Order\n- `10` — Storage Shipout\n- `11` — Return Label\n- `12` — Third-party Delivery Transfer\n- `16` — Sales Order\n- `17` — Third-party Partial Delivery Split\n- `18` — Order Split\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5,6,7,8,9,10,11,12,16,17,18],"x-enumDescriptions":["Batch Pickup","Super Proxy","Storage Order","Return Request","Moving Order","Kiosk Pickup","Smart Locker Pickup","Product Purchase","Shipping Order","Storage Shipout","Return Label","Third-party Delivery Transfer","Sales Order","Third-party Partial Delivery Split","Order Split"]},"related_order_id":{"type":"integer","description":"Id of the related document pointed to by `related_order_type` (storage order, shipping order, sales order, …).\n\n**Details:** Type `integer`."},"related_order_items":{"type":["object","null"],"description":"Related order items. Geographic latitude in decimal degrees.\n\n**Details:** Type `object` · Nullable."},"price_recalculated":{"type":"boolean","description":"Whether the related order price was recalculated after the update\n\n**Details:** Type `boolean`."},"estimate_price_response":{"type":["object","null"],"description":"The new price breakdown after recalculation (null if price was not recalculated)\n\n**Details:** Type `object` · Nullable."}}},"example":{"message":"Success","order_id":10410,"related_order_type":9,"related_order_id":501,"could_edit_itmes":true,"related_order_items":{"related_order_type":9,"related_order_id":501,"related_order_name":"shipping_order","status":1,"grouped_items":[{"packaging_id":null,"packaging_name":null,"description":"Desk xxx","length":120,"width":60,"height":75,"dimension_unit":1,"weight":35,"weight_unit":2,"value":null,"qty":2}],"raw_items":[],"products":[],"summary":{"total_item_count":2,"total_group_count":1,"total_grouped_quantity":2,"total_product_quantity":0}},"price_recalculated":true,"estimate_price_response":{"shipping_fee":25,"pickup_fee":null,"surcharges_total":0,"sub_total":25,"tax":{"total_tax":3.75},"total":28.75,"currency":"CAD"}}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders-status":{"get":{"tags":["Driver"],"summary":"Get order status list","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"S":{"type":"string","description":"S. Field in the JSON request body.\n\n**Details:** Type `string`."},"NR":{"type":"string","description":"Nr. Field in the JSON request body.\n\n**Details:** Type `string`."},"RL":{"type":"string","description":"Rl. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"S":"Successful","NR":"Need Rescheduled","RL":"Reschedule Later"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Driver"],"summary":"Update order status","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStatusUpdate"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"operation_event_id":{"type":"integer","description":"Operation event id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"orderId":12708,"operation_event_id":211,"message":"Success"}}}},"400":{"description":"Bad Request"},"422":{"description":"Delivery PIN verification failed","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Invalid delivery PIN`.","examples":["Invalid delivery PIN"]}}},"examples":{"PIN required":{"value":{"result":false,"message":"Delivery PIN is required"}},"Invalid PIN":{"value":{"result":false,"message":"Invalid delivery PIN"}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/driver/addGpsTackingRecord":{"post":{"tags":["Driver"],"summary":"Add Gps Tracking Record","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"latitude":{"type":"string","description":"Required. GPS latitude coordinate.\n\n**Details:** Type `string`."},"longitude":{"type":"string","description":"Required. GPS longitude coordinate.\n\n**Details:** Type `string`."},"route_id":{"type":["string","null"],"description":"Optional. Route ID associated with this GPS record.\n\n**Details:** Type `string` · Nullable."},"order_id":{"type":["string","null"],"description":"Optional. Order ID associated with this GPS record.\n\n**Details:** Type `string` · Nullable."}},"required":["latitude","longitude"]},"examples":{"example":{"value":{"latitude":"45.5261811","longitude":"-73.6496515","route_id":null,"order_id":null}}}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"message":"Success"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/startDelivery":{"post":{"tags":["Driver"],"summary":"start Delivery By route id","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteStatusUpdate"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"message":"Success"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/endDelivery":{"post":{"tags":["Driver"],"summary":"end Delivery By route id","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteStatusUpdate"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"message":"Success"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/routes/validate-order":{"post":{"tags":["Driver"],"summary":"Validate if ref matches order_id","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRefOrderId"}}},"required":true},"responses":{"200":{"description":"ref matches order"},"400":{"description":"Bad Request"},"404":{"description":"Not found"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders-notes/create":{"post":{"tags":["Driver"],"summary":"Create an order note","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderNotesSave"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"orderId":12708,"message":"Success"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders-notes/{orderId}":{"get":{"tags":["Driver"],"summary":"Get order notes","parameters":[{"in":"path","name":"orderId","schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"notes":{"type":"string","description":"Free-text notes.\n\n**Details:** Type `string`."},"note_time":{"type":"string","description":"Note time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"created_by":{"type":"string","description":"Created by. Field in the JSON request body.\n\n**Details:** Type `string`."}}}},"example":[{"id":78,"notes":"adsafdssa","note_time":"2020-10-01 06:35:32","created_by":"9397-2958 Quebec inc."}]}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/upload-pictures":{"post":{"tags":["Driver"],"summary":"Upload order picture","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPictureUpload"}},"multipart/form-data":{"schema":{"type":"object","required":["orderId","type"],"properties":{"orderId":{"type":"integer","description":"**Required.**\n\nSuperroute order id (`orders.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `12708`.","examples":[12708]},"type":{"type":"string","enum":["photo","signature"],"description":"**Required.**\n\nType discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `photo` · `signature`.\n\n**Details:** Type `string`.","examples":["photo"]},"image":{"type":"string","format":"binary","description":"A single file. Ignored when images[] is sent.\n\n**Details:** Type `string`, format `binary`."},"images[]":{"type":"array","maxItems":10,"items":{"type":"string","format":"binary","description":"Images. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`, format `binary`."},"description":"Several files in one request, at most 10. Each is stored as a separate order file.\n\n**Details:** Type `array`, items `string` · maxItems `10`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `left at door`.","examples":["left at door"]},"gps_tracking_id":{"type":["integer","null"],"description":"Gps tracking id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"operation_event_id":{"type":["integer","null"],"description":"Operation event id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_id":{"type":["integer","null"],"description":"Tracking event id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the first stored file.\n\n**Details:** Type `integer`."},"orderId":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"url":{"type":"string","description":"Url of the first stored file.\n\n**Details:** Type `string`."},"gps_tracking_id":{"type":["string","null"],"description":"Gps tracking id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"operation_event_id":{"type":["string","null"],"description":"Operation event id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"tracking_event_id":{"type":["integer","null"],"description":"The tracking event the proof was tied to, or null when the order has no outcome yet (it is tied when the driver reports one).\n\n**Details:** Type `integer` · Nullable."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"files":{"type":"array","description":"Every stored file, in the order it was sent. One entry for a single image.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"url":{"type":"string","description":"Url. Absolute or relative URL.\n\n**Details:** Type `string`."}}}}}},"example":{"id":2323,"orderId":12708,"url":"https://admin.superroute.ca/storage/2020-08-09/12708_P_JklHTuSn5IiQmkX.jpeg","files":[{"id":2323,"url":"https://admin.superroute.ca/storage/2020-08-09/12708_P_JklHTuSn5IiQmkX.jpeg"},{"id":2324,"url":"https://admin.superroute.ca/storage/2020-08-09/12708_P_Q3fYt9Lk2bXw7Rm.jpeg"}],"gps_tracking_id":null,"operation_event_id":456789,"tracking_event_id":123456,"message":"Success"}}}},"400":{"description":"Bad Request: missing orderId, type or image data, or more than 10 files in images[]. `message` is an array of reasons, worded in the language of the Accept-Language header."}},"security":[{"bearerAuth":[]}],"description":"Stores a proof-of-delivery photo or signature for an order on the driver's current route. Send one file as `image` (multipart file, base64 string or `imageUrl`), or up to 10 files at once as `images[]` (multipart). Each file in `images[]` is stored as its own order file with the same note and event links. When `images[]` is present it takes precedence over `image`."}},"/v1/driver/delete-pictures":{"post":{"tags":["Driver"],"summary":"Delete order picture by orderfile Id","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPictureDelete"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"message":"Success"}}}},"400":{"description":"Bad Request"},"404":{"description":"Order Not Found"}},"security":[{"bearerAuth":[]}]}},"/v1/orders/{orderId}":{"get":{"tags":["Orders"],"summary":"Get order by Id or reference number or tracking number","description":"Returns the order owned by the caller's business. Alliance Order View: a client may also query orders owned by an alliance partner that shares Order View with them (partner holds the Share grant, caller holds the Receive grant, and Order View is enabled for the alliance). For such cross-business orders the response sets is_alliance_data to true, includes alliance and order_owner objects, and masks commercial fields (pricing, commission, internal reference, customer id, order channel, order batches, external/third-party tracking identifiers). Fields the business marked Mandatory under Settings → Add New Order (/setting) may not be blanked by an edit, and a package the edit touches must keep its weight / dimensions when those are mandatory; a violation is answered with result=false and HTTP 400.","parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"business_name":{"type":"string","description":"Business name. Human-readable label.\n\n**Details:** Type `string`."},"stop_number":{"type":["string","null"],"description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"is_alliance_data":{"type":"boolean","description":"True when the order belongs to an alliance partner and is returned through the alliance Order View permission. Commercial fields (pricing, commission, ref, customer_id, order_channel_id, order batches, external/third-party tracking identifiers) are removed from order and packages in that case.\n\n**Details:** Type `boolean`."},"alliance":{"type":["object","null"],"description":"Present only when is_alliance_data is true. The alliance through which access was granted.\n\n**Details:** Type `object` · Nullable.","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`."}}},"order_owner":{"type":["object","null"],"description":"Present only when is_alliance_data is true. The business that owns the order.\n\n**Details:** Type `object` · Nullable.","properties":{"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"business_name":{"type":"string","description":"Business name. Human-readable label.\n\n**Details:** Type `string`."}}},"third_party_provider":{"type":"boolean","description":"Whether the order is currently assigned to a third-party delivery provider. Only present for non-customer callers and never for alliance viewers; absent for customer callers.\n\n**Details:** Type `boolean`."},"third_party_provider_info":{"type":["object","null"],"description":"Present only when third_party_provider is true.\n\n**Details:** Type `object` · Nullable.","properties":{"provider":{"type":"string","description":"Provider. Field in the JSON request body.\n\n**Details:** Type `string`."},"external_order_number":{"type":["string","null"],"description":"External order number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}},"order":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"customer_id":{"type":["string","null"],"description":"Customer id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"apt":{"type":["string","null"],"description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"signature_option":{"type":"integer","description":"Signature option. Field in the JSON request body.\n\n**Details:** Type `integer`."},"insurance_option":{"type":"integer","description":"Insurance option. Field in the JSON request body.\n\n**Details:** Type `integer`."},"need_pickup":{"type":["string","null"],"description":"Need pickup. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"pickup_date":{"type":["string","null"],"description":"Pickup date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string` · Nullable."},"pickup_time_window_start":{"type":["string","null"],"description":"Pickup time window start. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"pickup_time_window_end":{"type":["string","null"],"description":"Pickup time window end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"additional_service":{"type":["string","null"],"description":"Additional service. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"additional_service_settings":{"type":["string","null"],"description":"Additional service settings. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"package_type":{"type":"string","description":"Package handling type. Source: `PackageTypeInput`.\n\nEnum values (from deployed code):\n- `parcel` — Parcel\n- `pallet` — Pallet\n\n**Details:** Type `string`.","enum":["parcel","pallet"],"x-enumDescriptions":["Parcel","Pallet"]},"label_service":{"type":"integer","description":"Label service. Human-readable label.\n\n**Details:** Type `integer`."},"rate_id":{"type":["string","null"],"description":"Rate id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"point_id":{"type":["string","null"],"description":"Point id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`."},"latitude":{"type":["string","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `string` · Nullable."},"longitude":{"type":["string","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `string` · Nullable."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"company_name":{"type":"string","description":"Contact company name at the stop.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."},"order_batch":{"type":"string","description":"Order batch. Field in the JSON request body.\n\n**Details:** Type `string`."},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"length":{"type":"integer","description":"Length dimension.\n\n**Details:** Type `integer`."},"width":{"type":"integer","description":"Width dimension.\n\n**Details:** Type `integer`."},"height":{"type":"integer","description":"Height dimension.\n\n**Details:** Type `integer`."},"insurance_value":{"type":"string","description":"Insurance amount for the package or order in the business currency.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."},"notes":{"type":"string","description":"Free-text notes.\n\n**Details:** Type `string`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"items":{"type":"array","items":{"type":"string","description":"Items. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Items. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"allow_dropoff":{"type":"integer","description":"Allow dropoff. Field in the JSON request body.\n\n**Details:** Type `integer`."},"address_type":{"type":"integer","description":"Address type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"scheduled_date":{"type":"string","description":"Scheduled date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`."},"store_grid":{"type":"string","description":"Store grid. Identifier referencing the related record.\n\n**Details:** Type `string`."},"notification_language":{"type":"string","description":"Notification language. Field in the JSON request body.\n\n**Details:** Type `string`."},"route_id":{"type":["string","null"],"description":"Route id (`routes.id`).\n\n**Details:** Type `string` · Nullable."},"driver_id":{"type":["string","null"],"description":"Driver id.\n\n**Details:** Type `string` · Nullable."},"stop_number":{"type":["string","null"],"description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"orders_status_id":{"type":"integer","description":"Order lifecycle status id (`orders.orders_status_id`). Source: `OrdersStatusInput`.\n\nEnum values (from deployed code):\n- `1` — Need Update Address (`need_update_address`)\n- `2` — New Order (`new_order`)\n- `3` — Waiting To Plan (`waiting_to_plan`)\n- `4` — Planning (`planning`)\n- `5` — Already Planned (`already_planned`)\n- `6` — Plan Failed (`plan_failed`)\n- `14` — Already Pickup (`already_pickup`)\n- `8` — Successful (`successful`)\n- `9` — Redelivered Later (`redelivered_later`)\n- `10` — Need Rescheduled (`need_rescheduled`)\n- `11` — Rescheduled (`rescheduled`)\n- `12` — Cancelled (`cancelled`)\n- `16` — Need To Pick Up (`need_to_pick_up`)\n- `7` — Already Pickup (`already_pickup`)\n- `20` — Out For Delivery (`out_for_delivery`)\n- `21` — Out For Pickup (`out_for_pickup`)\n- `17` — Waiting For Self Pickup (`waiting_for_self_pickup`)\n- `19` — Return To Customer (`return_to_customer`)\n- `25` — Hand Off (`hand_off`)\n- `18` — Self Pickup Completed (`self_pickup_completed`)\n- `22` — Partial Received (`partial_received`)\n- `23` — Partial Delivered (`partial_delivered`)\n- `24` — Partial Pickuped (`partial_pickuped`)\n- `26` — Review (`review`)\n- `27` — Destroyed (`destroyed`)\n- `29` — In Transit (`in_transit`)\n- `30` — Package Lost (`package_lost`)\n- `31` — Package Damaged (`package_damaged`)\n- `32` — Waiting Customer Options (`waiting_customer_options`)\n- `33` — Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)\n- `34` — Waiting Batch Pickup (`waiting_batch_pickup`)\n- `28` — Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)\n- `35` — Payment Required (`payment_required`)\n- `36` — Bulk Transshipment Pending (`bulk_transshipment_pending`)\n- `37` — Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)\n- `38` — Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)\n- `39` — Inbound Scan Required (`inbound_scan_required`)\n- `40` — Rejected By Recipient (`rejected_by_recipient`)\n- `41` — Package Outbound (`package_outbound`)\n- `42` — Waiting For Quote (`waiting_for_quote`)\n- `43` — Waiting Third Party Handover (`waiting_third_party_handover`)\n- `44` — Waiting For Assignment (`waiting_for_assignment`)\n- `45` — Start Pickup (`start_pickup`)\n- `46` — Start Delivery (`start_delivery`)\n- `47` — Out Of Delivery Area (`out_of_delivery_area`)\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5,6,14,8,9,10,11,12,16,7,20,21,17,19,25,18,22,23,24,26,27,29,30,31,32,33,34,28,35,36,37,38,39,40,41,42,43,44,45,46,47],"x-enumDescriptions":["Need Update Address (`need_update_address`)","New Order (`new_order`)","Waiting To Plan (`waiting_to_plan`)","Planning (`planning`)","Already Planned (`already_planned`)","Plan Failed (`plan_failed`)","Already Pickup (`already_pickup`)","Successful (`successful`)","Redelivered Later (`redelivered_later`)","Need Rescheduled (`need_rescheduled`)","Rescheduled (`rescheduled`)","Cancelled (`cancelled`)","Need To Pick Up (`need_to_pick_up`)","Already Pickup (`already_pickup`)","Out For Delivery (`out_for_delivery`)","Out For Pickup (`out_for_pickup`)","Waiting For Self Pickup (`waiting_for_self_pickup`)","Return To Customer (`return_to_customer`)","Hand Off (`hand_off`)","Self Pickup Completed (`self_pickup_completed`)","Partial Received (`partial_received`)","Partial Delivered (`partial_delivered`)","Partial Pickuped (`partial_pickuped`)","Review (`review`)","Destroyed (`destroyed`)","In Transit (`in_transit`)","Package Lost (`package_lost`)","Package Damaged (`package_damaged`)","Waiting Customer Options (`waiting_customer_options`)","Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)","Waiting Batch Pickup (`waiting_batch_pickup`)","Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)","Payment Required (`payment_required`)","Bulk Transshipment Pending (`bulk_transshipment_pending`)","Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)","Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)","Inbound Scan Required (`inbound_scan_required`)","Rejected By Recipient (`rejected_by_recipient`)","Package Outbound (`package_outbound`)","Waiting For Quote (`waiting_for_quote`)","Waiting Third Party Handover (`waiting_third_party_handover`)","Waiting For Assignment (`waiting_for_assignment`)","Start Pickup (`start_pickup`)","Start Delivery (`start_delivery`)","Out Of Delivery Area (`out_of_delivery_area`)"]},"source":{"type":"string","description":"Document or data source selector for this developer-center export.\n\n**Details:** Type `string`."},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`."},"time_window_start":{"type":["string","null"],"description":"Time window start. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"time_window_end":{"type":["string","null"],"description":"Time window end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"return_reason_id":{"type":["string","null"],"description":"Return reason id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"pickup_location_id":{"type":["string","null"],"description":"Pickup location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"related_order_id":{"type":["string","null"],"description":"Id of the related document pointed to by `related_order_type` (storage order, shipping order, sales order, …).\n\n**Details:** Type `string` · Nullable."},"related_order_type":{"type":["string","null"],"description":"How this order links to another business document (`orders.related_order_type`). Source: `RelatedOrderTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Batch Pickup\n- `2` — Super Proxy\n- `3` — Storage Order\n- `4` — Return Request\n- `5` — Moving Order\n- `6` — Kiosk Pickup\n- `7` — Smart Locker Pickup\n- `8` — Product Purchase\n- `9` — Shipping Order\n- `10` — Storage Shipout\n- `11` — Return Label\n- `12` — Third-party Delivery Transfer\n- `16` — Sales Order\n- `17` — Third-party Partial Delivery Split\n- `18` — Order Split\n\n**Details:** Type `string` · Nullable.","enum":[1,2,3,4,5,6,7,8,9,10,11,12,16,17,18,null],"x-enumDescriptions":["Batch Pickup","Super Proxy","Storage Order","Return Request","Moving Order","Kiosk Pickup","Smart Locker Pickup","Product Purchase","Shipping Order","Storage Shipout","Return Label","Third-party Delivery Transfer","Sales Order","Third-party Partial Delivery Split","Order Split"]},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"shipping_method_id":{"type":"integer","description":"Shipping method id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"shipping_price":{"type":["string","null"],"description":"Shipping price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string` · Nullable."},"shipping_cost":{"type":["string","null"],"description":"Shipping cost. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string` · Nullable."},"external_id":{"type":"string","description":"External id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"shipping_address_type":{"type":["string","null"],"description":"Shipping address type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"shipping_zone":{"type":["string","null"],"description":"Shipping zone. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"shipping_label_url":{"type":"string","description":"Shipping label url. Absolute or relative URL.\n\n**Details:** Type `string`."},"shipping_cost_detail":{"type":["string","null"],"description":"Shipping cost detail. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string` · Nullable."},"extend_settings":{"type":"string","description":"Extend settings. Field in the JSON request body.\n\n**Details:** Type `string`."},"price_detail":{"type":"string","description":"Price detail. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"transaction_id":{"type":["string","null"],"description":"Transaction id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"shipping_from":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"apt":{"type":"string","description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"address_type":{"type":"string","description":"Address type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."}},"description":"Address-book / warehouse id used as the sender location; when set, most sender_* fields can be omitted.\n\n**Details:** Type `object`."},"max_ride_minutes":{"type":["integer","null"],"description":"Max ride minutes. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"dispatch_ready_at":{"type":["string","null"],"description":"Dispatch ready at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"route_group_key":{"type":["string","null"],"description":"Route group key. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"goods_class_id":{"type":["integer","null"],"description":"Goods class id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"goods_class":{"type":["string","null"],"description":"Goods class name\n\n**Details:** Type `string` · Nullable."},"delivery_alternatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"addressbook_id":{"type":["integer","null"],"description":"Addressbook id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"address":{"type":["string","null"],"description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"time_window_start":{"type":["string","null"],"description":"Time window start. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"time_window_end":{"type":["string","null"],"description":"Time window end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."}}},"description":"Alternative delivery locations; empty when none. The routing constraint fields are not returned on alliance (cross-business) views.\n\n**Details:** Type `array`, items `object`."}},"description":"Sort direction: typically `asc` or `desc`.\n\n**Details:** Type `object`."},"tracking_numbers":{"type":"array","items":{"type":"string","description":"Tracking numbers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Tracking numbers. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"packages":{"type":"integer","description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `integer`."}}},"example":{"business_name":"Hello Inc.","stop_number":null,"third_party_provider":true,"third_party_provider_info":{"provider":"XXX EXPRESS","external_order_number":"DEMOXXXX"},"order":{"id":109928,"ref":"A100","business_id":333,"customer_id":null,"city":"Saint-Jerome","address_1":"1108 RUE D'AMBOISE","address_2":"","street_number":"","street_name":"","apt":null,"postcode":"J5L0E1","province":"QC","country":"Canada","signature_option":0,"insurance_option":0,"need_pickup":null,"pickup_date":null,"pickup_time_window_start":null,"pickup_time_window_end":null,"additional_service":null,"additional_service_settings":null,"package_type":"parcel","label_service":1,"rate_id":null,"point_id":null,"code":"","latitude":null,"longitude":null,"name":"XY","company_name":"","email":"","telephone":4388789567,"note":"","order_batch":"","packages":[{"id":137687,"order_id":109928,"weight":100,"length":100,"width":100,"height":100,"insurance_value":"0.00","tracking_number":"DS865771519563","external_tracking_number":1111,"notes":"","created_at":"2023-05-25 03:13:04.00","updated_at":"2023-05-28 03:24:24.00","items":[]}],"allow_dropoff":1,"address_type":0,"scheduled_date":"","store_grid":"","notification_language":"en","route_id":null,"driver_id":null,"stop_number":null,"orders_status_id":8,"source":2,"type":"L","time_window_start":null,"time_window_end":null,"return_reason_id":null,"pickup_location_id":null,"related_order_id":null,"related_order_type":null,"created_at":"2023-05-25 03:13:04.00","updated_at":"2023-05-28 03:51:12.00","shipping_method_id":9,"shipping_price":null,"shipping_cost":null,"external_id":109928,"shipping_address_type":null,"shipping_zone":null,"shipping_label_url":"109928_UPS_1685244264.pdf","shipping_cost_detail":null,"extend_settings":"{}","price_detail":"{\"carrier\":\"UPS\"}","transaction_id":null,"shipping_from":{"id":107,"name":"ARM-HOUSTON","country":"Canada","province":"QC","city":"Montreal","street_number":6701,"street_name":"RUE HADLEY","apt":"","postcode":"H4E3R3","telephone":439231312,"address_type":0},"max_ride_minutes":null,"dispatch_ready_at":null,"route_group_key":null,"goods_class_id":null,"goods_class":null,"delivery_alternatives":[]},"tracking_numbers":["DS865771519563"],"packages":1}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Orders"],"summary":"Delete Order By Id","parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"id":11092,"message":"Order 11092 has been deleted successful."}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]},"patch":{"tags":["Orders"],"summary":"Partially update an existing order","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"ID of the order to modify\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"ID of the order to modify\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModifyOrderRequest"}}}},"responses":{"200":{"description":"Order updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModifyOrderResponse"}}}},"400":{"description":"Invalid input; also returned when packagesDetail omits existing package ids that cannot be deleted (order already dispatched/processed, or the package has tracking history)"},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"}},"security":[{"BearerAuth":[]}]}},"/v1/orders/{orderId}/cancel":{"get":{"tags":["Orders"],"summary":"Cancel Order By Id","description":"Cancels an order. A shipping label is cancelled first when the order has one. An order held by a third-party carrier is cancelled at the carrier first: the carrier must support cancellation (otherwise 409 THIRD_PARTY_CANCEL_NOT_SUPPORTED) and must accept (otherwise 409 THIRD_PARTY_CANCEL_FAILED with the carrier's reason); the order is unchanged in both cases. A carrier-held order may be cancelled from any status while the carrier has not taken custody of the parcel. The response carries `third_party` whenever a carrier was involved. Orders with no carrier behave exactly as before.","parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"third_party":{"type":"object","description":"Present only when a third-party carrier held the order.\n\n**Details:** Type `object`.","properties":{"provider":{"type":"string","description":"The carrier holding the order\n\n**Details:** Type `string`."},"supports_cancel":{"type":"boolean","description":"Whether this carrier can be asked to cancel at all\n\n**Details:** Type `boolean`."},"cancelled":{"type":"boolean","description":"True when the carrier accepted the cancellation\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Why the carrier cancellation was not made or was refused\n\n**Details:** Type `string`."}}}}},"example":{"result":true,"id":11092,"message":"Order 11092 has been cancelled successful.","third_party":{"provider":"Intelcom","supports_cancel":true,"cancelled":true}}}}},"400":{"description":"Bad Request"},"401":{"description":"Not permitted, or the current order status does not allow cancellation"},"409":{"description":"The third-party carrier holding the order does not support cancellation (THIRD_PARTY_CANCEL_NOT_SUPPORTED), refused or failed to cancel (THIRD_PARTY_CANCEL_FAILED), or the order is locked by a third-party delivery flow (ORDER_CANCEL_BLOCKED_THIRD_PARTY). The order is unchanged.","content":{"application/json":{"example":{"result":false,"code":"THIRD_PARTY_CANCEL_FAILED","id":11092,"message":"Carrier Intelcom did not cancel the delivery; the order is unchanged. Shipment already out for delivery.","third_party":{"provider":"Intelcom","supports_cancel":true,"cancelled":false,"message":"Carrier Intelcom did not cancel the delivery; the order is unchanged. Shipment already out for delivery."}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/orders/cancel":{"post":{"tags":["Orders"],"summary":"Cancel Order By Number (idempotent)","description":"Cancels an order located by tracking_number, external_tracking_number or order_id (provide exactly one). Same permission, status and third-party carrier rules as GET /v1/orders/{orderId}/cancel (carrier-held orders are cancelled at the carrier first; `third_party` reports the outcome), plus idempotency: cancelling an already-cancelled order returns 200 with already_cancelled=true. When a number matches multiple live orders, 409 is returned with matched_order_ids so the caller can disambiguate by order_id.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"integer","description":"Internal order id\n\n**Details:** Type `integer`."},"tracking_number":{"type":"string","description":"Internal package tracking number\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"External package tracking number supplied at order creation\n\n**Details:** Type `string`."}}},"example":{"external_tracking_number":"WP1234567890"}}}},"responses":{"200":{"description":"successful operation (already_cancelled=true when the order was cancelled before this call)","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"already_cancelled":{"type":"boolean","description":"Already cancelled. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"third_party":{"type":"object","description":"Present only when a third-party carrier held the order.\n\n**Details:** Type `object`.","properties":{"provider":{"type":"string","description":"The carrier holding the order\n\n**Details:** Type `string`."},"supports_cancel":{"type":"boolean","description":"Whether this carrier can be asked to cancel at all\n\n**Details:** Type `boolean`."},"cancelled":{"type":"boolean","description":"True when the carrier accepted the cancellation\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Why the carrier cancellation was not made or was refused\n\n**Details:** Type `string`."}}}}},"example":{"result":true,"id":11092,"already_cancelled":false,"message":"Order 11092 has been cancelled successful.","third_party":{"provider":"Intelcom","supports_cancel":true,"cancelled":true}}}}},"400":{"description":"Validation failed / order not found"},"401":{"description":"Not permitted, or the current order status does not allow cancellation"},"409":{"description":"Number matched multiple live orders (matched_order_ids returned); the third-party carrier holding the order does not support cancellation (THIRD_PARTY_CANCEL_NOT_SUPPORTED) or refused / failed to cancel (THIRD_PARTY_CANCEL_FAILED, with `third_party.message`); or the order is locked by a third-party delivery flow (ORDER_CANCEL_BLOCKED_THIRD_PARTY). The order is unchanged.","content":{"application/json":{"example":{"result":false,"code":"MULTIPLE_ORDERS_MATCHED","message":"Multiple orders matched number WP1234567890, please cancel by order_id","matched_order_ids":[11092,11095]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/orders/list":{"get":{"tags":["Orders"],"summary":"List the caller's orders","description":"Returns the orders owned by the caller's business (business_id = the token owner's service provider), newest first, each with all of its packages and their item lines, plus resolved status / channel / customer / route / driver names. Instant Deliver orders are excluded — they have their own module and listing. A customer token is further narrowed to that customer's own orders and never sees the third-party delivery fields; a contractor (broker) token sees only the orders its own routes and drivers cover, exactly like the web list. Pagination requires BOTH page and per_page (per_page is capped at 1000). With either one missing the response falls back to the newest 1000 orders in a { data, limit, truncated } envelope — every row carries its packages and items, so an unbounded response is not served; paginate to walk the whole book. The payload is an explicit field set: internal plumbing columns (pricing internals, geocoder bookkeeping, computed postcode variants, solver hints, original_* shadow copies, warehouse/user join keys) are deliberately not published, and every published field is always present, null when unset.","parameters":[{"in":"query","name":"page","required":false,"description":"Page number. Paginates only when per_page is also supplied.\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · min `1`.","schema":{"type":"integer","minimum":1,"description":"Page number. Paginates only when per_page is also supplied.\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · min `1`."}},{"in":"query","name":"per_page","required":false,"description":"Page size, 1-1000. Paginates only when page is also supplied (default 20); larger values are clamped to 1000.\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `1000`.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":20,"description":"Page size, 1-1000. Paginates only when page is also supplied (default 20); larger values are clamped to 1000.\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `1000`."}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"current_page":{"type":"integer","description":"Present only when paginated (page + per_page supplied).\n\n**Details:** Type `integer`."},"per_page":{"type":"integer","description":"Present only when paginated.\n\n**Details:** Type `integer`."},"total":{"type":"integer","description":"Present only when paginated.\n\n**Details:** Type `integer`."},"last_page":{"type":"integer","description":"Present only when paginated.\n\n**Details:** Type `integer`."},"data":{"type":"array","description":"The orders.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Resource identifier.\n\n**Details:** Type `integer` · Nullable."},"ref":{"type":["string","null"],"description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"order_code":{"type":["string","null"],"description":"Order code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"external_order_id":{"type":["string","null"],"description":"Merchant / upstream order reference stored on the Superroute order.\n\n**Details:** Type `string` · Nullable."},"external_id":{"type":["string","null"],"description":"External id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"type":{"type":["string","null"],"description":"Order type code. Instant Deliver orders are never returned by this endpoint.\n\n**Details:** Type `string` · Nullable."},"priority":{"type":["integer","null"],"description":"Order priority score (higher = more urgent). Source: `OrderPriorityInput`.\n\nEnum values (from deployed code):\n- `90` — Overdue (system)\n- `80` — Due (system)\n- `75` — Same region (system)\n- `70` — Emergency\n- `60` — Rush\n- `50` — Express\n- `40` — Standard\n- `30` — Economy\n- `20` — Flexible\n- `10` — Hold\n\n**Details:** Type `integer` · Nullable.","enum":[90,80,75,70,60,50,40,30,20,10,null],"x-enumDescriptions":["Overdue (system)","Due (system)","Same region (system)","Emergency","Rush","Express","Standard","Economy","Flexible","Hold"]},"customer_id":{"type":["string","null"],"description":"Customer id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"order_channel_id":{"type":["integer","null"],"description":"Order channel id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"orders_status_id":{"type":["integer","null"],"description":"Order status id; order_status_name carries the readable label.\n\nOrder lifecycle status id (`orders.orders_status_id`). Source: `OrdersStatusInput`.\n\nEnum values (from deployed code):\n- `1` — Need Update Address (`need_update_address`)\n- `2` — New Order (`new_order`)\n- `3` — Waiting To Plan (`waiting_to_plan`)\n- `4` — Planning (`planning`)\n- `5` — Already Planned (`already_planned`)\n- `6` — Plan Failed (`plan_failed`)\n- `14` — Already Pickup (`already_pickup`)\n- `8` — Successful (`successful`)\n- `9` — Redelivered Later (`redelivered_later`)\n- `10` — Need Rescheduled (`need_rescheduled`)\n- `11` — Rescheduled (`rescheduled`)\n- `12` — Cancelled (`cancelled`)\n- `16` — Need To Pick Up (`need_to_pick_up`)\n- `7` — Already Pickup (`already_pickup`)\n- `20` — Out For Delivery (`out_for_delivery`)\n- `21` — Out For Pickup (`out_for_pickup`)\n- `17` — Waiting For Self Pickup (`waiting_for_self_pickup`)\n- `19` — Return To Customer (`return_to_customer`)\n- `25` — Hand Off (`hand_off`)\n- `18` — Self Pickup Completed (`self_pickup_completed`)\n- `22` — Partial Received (`partial_received`)\n- `23` — Partial Delivered (`partial_delivered`)\n- `24` — Partial Pickuped (`partial_pickuped`)\n- `26` — Review (`review`)\n- `27` — Destroyed (`destroyed`)\n- `29` — In Transit (`in_transit`)\n- `30` — Package Lost (`package_lost`)\n- `31` — Package Damaged (`package_damaged`)\n- `32` — Waiting Customer Options (`waiting_customer_options`)\n- `33` — Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)\n- `34` — Waiting Batch Pickup (`waiting_batch_pickup`)\n- `28` — Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)\n- `35` — Payment Required (`payment_required`)\n- `36` — Bulk Transshipment Pending (`bulk_transshipment_pending`)\n- `37` — Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)\n- `38` — Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)\n- `39` — Inbound Scan Required (`inbound_scan_required`)\n- `40` — Rejected By Recipient (`rejected_by_recipient`)\n- `41` — Package Outbound (`package_outbound`)\n- `42` — Waiting For Quote (`waiting_for_quote`)\n- `43` — Waiting Third Party Handover (`waiting_third_party_handover`)\n- `44` — Waiting For Assignment (`waiting_for_assignment`)\n- `45` — Start Pickup (`start_pickup`)\n- `46` — Start Delivery (`start_delivery`)\n- `47` — Out Of Delivery Area (`out_of_delivery_area`)\n\n**Details:** Type `integer` · Nullable.","enum":[1,2,3,4,5,6,14,8,9,10,11,12,16,7,20,21,17,19,25,18,22,23,24,26,27,29,30,31,32,33,34,28,35,36,37,38,39,40,41,42,43,44,45,46,47,null],"x-enumDescriptions":["Need Update Address (`need_update_address`)","New Order (`new_order`)","Waiting To Plan (`waiting_to_plan`)","Planning (`planning`)","Already Planned (`already_planned`)","Plan Failed (`plan_failed`)","Already Pickup (`already_pickup`)","Successful (`successful`)","Redelivered Later (`redelivered_later`)","Need Rescheduled (`need_rescheduled`)","Rescheduled (`rescheduled`)","Cancelled (`cancelled`)","Need To Pick Up (`need_to_pick_up`)","Already Pickup (`already_pickup`)","Out For Delivery (`out_for_delivery`)","Out For Pickup (`out_for_pickup`)","Waiting For Self Pickup (`waiting_for_self_pickup`)","Return To Customer (`return_to_customer`)","Hand Off (`hand_off`)","Self Pickup Completed (`self_pickup_completed`)","Partial Received (`partial_received`)","Partial Delivered (`partial_delivered`)","Partial Pickuped (`partial_pickuped`)","Review (`review`)","Destroyed (`destroyed`)","In Transit (`in_transit`)","Package Lost (`package_lost`)","Package Damaged (`package_damaged`)","Waiting Customer Options (`waiting_customer_options`)","Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)","Waiting Batch Pickup (`waiting_batch_pickup`)","Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)","Payment Required (`payment_required`)","Bulk Transshipment Pending (`bulk_transshipment_pending`)","Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)","Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)","Inbound Scan Required (`inbound_scan_required`)","Rejected By Recipient (`rejected_by_recipient`)","Package Outbound (`package_outbound`)","Waiting For Quote (`waiting_for_quote`)","Waiting Third Party Handover (`waiting_third_party_handover`)","Waiting For Assignment (`waiting_for_assignment`)","Start Pickup (`start_pickup`)","Start Delivery (`start_delivery`)","Out Of Delivery Area (`out_of_delivery_area`)"]},"order_batch":{"type":["string","null"],"description":"Order batch. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"import_batch_number":{"type":["string","null"],"description":"Import batch number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"return_reason_id":{"type":["integer","null"],"description":"Return reason id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable."},"company_name":{"type":["string","null"],"description":"Contact company name at the stop.\n\n**Details:** Type `string` · Nullable."},"email":{"type":["string","null"],"description":"Account email address.\n\n**Details:** Type `string` · Nullable."},"telephone":{"type":["string","null"],"description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string` · Nullable."},"address_1":{"type":["string","null"],"description":"Primary street address line for the stop.\n\n**Details:** Type `string` · Nullable."},"address_2":{"type":["string","null"],"description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string` · Nullable."},"street_number":{"type":["string","null"],"description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"street_name":{"type":["string","null"],"description":"Street name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"apt":{"type":["string","null"],"description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"city":{"type":["string","null"],"description":"City / locality.\n\n**Details:** Type `string` · Nullable."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"postcode":{"type":["string","null"],"description":"Postal / ZIP code.\n\n**Details:** Type `string` · Nullable."},"country":{"type":["string","null"],"description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string` · Nullable."},"latitude":{"type":["string","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `string` · Nullable."},"longitude":{"type":["string","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `string` · Nullable."},"address_type":{"type":["integer","null"],"description":"Address type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer` · Nullable."},"allow_dropoff":{"type":["integer","null"],"description":"Allow dropoff. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"self_pickup":{"type":["integer","null"],"description":"Self-pickup flag: 0=delivery, 1=self-pickup (account must allow self-pickup).\n\n**Details:** Type `integer` · Nullable."},"note":{"type":["string","null"],"description":"Note. Free-text note.\n\n**Details:** Type `string` · Nullable."},"deliver_instruction":{"type":["string","null"],"description":"Deliver instruction. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"pickup_instruction":{"type":["string","null"],"description":"Pickup instruction. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"notification_language":{"type":["string","null"],"description":"Notification language. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"scheduled_date":{"type":["string","null"],"description":"Scheduled date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string` · Nullable."},"time_window_start":{"type":["string","null"],"description":"ISO-8601 UTC timestamp.\n\n**Details:** Type `string` · Nullable."},"time_window_end":{"type":["string","null"],"description":"ISO-8601 UTC timestamp.\n\n**Details:** Type `string` · Nullable."},"service_time":{"type":["integer","null"],"description":"Service time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer` · Nullable."},"ready_at":{"type":["string","null"],"description":"Ready at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"need_pickup":{"type":["integer","null"],"description":"Need pickup. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"pickup_date":{"type":["string","null"],"description":"Pickup date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string` · Nullable."},"pickup_time_window_start":{"type":["string","null"],"description":"ISO-8601 UTC timestamp.\n\n**Details:** Type `string` · Nullable."},"pickup_time_window_end":{"type":["string","null"],"description":"ISO-8601 UTC timestamp.\n\n**Details:** Type `string` · Nullable."},"pickup_service_time":{"type":["integer","null"],"description":"Pickup service time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer` · Nullable."},"package_type":{"type":["string","null"],"description":"Package handling type. Source: `PackageTypeInput`.\n\nEnum values (from deployed code):\n- `parcel` — Parcel\n- `pallet` — Pallet\n\n**Details:** Type `string` · Nullable.","enum":["parcel","pallet",null],"x-enumDescriptions":["Parcel","Pallet"]},"signature_option":{"type":["integer","null"],"description":"Signature option. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"insurance_option":{"type":["integer","null"],"description":"Insurance option. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"shipping_price":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"tip_amount":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"tip_source":{"type":["string","null"],"description":"Tip source. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"cash_collected":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"cash_collected_at":{"type":["string","null"],"description":"Cash collected at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"label_service":{"type":["integer","null"],"description":"Label service. Human-readable label.\n\n**Details:** Type `integer` · Nullable."},"shipping_method_id":{"type":["integer","null"],"description":"Shipping method id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"shipping_label_url":{"type":["string","null"],"description":"Shipping label url. Absolute or relative URL.\n\n**Details:** Type `string` · Nullable."},"carrier_name":{"type":["string","null"],"description":"Carrier name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"route_id":{"type":["integer","null"],"description":"Route id (`routes.id`).\n\n**Details:** Type `integer` · Nullable."},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"stop_number":{"type":["integer","null"],"description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"distance":{"type":["integer","null"],"description":"Distance. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"created_at":{"type":["string","null"],"description":"ISO-8601 UTC timestamp.\n\n**Details:** Type `string` · Nullable."},"updated_at":{"type":["string","null"],"description":"ISO-8601 UTC timestamp.\n\n**Details:** Type `string` · Nullable."},"order_status_name":{"type":["string","null"],"description":"Resolved status label.\n\n**Details:** Type `string` · Nullable."},"order_channel_name":{"type":["string","null"],"description":"Resolved order channel name.\n\n**Details:** Type `string` · Nullable."},"customer_name":{"type":["string","null"],"description":"Resolved customer name.\n\n**Details:** Type `string` · Nullable."},"route_name":{"type":["string","null"],"description":"Resolved route name; null while the order is unrouted.\n\n**Details:** Type `string` · Nullable."},"driver_name":{"type":["string","null"],"description":"Resolved driver name; null while no driver is assigned.\n\n**Details:** Type `string` · Nullable."},"packages_count":{"type":["integer","null"],"description":"The order's declared package count (the orders.packages column). It can differ from the number of rows in packages when packages have not all been created yet.\n\n**Details:** Type `integer` · Nullable."},"packages":{"type":"array","description":"Every package of the order, each with its item lines.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Resource identifier.\n\n**Details:** Type `integer` · Nullable."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"ref":{"type":["string","null"],"description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"weight":{"type":["integer","null"],"description":"Weight of the package or shipment.\n\n**Details:** Type `integer` · Nullable."},"length":{"type":["integer","null"],"description":"Length dimension.\n\n**Details:** Type `integer` · Nullable."},"width":{"type":["integer","null"],"description":"Width dimension.\n\n**Details:** Type `integer` · Nullable."},"height":{"type":["integer","null"],"description":"Height dimension.\n\n**Details:** Type `integer` · Nullable."},"original_weight":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"original_length":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"original_width":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"original_height":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"display_weight_unit":{"type":["integer","null"],"description":"Display weight unit. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer` · Nullable."},"display_dimension_unit":{"type":["integer","null"],"description":"Display dimension unit. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer` · Nullable."},"package_value":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"insurance_value":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"tracking_number":{"type":["string","null"],"description":"Superroute or carrier tracking number.\n\n**Details:** Type `string` · Nullable."},"external_tracking_number":{"type":["string","null"],"description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string` · Nullable."},"external_tracking_url":{"type":["string","null"],"description":"External tracking url. Absolute or relative URL.\n\n**Details:** Type `string` · Nullable."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."},"received_at":{"type":["string","null"],"description":"Received at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"stock_out_at":{"type":["string","null"],"description":"Stock out at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"created_at":{"type":["string","null"],"description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"updated_at":{"type":["string","null"],"description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"third_party_tracking_number":{"type":["string","null"],"description":"Third-party delivery data; omitted for customer tokens.\n\n**Details:** Type `string` · Nullable."},"third_party_tracking_url":{"type":["string","null"],"description":"Third-party delivery data; omitted for customer tokens.\n\n**Details:** Type `string` · Nullable."},"third_party_package_number":{"type":["string","null"],"description":"Third-party delivery data; omitted for customer tokens.\n\n**Details:** Type `string` · Nullable."},"third_party_order_number":{"type":["string","null"],"description":"Third-party delivery data; omitted for customer tokens.\n\n**Details:** Type `string` · Nullable."},"tpd_handed_over_at":{"type":["string","null"],"description":"Third-party delivery data; omitted for customer tokens.\n\n**Details:** Type `string` · Nullable."},"tpd_delivery_outcome":{"type":["string","null"],"description":"Third-party delivery data; omitted for customer tokens.\n\n**Details:** Type `string` · Nullable."},"tpd_delivery_outcome_at":{"type":["string","null"],"description":"Third-party delivery data; omitted for customer tokens.\n\n**Details:** Type `string` · Nullable."},"items":{"type":"array","description":"Item lines of this package.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Resource identifier.\n\n**Details:** Type `integer` · Nullable."},"package_id":{"type":["integer","null"],"description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable."},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable."},"quantity":{"type":["integer","null"],"description":"Quantity of units.\n\n**Details:** Type `integer` · Nullable."},"unit":{"type":["string","null"],"description":"Unit. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"unit_price":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"sku":{"type":["string","null"],"description":"Stock keeping unit / product code.\n\n**Details:** Type `string` · Nullable."},"barcode":{"type":["string","null"],"description":"Barcode. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"hscode":{"type":["string","null"],"description":"Hscode. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"origin":{"type":["string","null"],"description":"Origin. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"weight":{"type":["integer","null"],"description":"Weight of the package or shipment.\n\n**Details:** Type `integer` · Nullable."}}}}}}},"items":{"type":"array","description":"Item lines recorded against the order itself rather than against a package. Usually empty.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Resource identifier.\n\n**Details:** Type `integer` · Nullable."},"package_id":{"type":["integer","null"],"description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable."},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable."},"quantity":{"type":["integer","null"],"description":"Quantity of units.\n\n**Details:** Type `integer` · Nullable."},"unit":{"type":["string","null"],"description":"Unit. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"unit_price":{"type":["string","null"],"description":"Decimal, serialized as a string.\n\n**Details:** Type `string` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"sku":{"type":["string","null"],"description":"Stock keeping unit / product code.\n\n**Details:** Type `string` · Nullable."},"barcode":{"type":["string","null"],"description":"Barcode. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"hscode":{"type":["string","null"],"description":"Hscode. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"origin":{"type":["string","null"],"description":"Origin. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"weight":{"type":["integer","null"],"description":"Weight of the package or shipment.\n\n**Details:** Type `integer` · Nullable."}}}}}}},"limit":{"type":"integer","description":"Present only when NOT paginated: the ceiling applied to the fallback response (1000).\n\n**Details:** Type `integer`."},"truncated":{"type":"boolean","description":"Present only when NOT paginated: true when the business has more orders than the ceiling, so the caller must paginate to see the rest.\n\n**Details:** Type `boolean`."}}},"example":{"current_page":1,"per_page":20,"total":1,"last_page":1,"data":[{"id":1782522,"ref":"WP-REF-001","order_code":"SR123456","external_order_id":"SHOP-8891","external_id":null,"type":"D","priority":2,"customer_id":1981,"order_channel_id":12,"orders_status_id":8,"order_batch":"2026-07-19-AM","import_batch_number":null,"return_reason_id":null,"name":"Jane Doe","company_name":"Doe Studio","email":"jane@example.com","telephone":5141234567,"address_1":"5333 Av. Casgrain","address_2":null,"street_number":5333,"street_name":"Av. Casgrain","apt":1400,"city":"Montreal","province":"QC","postcode":"H2T 1X3","country":"CA","latitude":"45.5245000","longitude":"-73.5989000","address_type":0,"allow_dropoff":1,"self_pickup":0,"note":"Leave at the front desk","deliver_instruction":"Ring the bell twice","pickup_instruction":null,"notification_language":"en","scheduled_date":"2026-07-20","time_window_start":"2026-07-20T13:00:00.000000Z","time_window_end":"2026-07-20T17:00:00.000000Z","service_time":10,"ready_at":"2026-07-19T18:00:00.000000Z","need_pickup":0,"pickup_date":null,"pickup_time_window_start":null,"pickup_time_window_end":null,"pickup_service_time":null,"package_type":"parcel","signature_option":1,"insurance_option":0,"currency":"CAD","shipping_price":"28.42","tip_amount":"3.00","tip_source":"driver_app","cash_collected":null,"cash_collected_at":null,"label_service":0,"shipping_method_id":null,"shipping_label_url":null,"carrier_name":null,"route_id":31532,"driver_id":2,"stop_number":3,"distance":5,"created_at":"2026-07-19T14:30:05.000000Z","updated_at":"2026-07-20T09:12:44.000000Z","order_status_name":"Successful","order_channel_name":"Local Delivery","customer_name":"Doe Studio","route_name":"Montreal AM 07-20","driver_name":"Marc Tremblay","packages_count":1,"packages":[{"id":2058492,"order_id":1782522,"ref":"WP-REF-001","status":3,"weight":2400,"length":30,"width":20,"height":15,"original_weight":2400,"original_length":30,"original_width":20,"original_height":15,"display_weight_unit":1,"display_dimension_unit":1,"package_value":"120.00","insurance_value":null,"tracking_number":"SR621079457793","external_tracking_number":"WP1234567890","external_tracking_url":null,"notes":null,"received_at":"2026-07-19T16:04:11.000000Z","stock_out_at":"2026-07-20T07:40:00.000000Z","created_at":"2026-07-19T14:30:05.000000Z","updated_at":"2026-07-20T09:12:44.000000Z","third_party_tracking_number":null,"third_party_tracking_url":null,"third_party_package_number":null,"third_party_order_number":null,"tpd_handed_over_at":null,"tpd_delivery_outcome":null,"tpd_delivery_outcome_at":null,"items":[{"id":77001,"package_id":234567,"name":"Ceramic mug","description":"Glazed, 350ml","quantity":2,"unit":"pcs","unit_price":"18.50","currency":"CAD","sku":"MUG-350-WHT","barcode":612345678901,"hscode":"6912.00","origin":"CA","weight":900}]}],"items":[]}]}}}},"401":{"description":"Unauthorized — the token's group may not list orders"}},"security":[{"bearerAuth":[]}]}},"/v1/orders-reconciliation":{"get":{"tags":["Orders"],"summary":"Incremental orders reconciliation feed","description":"Stable (updated_at, id) cursor pagination over the caller's orders within an updated_at window, for scheduled reconciliation sweeps. Pass next_cursor from the previous page to continue; every item carries unix timestamps so consumers never parse ambiguous local times. updated_from/updated_to accept unix timestamps or 'Y-m-d H:i:s' strings in the platform timezone.","parameters":[{"in":"query","name":"updated_from","required":false,"schema":{"type":"string","description":"Updated from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},"description":"Updated from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"updated_to","required":false,"schema":{"type":"string","description":"Updated to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},"description":"Updated to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"cursor","required":false,"schema":{"type":"string","description":"Cursor. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},"description":"Cursor. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `50` · min `1` · max `200`."},"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `50` · min `1` · max `200`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"items":[{"order_id":123456,"ref":"WP-REF-001","type":"D","orders_status_id":8,"orders_status_key":"successful","customer_id":1981,"updated_at":"2026-07-20 14:30:05","updated_timestamp":1784745005,"created_timestamp":1784658605,"packages":[{"package_id":234567,"ref":"WP-REF-001","tracking_number":"SR00012345601","external_tracking_number":"WP1234567890"}]}],"per_page":50,"has_more":true,"next_cursor":"MjAyNi0wNy0yMCAxNDozMDowNXwxMjM0NTY="}}}},"400":{"description":"Validation failed"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/tracking-events/reconciliation":{"get":{"tags":["Orders"],"summary":"Incremental tracking-events reconciliation feed","description":"Id-ascending cursor pagination over the caller's tracking events (append-only) within an updated_at window. Same parameters as /v1/orders-reconciliation. occurred_at/occurred_timestamp expose the business occurrence time (falls back to created time for historical rows).","parameters":[{"in":"query","name":"updated_from","required":false,"schema":{"type":"string","description":"Updated from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},"description":"Updated from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"updated_to","required":false,"schema":{"type":"string","description":"Updated to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},"description":"Updated to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"cursor","required":false,"schema":{"type":"string","description":"Cursor. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},"description":"Cursor. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `50` · min `1` · max `200`."},"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `50` · min `1` · max `200`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"items":[{"id":90001,"order_id":123456,"tracking_event_status_id":300,"tracking_event_key":"delivered","type":"D","reason_id":null,"incident_reason":null,"updated_at":"2026-07-20 14:30:05","updated_timestamp":1784745005,"created_timestamp":1784745005,"occurred_at":"2026-07-20 14:30:05","occurred_timestamp":1784745005}],"per_page":50,"has_more":false,"next_cursor":null}}}},"400":{"description":"Validation failed"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/documentation/postman-collection":{"get":{"tags":["Documentation"],"summary":"Download Postman Collection (always current)","description":"Converts the deployed OpenAPI document into a Postman Collection v2.1 on every request, so the download is always in sync with the live API. Query params: source=default|ua (which OpenAPI document to convert), download=0 to view inline instead of downloading. No authentication required.","parameters":[{"in":"query","name":"source","required":false,"schema":{"type":"string","enum":["default","ua"],"description":"Document or data source selector for this developer-center export.\n\nDocument or data source selector for this developer-center export.\n\nEnum values:\n- `default` — Main Superroute API document\n- `ua` — UA (white-label) API document\n\n**Details:** Optional · Type `string`.","x-enumDescriptions":["Main Superroute API document","UA (white-label) API document"]},"description":"Document or data source selector for this developer-center export.\n\nDocument or data source selector for this developer-center export.\n\nEnum values:\n- `default` — Main Superroute API document\n- `ua` — UA (white-label) API document\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"download","required":false,"schema":{"type":"string","enum":["0","1"],"description":"When `1`, the response is returned as a file download; when `0`, inline body.\n\nWhen `1`, the response is returned as a file download; when `0`, inline body.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `string`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"description":"When `1`, the response is returned as a file download; when `0`, inline body.\n\nWhen `1`, the response is returned as a file download; when `0`, inline body.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"Postman Collection v2.1 JSON (Content-Disposition: attachment by default)"}}}},"/documentation/integration-updates":{"get":{"tags":["Documentation"],"summary":"Integration updates guide (always current)","description":"Guide to the additive API & webhook capabilities — idempotent cancel, reconciliation feeds, error codes, v2 webhook signatures, payload envelope, new events, delivery options, token restrictions — with adoption examples. Generated live on every request. Browsers receive a styled, localized HTML page; non-browser clients receive raw Markdown. Query params: download=1 to download the Markdown file, format=md to force raw Markdown inline, lang=<code> (en, chs, cht, de, es, fr, it, nl, pt, sr, hu, pl, sk, cs) to select the language. No authentication required.","parameters":[{"in":"query","name":"download","required":false,"schema":{"type":"string","enum":["0","1"],"description":"When `1`, the response is returned as a file download; when `0`, inline body.\n\nWhen `1`, the response is returned as a file download; when `0`, inline body.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `string`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"description":"When `1`, the response is returned as a file download; when `0`, inline body.\n\nWhen `1`, the response is returned as a file download; when `0`, inline body.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"format","required":false,"description":"md forces raw Markdown even for browsers\n\nAllowed values: `md`.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","enum":["md"],"description":"md forces raw Markdown even for browsers\n\nAllowed values: `md`.\n\n**Details:** Optional · Type `string`."}},{"in":"query","name":"lang","required":false,"description":"Document language (defaults to the platform locale)\n\nAllowed values: `en` · `chs` · `cht` · `de` · `es` · `fr` · `it` · `nl` · `pt` · `sr` · `hu` · `pl` · `sk` · `cs`.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","enum":["en","chs","cht","de","es","fr","it","nl","pt","sr","hu","pl","sk","cs"],"description":"Document language (defaults to the platform locale)\n\nAllowed values: `en` · `chs` · `cht` · `de` · `es` · `fr` · `it` · `nl` · `pt` · `sr` · `hu` · `pl` · `sk` · `cs`.\n\n**Details:** Optional · Type `string`."}}],"responses":{"200":{"description":"text/html page for browsers; text/markdown for scripts or with format=md / download=1"}}}},"/documentation/order-status-flow":{"get":{"tags":["Documentation"],"summary":"Order status dictionary & flow (always current)","description":"Complete order status dictionary, transition diagrams and cancel rules, generated live from the deployed code on every request. Browsers receive a styled, localized HTML page with rendered diagrams; non-browser clients receive raw Markdown. Query params: download=1 to download the Markdown file, format=md to force raw Markdown inline, lang=<code> (en, chs, cht, de, es, fr, it, nl, pt, sr, hu, pl, sk, cs) to select the language. No authentication required.","parameters":[{"in":"query","name":"download","required":false,"schema":{"type":"string","enum":["0","1"],"description":"When `1`, the response is returned as a file download; when `0`, inline body.\n\nWhen `1`, the response is returned as a file download; when `0`, inline body.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `string`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"description":"When `1`, the response is returned as a file download; when `0`, inline body.\n\nWhen `1`, the response is returned as a file download; when `0`, inline body.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"format","required":false,"description":"md forces raw Markdown even for browsers\n\nAllowed values: `md`.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","enum":["md"],"description":"md forces raw Markdown even for browsers\n\nAllowed values: `md`.\n\n**Details:** Optional · Type `string`."}},{"in":"query","name":"lang","required":false,"description":"Document language (defaults to the platform locale)\n\nAllowed values: `en` · `chs` · `cht` · `de` · `es` · `fr` · `it` · `nl` · `pt` · `sr` · `hu` · `pl` · `sk` · `cs`.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","enum":["en","chs","cht","de","es","fr","it","nl","pt","sr","hu","pl","sk","cs"],"description":"Document language (defaults to the platform locale)\n\nAllowed values: `en` · `chs` · `cht` · `de` · `es` · `fr` · `it` · `nl` · `pt` · `sr` · `hu` · `pl` · `sk` · `cs`.\n\n**Details:** Optional · Type `string`."}}],"responses":{"200":{"description":"text/html page for browsers; text/markdown for scripts or with format=md / download=1"}}}},"/v1/orders/{orderId}/resend-pin":{"post":{"tags":["Orders"],"summary":"Resend delivery PIN","description":"Generates a new delivery PIN and sends it via SMS and Email to the recipient. The old PIN is invalidated.","parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"ID of the order to resend PIN for\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"ID of the order to resend PIN for\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"PIN resent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Delivery PIN has been resent successfully`.","examples":["Delivery PIN has been resent successfully"]}}}}}},"400":{"description":"PIN verification not required or no contact info","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `PIN verification is not required for this order`.","examples":["PIN verification is not required for this order"]}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Order not found`.","examples":["Order not found"]}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/orders/{orderId}/packages":{"get":{"tags":["Orders"],"summary":"Get order packages by orderId","parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"length":{"type":"integer","description":"Length dimension.\n\n**Details:** Type `integer`."},"width":{"type":"integer","description":"Width dimension.\n\n**Details:** Type `integer`."},"height":{"type":"integer","description":"Height dimension.\n\n**Details:** Type `integer`."},"insurance_value":{"type":"string","description":"Insurance amount for the package or order in the business currency.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."},"notes":{"type":"string","description":"Free-text notes.\n\n**Details:** Type `string`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"items":{"type":"array","items":{"type":"string","description":"Items. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Items. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}}}},"example":[{"id":151284,"order_id":121380,"ref":20311,"weight":1000,"length":300,"width":200,"height":100,"insurance_value":"200.00","tracking_number":"SR319377023615","external_tracking_number":123456789,"notes":"","status":0,"created_at":"2023-09-11 04:15:57.00","updated_at":"2023-09-11 04:15:57.00","items":[]}]}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/tracking/{trackingNumber}/route-assignments":{"get":{"tags":["Orders"],"summary":"Get the route history of the parcel carrying a tracking number (client / employee)","description":"Route history of the parcel carrying the given tracking number. The number may be the system tracking number, the external tracking number or the third-party carrier tracking number of any package of an order owned by the caller's business; matched_by says which one matched. The response lists how many times the order was put on a route (assignment_count) and every assignment, newest route first. Each assignment carries: route (id, name, date, status); broker (the driver's own broker, else the broker holding the route slot, else the route's contract; null when none); driver (id, alias, name, phone; null when the slot has no driver); stop_number; the delivery outcome; and the proofs taken on that route. The delivery outcome is given three ways: delivery_status is the integer stored on the assignment and defined by the DeliveryStatusInput constants (0 NOT_DELIVERED, 1 DELIVER_SUCCESS, 2 DELIVER_FAIL, 3 DELIVER_CANCEL); delivery_status_key is the stable machine key to switch on (pending, successful, failed, cancelled) and never changes or gets translated; delivery_status_text is the human label. return_reason (id, reason) is set when the attempt failed. Proofs use exactly the proofs[] shape of GET /v1/tracking/{trackingNumber}: stable file_id, upload time, permanent and signed URLs and the event context (tracking_event_id, tracking_event_status_id, tracking_event_key, service_type 1 = delivery / 2 = pickup, service_status 1 = success / 2 = failed). A proof uploaded without an event is read off the order's timeline, so it reports the same outcome a tied proof would. The top-level proofs[] is the full list for the parcel, identical to the tracking API's. Each assignment's proofs[] holds the subset taken on that route, each with an extra operation_event_id: the operation the proof documents, resolved the way uploads are tied (the operation recorded on the file, else the order's operation recorded against the proof's tracking event, whether that event was recorded or read off the timeline). Available to client and employee accounts of the business that owns the order (not customer or driver tokens). Backed by GraphQL orderRouteAssignments.","parameters":[{"in":"path","name":"trackingNumber","required":true,"schema":{"type":"string","description":"System tracking number, external tracking number or third-party carrier tracking number of the parcel\n\n**Details:** Required · Type `string`."},"description":"System tracking number, external tracking number or third-party carrier tracking number of the parcel\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Route assignments, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"matched_by":{"type":"string","enum":["tracking_number","external_tracking_number","third_party_tracking_number"],"description":"Allowed values: `tracking_number` · `external_tracking_number` · `third_party_tracking_number`.\n\n**Details:** Type `string`."},"order":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":["string","null"],"description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status_id":{"type":"integer","description":"Numeric status id. For order endpoints this is `orders_status_id` (`OrdersStatusInput`).\n\n**Details:** Type `integer`."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."}},"description":"Sort direction: typically `asc` or `desc`.\n\n**Details:** Type `object`."},"package":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"tracking_number":{"type":["string","null"],"description":"Superroute or carrier tracking number.\n\n**Details:** Type `string` · Nullable."},"external_tracking_number":{"type":["string","null"],"description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string` · Nullable."},"third_party_tracking_number":{"type":["string","null"],"description":"Third party tracking number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}},"description":"Package. Field in the JSON request body.\n\n**Details:** Type `object`."},"assignment_count":{"type":"integer","description":"Assignment count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"assignments":{"type":"array","description":"newest route first\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"route":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable."},"date":{"type":["string","null"],"description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"status_id":{"type":["integer","null"],"description":"Numeric status id. For order endpoints this is `orders_status_id` (`OrdersStatusInput`).\n\n**Details:** Type `integer` · Nullable."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."}},"description":"Route. Field in the JSON request body.\n\n**Details:** Type `object`."},"broker":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}},"description":"The driver's own broker, else the broker holding the route slot, else the route's contract; null when none\n\n**Details:** Type `object` · Nullable."},"driver":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"alias":{"type":["string","null"],"description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable."},"phone":{"type":["string","null"],"description":"Phone number used for OTP or contact.\n\n**Details:** Type `string` · Nullable."}},"description":"null when the slot has no driver\n\n**Details:** Type `object` · Nullable."},"stop_number":{"type":["integer","null"],"description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"delivery_status":{"type":["integer","null"],"description":"Stored outcome, DeliveryStatusInput constants: 0 NOT_DELIVERED, 1 DELIVER_SUCCESS, 2 DELIVER_FAIL, 3 DELIVER_CANCEL\n\n**Details:** Type `integer` · Nullable."},"delivery_status_key":{"type":"string","enum":["pending","successful","failed","cancelled"],"description":"Stable machine key of delivery_status; switch on this, it is never translated or renamed\n\nAllowed values: `pending` · `successful` · `failed` · `cancelled`.\n\n**Details:** Type `string`."},"delivery_status_text":{"type":"string","enum":["Pending","Successful","Failed","Cancelled"],"description":"Human label of delivery_status (English)\n\nAllowed values: `Pending` · `Successful` · `Failed` · `Cancelled`.\n\n**Details:** Type `string`."},"return_reason":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."}},"description":"Set when the attempt failed\n\n**Details:** Type `object` · Nullable."},"assigned_at":{"type":"string","description":"When the order was put on this route, in the caller's timezone\n\n**Details:** Type `string`."},"assigned_at_utc":{"type":"string","description":"assigned_at in UTC\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"proofs":{"type":"array","description":"Proofs taken on this route: the tracking-API proof fields plus operation_event_id\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"url":{"type":"string","description":"Url. Absolute or relative URL.\n\n**Details:** Type `string`."},"full_url":{"type":"string","description":"Full url. Absolute or relative URL.\n\n**Details:** Type `string`."},"type":{"type":"integer","description":"1 = signature, 2 = photo\n\n**Details:** Type `integer`."},"file_id":{"type":"integer","description":"File id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"uploaded_at":{"type":["string","null"],"description":"Uploaded at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"uploaded_timestamp":{"type":["integer","null"],"description":"Uploaded timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer` · Nullable."},"signed_url":{"type":"string","description":"Signed url. Absolute or relative URL.\n\n**Details:** Type `string`."},"signed_url_expires_at":{"type":"integer","description":"Signed url expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`."},"tracking_event_id":{"type":["integer","null"],"description":"Tracking event id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_status_id":{"type":["integer","null"],"description":"Tracking event status id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_key":{"type":["string","null"],"description":"Tracking event key. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"service_type":{"type":["integer","null"],"description":"1 = delivery, 2 = pickup\n\n**Details:** Type `integer` · Nullable."},"service_status":{"type":["integer","null"],"description":"1 = success, 2 = failed\n\n**Details:** Type `integer` · Nullable."},"operation_event_id":{"type":["integer","null"],"description":"The operation event the proof documents (recorded on the file, else resolved through its tracking event)\n\n**Details:** Type `integer` · Nullable."}}}}}}},"proofs":{"type":"array","description":"every proof of the parcel, identical to proofs[] of GET /v1/tracking/{trackingNumber}\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"url":{"type":"string","description":"Url. Absolute or relative URL.\n\n**Details:** Type `string`."},"full_url":{"type":"string","description":"Full url. Absolute or relative URL.\n\n**Details:** Type `string`."},"type":{"type":"integer","description":"1 = signature, 2 = photo\n\n**Details:** Type `integer`."},"file_id":{"type":"integer","description":"File id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"uploaded_at":{"type":["string","null"],"description":"Uploaded at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"uploaded_timestamp":{"type":["integer","null"],"description":"Uploaded timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer` · Nullable."},"signed_url":{"type":"string","description":"Signed url. Absolute or relative URL.\n\n**Details:** Type `string`."},"signed_url_expires_at":{"type":"integer","description":"Signed url expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`."},"tracking_event_id":{"type":["integer","null"],"description":"Tracking event id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_status_id":{"type":["integer","null"],"description":"Tracking event status id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_key":{"type":["string","null"],"description":"Tracking event key. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"service_type":{"type":["integer","null"],"description":"1 = delivery, 2 = pickup\n\n**Details:** Type `integer` · Nullable."},"service_status":{"type":["integer","null"],"description":"1 = success, 2 = failed\n\n**Details:** Type `integer` · Nullable."}}}},"generated_at":{"type":"string","description":"Generated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."}}},"example":{"result":true,"tracking_number":"WP183187779585","matched_by":"tracking_number","order":{"id":1637361,"ref":"ZX10261234","status_id":5,"status":"Out for Delivery"},"package":{"id":1925410,"tracking_number":"WP183187779585","external_tracking_number":"ZX10261234","third_party_tracking_number":null},"assignment_count":2,"assignments":[{"route":{"id":27101,"name":"A-260909-04","date":"2026-09-10","status_id":2,"status":"Approved"},"broker":null,"driver":{"id":1802,"alias":"V31","name":"Haroon","phone":7480462809},"stop_number":16,"delivery_status":0,"delivery_status_key":"pending","delivery_status_text":"Pending","return_reason":null,"assigned_at":"2026-09-09 12:08:35","assigned_at_utc":"2026-09-09 11:08:35","updated_at":"2026-09-09 12:08:35","proofs":[]},{"route":{"id":26988,"name":"P-Collection-260907-03","date":"2026-09-08","status_id":3,"status":"Success"},"broker":{"id":7036,"name":"Lucas"},"driver":{"id":1790,"alias":"P201","name":"Sajid","phone":7401724210},"stop_number":4,"delivery_status":2,"delivery_status_key":"failed","delivery_status_text":"Failed","return_reason":{"id":3,"reason":"Recipient not at home"},"assigned_at":"2026-09-07 11:28:43","assigned_at_utc":"2026-09-07 10:28:43","updated_at":"2026-09-08 09:41:12","proofs":[{"url":"/storage/2026-09-07/1637361_P_h1B9mKNv02yTJee.jpeg","full_url":"https://admin.superroute.ca/storage/2026-09-07/1637361_P_h1B9mKNv02yTJee.jpeg","type":2,"file_id":1874236,"uploaded_at":"2026-09-08 09:41:12","uploaded_timestamp":1788860472,"signed_url":"https://admin.superroute.ca/files/pod/1874236?expires=1789586006&signature=...","signed_url_expires_at":1789586006,"tracking_event_id":8498812,"tracking_event_status_id":200,"tracking_event_key":"need_rescheduled","service_type":1,"service_status":2}]}],"proofs":[{"url":"/storage/2026-09-07/1637361_P_h1B9mKNv02yTJee.jpeg","full_url":"https://admin.superroute.ca/storage/2026-09-07/1637361_P_h1B9mKNv02yTJee.jpeg","type":2,"file_id":1874236,"uploaded_at":"2026-09-08 09:41:12","uploaded_timestamp":1788860472,"signed_url":"https://admin.superroute.ca/files/pod/1874236?expires=1789586006&signature=...","signed_url_expires_at":1789586006,"tracking_event_id":8498812,"tracking_event_status_id":200,"tracking_event_key":"need_rescheduled","service_type":1,"service_status":2}],"generated_at":"2026-09-09 21:30:00 UTC"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Not a client / employee token, or the order is outside the caller's visibility"},"404":{"description":"No package of the caller's business carries this tracking number"}}}},"/v1/orders/{orderId}/audit-timeline":{"get":{"tags":["Orders"],"summary":"Get the audit timeline of an order (client / employee)","description":"Every recorded touch on the order from every source, merged into one chronological list: web actions, driver app scans, warehouse scans, client API calls, automation and carrier events. Each entry carries the source (web / api / driver_app / warehouse / automation / carrier / system / scan / device), the acting account (id, name, email, group), IP address when recorded, route and stop number, status change, the raw details of the call and the underlying record id. Times are given in the timezone of the client that owns the order (timezone field) and in UTC (at_utc). Available to client and employee accounts of the business that owns the order (not customer or driver tokens). Backed by GraphQL orderAuditTimeline and the developer MCP tool get_order_audit_timeline. `device` entries are the parcel's handling by a smart locker, kiosk or smart drop: event is the device order event type (stored, collected, removed, overdue, exception_opened, ...), status_before / status_after are device order statuses, event_code is null, and details carries device_order_id, device_type, device_id, device_name, grid_code, kind, actor_type, actor_id, channel, smart_locker_log_id, device_operation_log_id and payload; source_detail is device:<device_type> and record is device_order_events#<id>.","parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Order id\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Order id\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Audit timeline","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_numbers":{"type":"array","items":{"type":"string","description":"Tracking numbers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Tracking numbers. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"timezone":{"type":"string","description":"IANA timezone of the order's client; the at field of every entry is in this zone\n\n**Details:** Type `string`."},"generated_at":{"type":"string","description":"Generated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"entries":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","description":"At. Field in the JSON request body.\n\n**Details:** Type `string`."},"at_utc":{"type":"string","description":"At utc. Field in the JSON request body.\n\n**Details:** Type `string`."},"source":{"type":"string","enum":["web","api","driver_app","warehouse","automation","carrier","system","scan","device"],"description":"Document or data source selector for this developer-center export.\n\nAllowed values: `web` · `api` · `driver_app` · `warehouse` · `automation` · `carrier` · `system` · `scan` · `device`.\n\n**Details:** Type `string`."},"source_detail":{"type":"string","description":"Source detail. Field in the JSON request body.\n\n**Details:** Type `string`."},"event":{"type":"string","description":"Event. Field in the JSON request body.\n\n**Details:** Type `string`."},"event_code":{"type":["integer","null"],"description":"Event code. Stable machine-readable code.\n\n**Details:** Type `integer` · Nullable."},"actor":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"group":{"type":"string","description":"Group. Field in the JSON request body.\n\n**Details:** Type `string`."}},"description":"Actor. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"ip_address":{"type":["string","null"],"description":"Ip address. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"route":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"stop_number":{"type":["string","null"],"description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}},"description":"Route. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"status_before":{"type":["string","null"],"description":"Status before. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string` · Nullable."},"status_after":{"type":["string","null"],"description":"Status after. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string` · Nullable."},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."},"details":{"type":"object","description":"Details. Field in the JSON request body.\n\n**Details:** Type `object`."},"record":{"type":"string","description":"Record. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"description":"Entries. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"order_id":1583779,"ref":"S882288500554","tracking_numbers":["XLC084449624065"],"business_id":995,"timezone":"Europe/London","generated_at":"2026-08-27 13:00:00 UTC","entries":[{"at":"2026-08-26 13:05:19","at_utc":"2026-08-26 12:05:19","source":"api","source_detail":"shipping API (driver operation)","event":"order sorting and loading scan","event_code":1006,"actor":{"id":995,"name":"XL Courier","email":"api@example.com","group":"client"},"ip_address":"203.0.113.10","route":{"id":25005,"name":"A-260826-02","driver_id":null,"stop_number":"V12A-1"},"status_before":null,"status_after":null,"reason":null,"details":{"ref":"XLC084449624065","route_id":25005,"driver_id":null,"channel":"api","result":1,"stop_number":"V12A-1"},"record":"operation_events#5702467"},{"at":"2026-08-26 13:06:07","at_utc":"2026-08-26 12:06:07","source":"system","source_detail":"tracking event","event":"removed_from_route","event_code":401,"actor":null,"ip_address":null,"route":{"id":25005,"name":"A-260826-02","driver_id":null,"stop_number":null},"status_before":null,"status_after":null,"reason":null,"details":{"type":"D"},"record":"tracking_event#8172198"},{"at":"2026-09-15 10:06:00","at_utc":"2026-09-15 14:06:00","source":"device","source_detail":"device:smart_locker","event":"stored","event_code":null,"actor":null,"ip_address":null,"route":null,"status_before":"depositing","status_after":"stored","reason":null,"details":{"device_order_id":5012,"device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A","grid_code":"A-12","kind":"shipout_pickup","actor_type":"driver","actor_id":7,"channel":"device","smart_locker_log_id":33},"record":"device_order_events#90017","mirror":false,"key":true,"source_label":"Device","source_detail_label":"Smart locker","event_label":"Stored"}]}}}},"401":{"description":"Missing or invalid token"},"403":{"description":"Caller is not a client or employee of the business that owns the order"},"404":{"description":"Order not found"}},"security":[{"bearerAuth":[]}]}},"/v1/orders/delete-packages":{"post":{"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"package_ids":{"type":"array","items":{"type":"integer","description":"Package ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Required. Array of package IDs to delete.\n\n**Details:** Type `array`, items `integer`."}},"required":["package_ids"]},"example":{"order_id":23123,"package_ids":[151475]}}},"required":true},"summary":"delete packages from order","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"deleted":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."}}},"description":"Deleted. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"deleted":[{"id":151475,"ref":"A003","tracking_number":"SR472060120132","external_tracking_number":""}],"message":"Success"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unautherized"}},"security":[{"bearerAuth":[]}]}},"/v1/orders/updateorderbatch":{"post":{"tags":["Orders"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"List of Superroute order ids.\n\n**Details:** Type `array`, items `integer`."},"order_batch":{"type":"string","description":"Order batch. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"order_ids":[1,2,3],"order_batch":"test-01"}}},"required":true},"summary":"update order batch by orderIds","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"result":true,"msg":"Successful"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unautherized"}},"security":[{"bearerAuth":[]}]}},"/v1/orders/updatetimewindowbyrefs":{"post":{"tags":["Orders"],"summary":"Update time window for orders by reference","operationId":"updateOrderTimeWindowByRef","description":"Updates time_window_start and time_window_end for one or multiple orders using their reference numbers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refs","ref_type","time_window_start","time_window_end"],"properties":{"refs":{"type":"array","items":{"type":"string","description":"Refs. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"**Required.**\n\nArray of order reference numbers\n\n**Details:** Type `array`, items `string`.","examples":[["ABC123","XYZ789"]]},"ref_type":{"type":"integer","description":"**Required.**\n\nType of reference (1: ref, 2: tracking_number, 3: order_id)\n\n**Details:** Type `integer`.","examples":["ref"]},"time_window_start":{"type":"string","format":"date-time","description":"**Required.**\n\nStart of time window (format: Y-m-d H:i:s)\n\n**Details:** Type `string`, format `date-time`.\n\n**Example:** `2025-05-01 08:00:00`.","examples":["2025-05-01 08:00:00"]},"time_window_end":{"type":"string","format":"date-time","description":"**Required.**\n\nEnd of time window (must be later than start)\n\n**Details:** Type `string`, format `date-time`.\n\n**Example:** `2025-05-01 18:00:00`.","examples":["2025-05-01 18:00:00"]}}}}}},"responses":{"200":{"description":"Time window updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"processed_refs":{"type":"array","items":{"type":"string","description":"Processed refs. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Processed refs. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`.","examples":[["ABC123","XYZ789"]]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Time window updated successfully`.","examples":["Time window updated successfully"]}}}}}},"400":{"description":"Bad request or no results found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `No results found`.","examples":["No results found"]}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","description":"Errors. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Errors. Element of a list or map in the request/response payload.\n\n**Details:** Type `array`, items `string`."},"description":"Errors. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Internal server error`.","examples":["Internal server error"]}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/driver/register":{"post":{"summary":"Register a new driver","description":"Register a new driver account. When X-BUSINESS-ID header is provided (self-registration mode), the business must be an enabled client and must have Driver Self Registration turned on; otherwise the request is refused and nothing is written. Whether the new account can be used right away is then Driver Self Registration Review (on by default): when that switch is on, the account is created disabled and queued for review. This is a public endpoint — no authentication required. Rate limited: at most 10 attempts per IP per minute.","security":[],"tags":["Driver"],"parameters":[{"name":"X-BUSINESS-ID","in":"header","required":true,"schema":{"type":"string","description":"Valid business ID is required.\n\n**Details:** Required · Type `string`."},"description":"Valid business ID is required.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"alias":{"type":"string","description":"**Required.**\n\nAlias. Field in the JSON request body.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`."},"password":{"type":"string","description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string`."},"email":{"type":"string","format":"email","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email`."},"telephone":{"type":"string","description":"**Required.**\n\nPhone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"address":{"type":["string","null"],"description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"address_2":{"type":["string","null"],"description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string` · Nullable."},"city":{"type":["string","null"],"description":"City / locality.\n\n**Details:** Type `string` · Nullable."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"country":{"type":["string","null"],"description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string` · Nullable."},"postcode":{"type":["string","null"],"description":"Postal / ZIP code.\n\n**Details:** Type `string` · Nullable."},"language":{"type":"string","description":"**Required.**\n\nLanguage. Field in the JSON request body.\n\n**Details:** Type `string`."},"capacity":{"type":["integer","null"],"description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `integer` · Nullable."},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable."},"start_location_id":{"type":["integer","null"],"description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_location_id":{"type":["integer","null"],"description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."}},"required":["alias","name","password","email","telephone","language"]},"example":{"alias":"driver01","name":"John","password":12345678,"email":"join3@gmail.com","telephone":5555555555,"address":"demo","address_2":"demo","city":"demo","province":"demo","country":"CA","postcode":"H0H0H0","language":"en","capacity":null,"territory_id":null,"start_location_id":null,"end_location_id":null}}}},"responses":{"200":{"description":"Successful registration","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"business_id":{"type":"string","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"Email":{"type":"string","description":"Email. Email address.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"capacity":{"type":["integer","null"],"description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `integer` · Nullable."},"start_location_id":{"type":["integer","null"],"description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_location_id":{"type":["integer","null"],"description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable."},"skills":{"type":"array","items":{"type":"string","description":"Skills. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Skills. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}}},"example":{"result":true,"id":790,"business_id":1704,"Email":"join34@gmail.com","name":"John","status":0,"language":"en","alias":"driver01","telephone":5555555555,"capacity":null,"start_location_id":null,"end_location_id":null,"territory_id":null,"skills":[]}}}},"429":{"description":"Too many registration attempts from this IP (limit: 10 per minute). Retry after the delay indicated by the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Too Many Attempts.`.","examples":["Too Many Attempts."]}}}}}}}}},"/v1/user/login":{"post":{"tags":["User"],"summary":"User login","description":"Authenticate a user (Client/Employee/Admin/Driver) and receive a Bearer token. This is a public endpoint — no authentication required.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email`.\n\n**Example:** `user@example.com`.","examples":["user@example.com"]},"password":{"type":"string","description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string`.\n\n**Example:** `your_password`.","examples":["your_password"]},"remember_me":{"type":"boolean","description":"Keep the session alive longer\n\n**Details:** Type `boolean`.","examples":[false]}}}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"access_token":{"type":"string","description":"Access token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`.\n\n**Example:** `eyJ0eXAiOiJKV1QiLCJhbGciOi...`.","examples":["eyJ0eXAiOiJKV1QiLCJhbGciOi..."]},"token_type":{"type":"string","description":"Token type. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`.\n\n**Example:** `Bearer`.","examples":["Bearer"]},"expires_at":{"type":"string","format":"date-time","description":"Expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`.\n\n**Example:** `2026-03-17 14:30:00`.","examples":["2026-03-17 14:30:00"]},"expires_timestamp":{"type":"integer","description":"Expires timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`.\n\n**Example:** `1742222400`.","examples":[1742222400]},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `John Doe`.","examples":["John Doe"]},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`.\n\n**Example:** `user@example.com`.","examples":["user@example.com"]}}}}}},"401":{"description":"Unauthorized - invalid credentials or inactive account"}}}},"/v1/oauth/token":{"post":{"tags":["User"],"summary":"OAuth2 token","description":"OAuth2-compatible login endpoint. Accepts the same parameters as /v1/user/login. This is a public endpoint — no authentication required.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email`.\n\n**Example:** `user@example.com`.","examples":["user@example.com"]},"password":{"type":"string","description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string`.\n\n**Example:** `your_password`.","examples":["your_password"]}}}}}},"responses":{"200":{"description":"Token issued successfully","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"access_token":{"type":"string","description":"Access token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`.\n\n**Example:** `eyJ0eXAiOiJKV1QiLCJhbGciOi...`.","examples":["eyJ0eXAiOiJKV1QiLCJhbGciOi..."]},"token_type":{"type":"string","description":"Token type. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`.\n\n**Example:** `Bearer`.","examples":["Bearer"]},"expires_at":{"type":"string","format":"date-time","description":"Expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`.\n\n**Example:** `2026-03-17 14:30:00`.","examples":["2026-03-17 14:30:00"]},"expires_timestamp":{"type":"integer","description":"Expires timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`.\n\n**Example:** `1742222400`.","examples":[1742222400]},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `John Doe`.","examples":["John Doe"]},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`.\n\n**Example:** `user@example.com`.","examples":["user@example.com"]}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/user/logout":{"get":{"tags":["User"],"summary":"Logs out current logged in user session","responses":{"200":{"description":"Successfully logged out","content":{"application/json":{"schema":{"type":"string"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/user/refresh-token":{"post":{"summary":"Refresh API token","description":"Refresh the API token by extending its validity period to one period from the current time. A valid Bearer Token is required.","operationId":"refreshToken","tags":["User"],"security":[{"bearerAuth":[]}],"responses":{"200":{"401":{"description":"Unauthorized"},"description":"Token refreshed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"access_token":{"type":"string","description":"Access token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`.\n\n**Example:** `eyJ0eXAiOiJKV1QiLCJhbGciOi...`.","examples":["eyJ0eXAiOiJKV1QiLCJhbGciOi..."]},"token_type":{"type":"string","description":"Token type. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`.\n\n**Example:** `Bearer`.","examples":["Bearer"]},"expires_at":{"type":"string","format":"date-time","description":"Expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`.\n\n**Example:** `2025-05-07 23:59:59`.","examples":["2025-05-07 23:59:59"]},"expires_timestamp":{"type":"integer","description":"Expires timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`.\n\n**Example:** `1751913599`.","examples":[1751913599]},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `John Doe`.","examples":["John Doe"]},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`.\n\n**Example:** `john@example.com`.","examples":["john@example.com"]}}}}}}}}},"/v1/ocr/scan-codes":{"post":{"tags":["OCR"],"summary":"Extract scan codes (barcodes and QR codes) from images, PDFs, or ZIP archives","description":"Accepts an uploaded file (image, PDF, or ZIP archive) and extracts all barcodes and QR codes using the ImageHelper scan code extraction method.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"**Required.**\n\nImage file (jpg, jpeg, png, webp, heic), PDF, or ZIP archive containing images\n\n**Details:** Type `string`, format `binary`."}},"required":["file"]}}}},"responses":{"200":{"description":"OK - Extracted scan codes","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Success status\n\n**Details:** Type `boolean`."},"data":{"type":"array","description":"Array of scan code results, one per file/page\n\n**Details:** Type `array`, items `array`.","items":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","description":"The scan code value\n\n**Details:** Type `string`."},"type":{"type":"string","description":"The scan code type (e.g., CODE-128, QR-Code, EAN-13)\n\n**Details:** Type `string`."},"is_qrcode":{"type":"boolean","description":"Whether this is a QR code\n\n**Details:** Type `boolean`."},"is_barcode":{"type":"boolean","description":"Whether this is a traditional barcode\n\n**Details:** Type `boolean`."}}},"description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Type `array`, items `object`."}}}},"example":{"result":true,"data":[[{"value":1234567890123,"type":"EAN-13","is_qrcode":false,"is_barcode":true},{"value":"https://example.com","type":"QR-Code","is_qrcode":true,"is_barcode":false}]]}}}},"422":{"description":"Unprocessable Entity - Invalid or unsupported file","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"errors":{"type":"object","description":"Errors. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"message":"The given data was invalid.","errors":{"file":["The file must be a file of type: jpg, jpeg, png, webp, heic, zip, pdf."]}}}}},"500":{"description":"Internal Server Error - Unexpected system error","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"result":false,"msg":"Failed to process scan code extraction"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/ocr/parse-route-list":{"post":{"tags":["OCR"],"summary":"Parse route list pages from delivery application screenshots using AI/OCR","description":"Accepts an uploaded file (image, PDF, or ZIP archive) containing delivery route list screenshots and uses AI to extract structured route information including tracking number, recipient name, stop number, route identifier, and structured address information (address_1, address_2, city, province, country, postcode).","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"**Required.**\n\nImage file (jpg, jpeg, png, webp, heic), PDF, or ZIP archive containing route list screenshots\n\n**Details:** Type `string`, format `binary`."}},"required":["file"]}}}},"responses":{"200":{"description":"OK - Extracted route list data","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Success status\n\n**Details:** Type `boolean`."},"data":{"type":"array","description":"Array of route data results, one per file/page\n\n**Details:** Type `array`, items `array`.","items":{"type":"array","items":{"type":"object","properties":{"tracking_number":{"type":"string","description":"Tracking number or order number\n\n**Details:** Type `string`."},"recipient_name":{"type":"string","description":"Name of the recipient\n\n**Details:** Type `string`."},"stop_number":{"type":"integer","description":"Number of stops or deliveries on this route\n\n**Details:** Type `integer`."},"route":{"type":"string","description":"Route identifier (without 'Route:' prefix, e.g., 'T001' instead of 'Route: T001')\n\n**Details:** Type `string`."},"address":{"type":"object","description":"Structured delivery address information for this route\n\n**Details:** Type `object`.","properties":{"address_1":{"type":"string","description":"Main address (street number and name). Unit/apt/suite info removed from here.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Unit, apartment, or suite information if present\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City name\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province/state (preferably 2-letter ISO code)\n\n**Details:** Type `string`."},"country":{"type":"string","description":"Country (2-letter ISO code)\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal/ZIP code\n\n**Details:** Type `string`."}}}}},"description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Type `array`, items `object`."}}}},"example":{"result":true,"data":[[{"tracking_number":"TRK123456789","recipient_name":"John Smith","stop_number":25,"route":"T001","address":{"address_1":"123 Main Street","address_2":"Suite 100","city":"Toronto","province":"ON","country":"CA","postcode":"M5H 2N2"}},{"tracking_number":"TRK987654321","recipient_name":"Jane Doe","stop_number":18,"route":"T002","address":{"address_1":"456 Oak Avenue","address_2":"","city":"Vancouver","province":"BC","country":"CA","postcode":"V6B 1A1"}}]]}}}},"422":{"description":"Unprocessable Entity - Invalid or unsupported file","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"errors":{"type":"object","description":"Errors. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"message":"The given data was invalid.","errors":{"file":["The file must be a file of type: jpg, jpeg, png, webp, heic, zip, pdf."]}}}}},"500":{"description":"Internal Server Error - OCR service token not set or processing failed","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"result":false,"msg":"OCR service token is not set."}}}}},"security":[{"bearerAuth":[]}]}},"/v1/client/customers":{"get":{"operationId":"clientListCustomers","tags":["Client"],"summary":"get customer list","parameters":[{"in":"query","name":"customer_ids","schema":{"type":"string","description":"Customer ids. List of identifiers for the related records.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `1,2,3`.","examples":["1,2,3"]},"required":false,"description":"Customer ids. List of identifiers for the related records.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `1,2,3`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"array","description":"Item. Field in the JSON request body.\n\n**Details:** Type `array`."}},"example":[[{"235":{"id":235,"email":"aaa@gmail.com","name":"AAA","users_info_id":676,"status":1,"warehouses":[],"fulfillment_centers":[],"shipping_methods":[]},"236":{"id":236,"email":"bbbb@outlook.com","name":"BBB","users_info_id":683,"status":1,"warehouses":[],"fulfillment_centers":[],"shipping_methods":[]}}]]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/client/orderchannels":{"get":{"operationId":"clientListOrderChannels","tags":["Client"],"summary":"get order channels list","description":"Returns active channels enabled for Local Delivery orders. Channels reserved for Storage, Moving, or Shipping are excluded. When customer_id or customer_code is provided, the customer's Local Delivery channel whitelist is applied; an empty whitelist means all Local Delivery channels. Default Channel is represented by an empty order_channel_code and is allowed only when the business Default Channel Local Delivery setting is enabled and it is included in the customer's whitelist or no whitelist is configured.","parameters":[{"name":"customer_id","in":"query","required":false,"description":"Customer user ID used to apply customer-specific Local Delivery channel restrictions.\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Customer user ID used to apply customer-specific Local Delivery channel restrictions.\n\n**Details:** Optional · Type `integer`."}},{"name":"customer_code","in":"query","required":false,"description":"Customer code used to apply customer-specific Local Delivery channel restrictions.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","description":"Customer code used to apply customer-specific Local Delivery channel restrictions.\n\n**Details:** Optional · Type `string`."}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"array","description":"Item. Field in the JSON request body.\n\n**Details:** Type `array`."}},"example":[[{"id":1206,"channel_name":"ECONOMY","channel_code":"ECON","pricing_unit":1,"volumn_unit":1,"service_time":"","package_processing_time":"","pickup_time":"","package_pickup_time":"","package_calculation_rule":1,"volumetric_factor":"","tracking_number_suffix":"","display_name":{"en":"Economy","chs":"经济","es":"","fr":""},"display_order":10}]]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/client/surcharges":{"get":{"operationId":"getAvailableSurcharges","tags":["Client"],"summary":"Get available surcharges for local delivery orders","parameters":[{"name":"channel_id","in":"query","required":false,"schema":{"type":"integer","description":"Optional channel ID to filter surcharges by channel conditions\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `123`."},"description":"Optional channel ID to filter surcharges by channel conditions\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `123`.","example":123}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Surcharge ID\n\n**Details:** Type `integer`."},"code":{"type":"integer","description":"Surcharge code (same as id), used when submitting surcharges in order creation\n\n**Details:** Type `integer`."},"charge_type":{"type":"integer","description":"Charge type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"charge_type_label":{"type":"string","description":"Charge type label. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"display_type":{"type":"string","description":"Display type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."},"amount":{"type":"number","description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"unit_label":{"type":"string","description":"Unit label. Human-readable label.\n\n**Details:** Type `string`."},"is_optional":{"type":"boolean","description":"Is optional. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"pricing_config":{"type":["object","null"],"description":"Pricing config. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"options":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Index. Field in the JSON request body.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."}}},"description":"Options. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}},"example":[{"id":1,"code":1,"charge_type":1,"charge_type_label":"fixed","display_type":"checkbox","name":"Fuel Surcharge","description":"Extra fuel cost","amount":5,"unit_label":"","is_optional":true,"pricing_config":null,"options":[]},{"id":2,"code":2,"charge_type":1,"charge_type_label":"fixed","display_type":"select","name":"Insurance Level","description":"Choose insurance level","amount":0,"unit_label":"","is_optional":true,"pricing_config":null,"options":[{"index":0,"name":"Basic","price":2},{"index":1,"name":"Premium","price":10}]}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/client/orderCreate":{"post":{"tags":["Client"],"summary":"Create an order","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreate"},"examples":{"English":{"value":{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":"true/false","buzz_code":9393,"ref":"altima-4","order_code":"ABC","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20311,"dimension_unit":1,"weight_unit":1,"weight":1000,"length":300,"width":200,"height":100,"package_value":200,"insurance_value":200,"external_tracking_number":123456789,"notes":"this is a package note"}],"shipping_from":"87 (if want to manual set sender address, please leave it empty or null)","shipping_from_code":"WH-TORONTO (address book Unique Identifier; alternative to shipping_from - supply either one, shipping_from wins when both are given)","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":200,"schedule_date":"2023-02-27","time_window_start":"2023-02-27 09:00:00","time_window_end":"2023-02-27 12:00:00","pickup_date":"2023-01-27","pickup_time_window_start":"2023-01-27 00:00:00","pickup_time_window_end":"2023-01-27 10:00:00","service_time":1,"pickup_time":1,"notification_language":"en","skills":"1,2,3","latitude":43.82124,"longitude":-79.0171,"order_batch":"2021-08-23","auto_deduplication":1,"strict_duplicate_check":0,"external_customer":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"allow_dropoff":1,"pin_verification_required":1,"a_scan_at":1633073073,"sorting_code":708,"fulfillment_center_code":"WH001","surcharges":[{"surcharge_id":1,"quantity":1,"selected_option":null,"selected_options":[]},{"surcharge_id":2,"quantity":1,"selected_option":0,"selected_options":[]}]}},"address_1 + address_2":{"value":{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":true,"buzz_code":9393,"ref":"altima-4","order_code":"ABC","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20311,"dimension_unit":1,"weight_unit":1,"weight":1000,"length":300,"width":200,"height":100,"package_value":"200.00","insurance_value":"200.00","external_tracking_number":123456789,"notes":"this is a package note"}],"shipping_from":87,"shipping_from_code":"WH-TORONTO","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"(发件人地址2,如果发出地编号为空时，本字段选填）","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":"200.00","schedule_date":"2021-04-05","time_window_start":"2021-04-05 09:00:00","time_window_end":"2021-04-05 13:00:00","pickup_date":"2021-04-05","pickup_time_window_start":"2021-04-05 06:00:00","pickup_time_window_end":"2021-04-05 08:00:00","service_time":1,"pickup_service_time":1,"notification_language":"fr","skills":"1,2,3","latitude":"43.82124","longitude":"-79.0171","order_batch":"2021-08-23","auto_deduplication":1,"strict_duplicate_check":0,"external_customer (外部客户email，选填)":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"allow_dropoff":1,"pin_verification_required":1,"a_scan_at":1633073073,"sorting_code":708,"fulfillment_center_code":"WH001","surcharges":"[ {code: 1, selected_values: [1]} ] (Optional surcharges array. Each element: code (integer, required, surcharge ID from GET /v1/client/surcharges), selected_values (array, required). For checkbox: [1], for quantity: [3], for select/radio: [\"0\"] (option index), for multi_checkbox: [\"0\",\"1\"] (option indices). Invalid codes are silently ignored.)"}},"Instant Deliver":{"value":{"type":"I","order_channel_code":"SMALL","postcode":"H2X 1Z4","address_1":"200 Rue Sainte-Catherine","city":"Montreal","province":"QC","country":"Canada","name":"John Receiver","telephone":5145550200,"need_pick_up":1,"sender_name":"Shop A","sender_telephone":5145550100,"sender_address_1":"100 Rue Saint-Paul","sender_city":"Montreal","sender_province":"QC","sender_country":"Canada","time_window_start":"2026-06-08 12:00:00","time_window_end":"2026-06-08 13:00:00","packages":1,"packagesDetail":[{"weight":1000,"weight_unit":1}]}}}}},"required":true},"responses":{"200":{"headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome. The body also carries replayed: true.","schema":{"type":"string","enum":["true"]}}},"description":"successful operation Fields the business marked Mandatory under Settings → Add New Order (/setting) are required here too; a missing one is reported as a validation error (400) the same way as any other required field. When Weight or Dimension is mandatory, packagesDetail must be present and every package must carry weight / length, width and height.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"shipping_price":{"type":["number","null"],"description":"Null when the order bills by a third-party carrier cost the carrier has not quoted yet; see `warning`.\n\n**Details:** Type `number` · Nullable."},"price_details":{"type":["object","null"],"properties":{"shipping_fee":{"type":"string","description":"Shipping fee. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."}},"description":"Price details. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"tracking_number":{"type":"array","items":{"type":"string","description":"Tracking number. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Superroute or carrier tracking number.\n\n**Details:** Type `array`, items `string`."},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"warning":{"type":"string","description":"Advisory text about the created order, e.g. an unresolved fulfillment center code, or a delivery address outside the delivery area (the order was kept or held per the business setting).\n\n**Details:** Type `string`."}}},"example":{"result":true,"id":121375,"ref":"altima-4","shipping_price":6.99,"price_details":{"shipping_fee":"6.99"},"currency":"CAD","tracking_number":["SR944162425712"],"packages":[{"id":151279,"ref":20311,"tracking_number":"SR944162425712","external_tracking_number":123456789}]}}}},"400":{"description":"Bad Request. A customer with Auto Pause Local Delivery Service enabled is refused here when balance + credit does not cover the order's fee: the order is not created, nothing is charged, and the response carries `code: INSUFFICIENT_BALANCE` with the shortfall and the ways the customer can add funds. An order whose delivery address is outside the delivery area is refused with `code: OUT_OF_DELIVERY_AREA` when the business's Orders Outside the Delivery Area setting is Delete; the message says only that the address is outside the delivery area.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"code":{"type":"string","description":"`INSUFFICIENT_BALANCE` when the refusal was a balance one; `OUT_OF_DELIVERY_AREA` when the delivery address is outside the delivery area and the business setting deletes such orders.\n\n**Details:** Type `string`.","examples":["INSUFFICIENT_BALANCE"]},"insufficient_balance":{"$ref":"#/components/schemas/InsufficientBalance","description":"Insufficient balance. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `InsufficientBalance`."}}},"example":{"message":"Insufficient balance available","code":"INSUFFICIENT_BALANCE","insufficient_balance":{"msg":"Insufficient balance available","balance":7,"code":"INSUFFICIENT_BALANCE","message":"This charge is $12.00, but only $5.00 is available on your account. You are $7.00 short.","required":12,"available":5,"shortfall":7,"currency":"CAD","currency_symbol":"$","can_pay_online":true,"max_online_amount":null,"exceeds_max_online_amount":false,"channels":[{"id":"stripe:card","gateway":"stripe","method":"card","value":"card","display_name":"Credit / Debit Card","icon":"fas fa-credit-card","requires_saved_card":true}],"add_funds_url":"https://app.superroute.ca/payment/invoice?token=..."}}}}},"409":{"headers":{"Retry-After":{"description":"Present only on the 409 IDEMPOTENCY_IN_PROGRESS answer: the original request with this Idempotency-Key is still processing; retry after this many seconds.","schema":{"type":"string","examples":[1]}}},"description":"Idempotency-Key conflict","content":{"application/json":{"example":{"result":false,"code":"IDEMPOTENCY_CONFLICT","message":"Idempotency-Key was already used with a different request body"}}}}},"security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","maxLength":255,"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of creating a duplicate order. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). Absent header = exact legacy behaviour.\n\n**Details:** Optional · Type `string` · maxLength `255`."},"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of creating a duplicate order. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). Absent header = exact legacy behaviour.\n\n**Details:** Optional · Type `string` · maxLength `255`."}],"description":"Orders routed to a third-party carrier whose price plan bills by the carrier's cost (fee mode 2 or 3) are quoted with that carrier before this endpoint answers, so shipping_price is the third-party price and is what gets charged - it is not revised afterwards. The price is checked first, then the regions: if no price can be found — the rate card has no row for the address, or the carrier returns no price — AND the postcode belongs to no active region, the delivery address counts as outside the delivery area, and the response never says which carrier was asked or what it answered. An address inside an active region is never outside the delivery area; without a price it is simply left unpriced. When the business keeps such orders and shows no notice, nothing is checked at all and the order is simply created unpriced. What happens next follows the business's Orders Outside the Delivery Area setting (Settings): Keep (default) or Hold create the order — shipping_price, price_details and currency come back null and `warning` carries the out-of-area message — always for a held order, and for a kept one only when the business's Show Out-of-Delivery-Area Notice setting is on (a held order sits in Hold until an operator releases it); Delete refuses it with result: false, code OUT_OF_DELIVERY_AREA and the same message, and nothing is created or charged. If the order later leaves that carrier - returned to self delivery, the assignment cancelled, or re-routed to another carrier - it goes back to the rate card (or to the new carrier's cost) and the difference is posted as an adjustment or credit, like any other price change. A customer with Auto Pause Local Delivery Service enabled is refused when balance + credit does not cover the order's fee: the order is not created, nothing is charged, and the response carries code INSUFFICIENT_BALANCE plus an insufficient_balance block giving required, available and shortfall, the top-up channels the business has configured, and an add_funds_url. Coordinates supplied with the order (latitude/longitude) are kept as a confirmed pin that automatic geocoding never replaces unless the address itself changes. An order the auto-assignment rules route to a third-party carrier, and that is not priced by distance, is geocoded from free map sources only; the carrier receives the address text and finds the door itself."}},"/v1/orders/rate":{"post":{"tags":["Orders"],"summary":"Rate an order","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRate"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"shipping_price":{"type":"string","description":"Shipping price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"price_details":{"type":"object","properties":{"shipping_fee":{"type":"string","description":"Shipping fee. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"tax_details":{"type":"array","items":{"type":"object","properties":{"tax_number_id":{"type":"integer","description":"Tax number id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"tax_name":{"type":"string","description":"Tax name. Human-readable label.\n\n**Details:** Type `string`."},"tax_rate":{"type":"string","description":"Tax rate. Field in the JSON request body.\n\n**Details:** Type `string`."},"tax":{"type":"string","description":"Tax. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"description":"Tax details. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"tax_zone_id":{"type":"integer","description":"Tax zone id. Identifier referencing the related record.\n\n**Details:** Type `integer`."}},"description":"Price details. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"result":true,"shipping_price":"6.99","price_details":{"shipping_fee":"6.99","tax_details":[{"tax_number_id":2,"tax_name":"HST","tax_rate":"13.00","tax":"0.91"}],"tax_zone_id":3},"currency":"CAD"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v2/orders/rate":{"post":{"tags":["Orders"],"summary":"Rate an order (v2, with third-party carrier estimate)","description":"Same inputs and rate card pricing as POST /v1/orders/rate, plus: when the shipment would be routed to a third-party delivery provider with a rate API and the caller's price plan bills third-party deliveries by that carrier's cost, the carrier is asked for a live quote and the price is built from it by the plan's billing mode — the figure an order created under that plan is charged. Nothing is created or booked by this call. v1 is unchanged and keeps answering the rate card figure.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRateV2"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"shipping_price":{"type":["string","null"],"description":"Null when the shipment bills by a third-party cost and the carrier could not quote it (see warning).\n\n**Details:** Type `string|null`."},"price_details":{"type":["object","null"],"properties":{"shipping_fee":{"type":"string","description":"Shipping fee. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"tax_details":{"type":"array","items":{"type":"object","properties":{"tax_number_id":{"type":"integer","description":"Tax number id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"tax_name":{"type":"string","description":"Tax name. Human-readable label.\n\n**Details:** Type `string`."},"tax_rate":{"type":"string","description":"Tax rate. Field in the JSON request body.\n\n**Details:** Type `string`."},"tax":{"type":"string","description":"Tax. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"description":"Tax details. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"tax_zone_id":{"type":"integer","description":"Tax zone id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"sub_total":{"type":"string","description":"Pre-tax fee.\n\n**Details:** Type `string`."},"third_party_cost_plus":{"type":"object","description":"How a third-party-based fee was built. Only present when pricing_source is third_party and the carrier quoted.\n\n**Details:** Type `object`.","properties":{"mode":{"type":"integer","description":"Mode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"third_party_cost":{"type":"number","description":"Third party cost. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"cost_currency":{"type":["string","null"],"description":"Cost currency. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string|null`."},"markup_percent":{"type":"number","description":"Markup percent. Field in the JSON request body.\n\n**Details:** Type `number`."},"cost_plus_fee":{"type":"number","description":"Cost plus fee. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"rate_card_fee":{"type":["number","null"],"description":"The rate card fee that was compared against (mode 3), null when the postcode has no rate card row.\n\n**Details:** Type `number|null`."},"provider_id":{"type":["integer","null"],"description":"Provider id. Identifier referencing the related record.\n\n**Details:** Type `integer|null`."},"source":{"type":"string","enum":["rate_estimate"],"description":"Document or data source selector for this developer-center export.\n\nAllowed values: `rate_estimate`.\n\n**Details:** Type `string`."},"package_count":{"type":["integer","null"],"description":"Package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer|null`."}}}},"description":"Price details. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object|null`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"pricing_source":{"type":"string","enum":["rate_card","third_party"],"description":"Where the price came from.\n\nAllowed values: `rate_card` · `third_party`.\n\n**Details:** Type `string`."},"third_party":{"type":["object","null"],"description":"Present when a third-party carrier was consulted and quoted, i.e. a rule routes this shipment to a carrier with a rate API and the payer's price plan bills by that carrier's cost (cost + markup, or the higher of that and the rate card). Absent when the shipment prices off the rate card, and absent when no price can be found (no rate card row for the address, or the carrier returns no price): that answer is `result: false` with `code: OUT_OF_DELIVERY_AREA` and says nothing about the carrier.\n\n**Details:** Type `object|null`.","properties":{"provider_id":{"type":"integer","description":"Provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"provider_name":{"type":"string","description":"Provider name. Human-readable label.\n\n**Details:** Type `string`."},"quoted":{"type":"boolean","description":"The carrier returned a price. When false, shipping_price is null and warning explains why.\n\n**Details:** Type `boolean`."},"cost":{"type":["string","null"],"description":"The carrier's own price, before markup, in cost_currency.\n\n**Details:** Type `string|null`."},"cost_currency":{"type":["string","null"],"description":"Cost currency. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string|null`."},"mode":{"type":"integer","enum":[2,3],"description":"Billing mode from the payer's price plan. 2: third-party cost + markup; 3: the higher of the rate card fee and cost + markup.\n\nAllowed values: `2` · `3`.\n\n**Details:** Type `integer`."},"markup_percent":{"type":"number","description":"Markup percent. Field in the JSON request body.\n\n**Details:** Type `number`."},"warning":{"type":["string","null"],"description":"Warning. Field in the JSON request body.\n\n**Details:** Type `string|null`."}}},"warning":{"type":["string","null"],"description":"Set when the shipment bills by a third-party cost but the carrier could not quote it. The shipment is then returned without a price — exactly as an order created under that plan would be — rather than with a rate card figure the carrier would contradict.\n\n**Details:** Type `string|null`."}}},"examples":{"rateCard":{"summary":"Priced off the rate card (no third-party carrier involved)","value":{"result":true,"shipping_price":"6.99","price_details":{"shipping_fee":"6.99","sub_total":"6.18","tax_details":[{"tax_number_id":2,"tax_name":"HST","tax_rate":"13.00","tax":"0.81"}],"tax_zone_id":3},"currency":"CAD","pricing_source":"rate_card"}},"thirdPartyQuoted":{"summary":"Third-party carrier quoted; billed at cost + 15%","value":{"result":true,"shipping_price":"14.60","price_details":{"shipping_fee":12.92,"sub_total":"12.92","third_party_cost_plus":{"mode":2,"third_party_cost":11.23,"cost_currency":"CAD","markup_percent":15,"cost_plus_fee":12.92,"rate_card_fee":9.5,"assignment_id":null,"provider_id":42,"source":"rate_estimate","package_count":1},"tax_details":[{"tax_number_id":2,"tax_name":"HST","tax_rate":"13.00","tax":"1.68"}],"tax_zone_id":3},"currency":"CAD","pricing_source":"third_party","third_party":{"provider_id":42,"provider_name":"Intelcom","quoted":true,"cost":"11.23","cost_currency":"CAD","mode":2,"markup_percent":15,"warning":null}}},"outOfDeliveryArea":{"summary":"The carrier returned no price — the address is outside the delivery area","value":{"result":false,"shipping_price":null,"price_details":null,"currency":null,"code":"OUT_OF_DELIVERY_AREA","message":"The delivery address is outside the delivery area.","warning":"The delivery address is outside the delivery area."}}}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/client/batchOrderCreate":{"post":{"tags":["Client"],"summary":"Batch Create orders","description":"Optional top-level flag per_order_transaction=1 commits each order independently, so one order's failure cannot roll back the others (a terminal error row with batch_aborted=true is appended if processing stops early); default keeps the legacy single-transaction batch. Batches over 100 orders receive an advisory X-Batch-Size-Warning response header — prefer /v1/client/batchOrderCreateAsync for large batches.\n\nOrders routed to a third-party carrier whose price plan bills by the carrier's cost (fee mode 2 or 3) are quoted with that carrier before this endpoint answers, so shipping_price is the third-party price and is what gets charged - it is not revised afterwards. The price is checked first, then the regions: if no price can be found — the rate card has no row for the address, or the carrier returns no price — AND the postcode belongs to no active region, the delivery address counts as outside the delivery area, and the response never says which carrier was asked or what it answered. An address inside an active region is never outside the delivery area; without a price it is simply left unpriced. When the business keeps such orders and shows no notice, nothing is checked at all and the order is simply created unpriced. What happens next follows the business's Orders Outside the Delivery Area setting (Settings): Keep (default) or Hold create the order — shipping_price, price_details and currency come back null and `warning` carries the out-of-area message — always for a held order, and for a kept one only when the business's Show Out-of-Delivery-Area Notice setting is on (a held order sits in Hold until an operator releases it); Delete refuses it with result: false, code OUT_OF_DELIVERY_AREA and the same message, and nothing is created or charged. In a batch these orders are quoted after the batch is committed. If the order later leaves that carrier - returned to self delivery, the assignment cancelled, or re-routed to another carrier - it goes back to the rate card (or to the new carrier's cost) and the difference is posted as an adjustment or credit, like any other price change. Fields the business marked Mandatory under Settings → Add New Order (/setting) are required per order; an order missing one is returned with result=false and the field in message, like any other validation failure, and the rest of the batch still proceeds. Rows refused by the prepaid gate (Auto Pause Local Delivery Service, when balance + credit does not cover the fee) come back as result: false with code INSUFFICIENT_BALANCE and an insufficient_balance block; those orders are not created and nothing is charged for them. The rest of the batch is unaffected. Coordinates supplied with the order (latitude/longitude) are kept as a confirmed pin that automatic geocoding never replaces unless the address itself changes. An order the auto-assignment rules route to a third-party carrier, and that is not priced by distance, is geocoded from free map sources only; the carrier receives the address text and finds the door itself.","parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","maxLength":255,"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of creating the batch a second time. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). A non-200 outcome releases the key, so a rejected request can be fixed and retried with it. Absent header = exact legacy behaviour. Keys are scoped per user and per endpoint.\n\n**Details:** Optional · Type `string` · maxLength `255`."},"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of creating the batch a second time. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). A non-200 outcome releases the key, so a rejected request can be fixed and retried with it. Absent header = exact legacy behaviour. Keys are scoped per user and per endpoint.\n\n**Details:** Optional · Type `string` · maxLength `255`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchOrderCreate"},"examples":{"English":{"value":{"orders":[{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":"true/false","buzz_code":9393,"ref":"b-4","order_code":"ABC","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20311,"weight":1000,"length":300,"width":200,"height":100,"dimension_unit":1,"weight_unit":1,"package_value":200,"insurance_value":200,"external_tracking_number":123456789,"notes":"this is a package note"}],"allow_dropoff":1,"pin_verification_required":1,"shipping_from":"87 (if want to manual set sender address, please leave it empty or null)","shipping_from_code":"WH-TORONTO (address book Unique Identifier; alternative to shipping_from - supply either one, shipping_from wins when both are given)","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":200,"schedule_date":"2023-02-27","time_window_start":"2023-02-27 09:00:00","time_window_end":"2023-02-27 12:00:00","pickup_date":"2023-01-27","pickup_time_window_start":"2023-01-27 00:00:00","pickup_time_window_end":"2023-01-27 10:00:00","service_time":1,"pickup_time":1,"notification_language":"en","skills":"1,2,3","latitude":43.82124,"longitude":-79.0171,"order_batch":"2021-08-23","auto_deduplication":1,"external_customer":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"a_scan_at":1633073073,"sorting_code":708,"fulfillment_center_code":"WH001","surcharges":[{"code":1,"selected_values":[1]},{"code":2,"selected_values":[0]}]},{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":"true/false","buzz_code":9393,"ref":"c-4","order_code":"ABC","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20312,"weight":1000,"length":300,"width":200,"height":100,"dimension_unit":1,"weight_unit":1,"package_value":200,"insurance_value":200,"external_tracking_number":123456789,"notes":"this is a package note"}],"allow_dropoff":1,"pin_verification_required":1,"shipping_from":"87 (if want to manual set sender address, please leave it empty or null)","shipping_from_code":"WH-TORONTO (address book Unique Identifier; alternative to shipping_from - supply either one, shipping_from wins when both are given)","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":200,"schedule_date":"2023-02-27","time_window_start":"2023-02-27 09:00:00","time_window_end":"2023-02-27 12:00:00","pickup_date":"2023-01-27","pickup_time_window_start":"2023-01-27 00:00:00","pickup_time_window_end":"2023-01-27 10:00:00","service_time":1,"pickup_time":1,"notification_language":"en","skills":"1,2,3","latitude":43.82124,"longitude":-79.0171,"order_batch":"2021-08-23","auto_deduplication":1,"external_customer":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"a_scan_at":1633073073,"sorting_code":708,"fulfillment_center_code":"WH001"}]}},"address_1 + address_2":{"value":{"orders":[{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":true,"buzz_code":9393,"ref":"altima-4","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20311,"weight":1000,"length":300,"width":200,"height":100,"dimension_unit":1,"weight_unit":1,"package_value":"200.00","insurance_value":"200.00","external_tracking_number":123456789,"notes":"this is a package note"}],"allow_dropoff":1,"pin_verification_required":1,"shipping_from":87,"shipping_from_code":"WH-TORONTO","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"(发件人地址2,如果发出地编号为空时，本字段选填）","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":"200.00","schedule_date":"2021-04-05","time_window_start":"2021-04-05 09:00:00","time_window_end":"2021-04-05 13:00:00","pickup_date":"2021-04-05","pickup_time_window_start":"2021-04-05 06:00:00","pickup_time_window_end":"2021-04-05 08:00:00","service_time":1,"pickup_service_time":1,"notification_language":"fr","skills":"1,2,3","latitude":"43.82124","longitude":"-79.0171","order_batch":"2021-08-23","auto_deduplication":1,"external_customer (外部客户，选填)":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"a_scan_at":1633073073,"sorting_code":708,"fulfillment_center_code":"WH001"},{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":true,"buzz_code":9393,"ref":"altima-4","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20312,"weight":1000,"length":300,"width":200,"height":100,"dimension_unit":1,"weight_unit":1,"package_value":"200.00","insurance_value":"200.00","external_tracking_number":123456789,"notes":"this is a package note"}],"allow_dropoff":1,"pin_verification_required":1,"shipping_from":87,"shipping_from_code":"WH-TORONTO","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"(发件人地址2,如果发出地编号为空时，本字段选填）","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":"200.00","schedule_date":"2021-04-05","time_window_start":"2021-04-05 09:00:00","time_window_end":"2021-04-05 13:00:00","pickup_date":"2021-04-05","pickup_time_window_start":"2021-04-05 06:00:00","pickup_time_window_end":"2021-04-05 08:00:00","service_time":1,"pickup_service_time":1,"notification_language":"fr","skills":"1,2,3","latitude":"43.82124","longitude":"-79.0171","order_batch":"2021-08-23","auto_deduplication":1,"external_customer (外部客户，选填)":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"a_scan_at":1633073073,"sorting_code":708,"fulfillment_center_code":"WH001"}]}}}}},"required":true},"responses":{"200":{"headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome. The body also carries replayed: true.","schema":{"type":"string","enum":["true"]}}},"description":"successful operation Rows refused by the prepaid gate (Auto Pause Local Delivery Service, when balance + credit does not cover the fee) come back as `result: false` with `code: INSUFFICIENT_BALANCE` and an `insufficient_balance` block; those orders are not created and nothing is charged for them. The rest of the batch is unaffected. Rows whose delivery address is outside the delivery area come back as `result: false` with `code: OUT_OF_DELIVERY_AREA` when the business's Orders Outside the Delivery Area setting is Delete (with Keep or Hold the row is created; `warning` carries the out-of-area message always for a held row, and for a kept one only when the business's Show Out-of-Delivery-Area Notice setting is on).","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"shipping_price":{"type":["number","null"],"description":"Null when the order bills by a third-party carrier cost the carrier has not quoted yet; see `warning`.\n\n**Details:** Type `number` · Nullable."},"price_details":{"type":["object","null"],"properties":{"shipping_fee":{"type":"string","description":"Shipping fee. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."}},"description":"Price details. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"tracking_number":{"type":"array","items":{"type":"string","description":"Tracking number. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Superroute or carrier tracking number.\n\n**Details:** Type `array`, items `string`."},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"warning":{"type":"string","description":"Advisory text about the created order, e.g. an unresolved fulfillment center code, or a delivery address outside the delivery area (the order was kept or held per the business setting).\n\n**Details:** Type `string`."}}}},"example":[{"result":true,"id":121380,"ref":"b-4","shipping_price":6.99,"price_details":{"shipping_fee":"6.99"},"currency":"CAD","tracking_number":["SR319377023615"],"packages":[{"id":151284,"ref":20311,"tracking_number":"SR319377023615","external_tracking_number":123456789}]},{"result":false,"message":"Customer not found","skipped_ref":"a-4"},{"result":false,"message":{"postcode":["The postcode field is required."]},"skipped_ref":"c-4"},{"result":false,"message":"shipping from address not found.","skipped_ref":"e-4"},{"result":false,"message":"'Duplicate external pacakge ref or external tracking number","skipped_ref":"d-4","skipped_package_ref":[20312],"exist_package_ref":{"20312":{"tracking_number":"SR904227449186","external_tracking_number":123456789}},"skipped_external_tracking_number":[],"exist_external_tracking_number":{"123456789":{"tracking_number":"SR904227449186","package_ref":20311}}}]}}},"400":{"description":"Bad Request"},"409":{"headers":{"Retry-After":{"description":"Present only on the 409 IDEMPOTENCY_IN_PROGRESS answer: the original request with this Idempotency-Key is still processing; retry after this many seconds.","schema":{"type":"string","examples":[1]}}},"description":"Idempotency-Key conflict","content":{"application/json":{"example":{"result":false,"code":"IDEMPOTENCY_CONFLICT","message":"Idempotency-Key was already used with a different request body"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/client/batchOrderCreateAsync":{"post":{"tags":["Client"],"summary":"Batch Create orders","parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","maxLength":255,"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of queueing the batch a second time. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). A non-200 outcome releases the key, so a rejected request can be fixed and retried with it. Absent header = exact legacy behaviour. Keys are scoped per user and per endpoint.\n\n**Details:** Optional · Type `string` · maxLength `255`."},"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of queueing the batch a second time. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). A non-200 outcome releases the key, so a rejected request can be fixed and retried with it. Absent header = exact legacy behaviour. Keys are scoped per user and per endpoint.\n\n**Details:** Optional · Type `string` · maxLength `255`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchOrderCreate"},"examples":{"English":{"value":{"orders":[{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":"true/false","buzz_code":9393,"ref":"b-4","order_code":"ABC","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20311,"dimension_unit":1,"weight_unit":1,"weight":1000,"length":300,"width":200,"height":100,"package_value":200,"insurance_value":200,"external_tracking_number":123456789,"notes":"this is a package note","items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description Fields the business marked Mandatory under Settings → Add New Order (/setting) are required per order; an order missing one is returned with result=false and the field in message, like any other validation failure, and the rest of the batch still proceeds."}]}],"allow_dropoff":1,"pin_verification_required":1,"shipping_from":"87 (if want to manual set sender address, please leave it empty or null)","shipping_from_code":"WH-TORONTO (address book Unique Identifier; alternative to shipping_from - supply either one, shipping_from wins when both are given)","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":200,"schedule_date":"2021-04-05 00:00:00","time_window_start":"2021-04-05 09:00:00","time_window_end":"2021-04-05 13:00:00.00","pickup_date":"2021-04-05 00:00:00.00","pickup_time_window_start":"2021-04-05 06:00:00","pickup_time_window_end":"2021-04-05 08:00:00","service_time":1,"pickup_service_time":1,"notification_language":"en","skills":"1,2,3","latitude":43.82124,"longitude":-79.0171,"order_batch":"2021-08-23","auto_deduplication":1,"external_customer":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"a_scan_at":1633073073,"sorting_code":708,"carriers":["usps"],"services":["usps_priority_mail","usps_priority_mail_express"],"paid_by":2,"account_number":123456789,"account_country":"US","account_postcode":12001,"package_type":"parcel","fulfillment_center_code":"WH001"},{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":"true/false","buzz_code":9393,"ref":"c-4","order_code":"ABC","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20312,"dimension_unit":1,"weight_unit":1,"weight":1000,"length":300,"width":200,"height":100,"package_value":200,"insurance_value":200,"external_tracking_number":123456789,"notes":"this is a package note","items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}]}],"allow_dropoff":1,"pin_verification_required":1,"shipping_from":"87 (if want to manual set sender address, please leave it empty or null)","shipping_from_code":"WH-TORONTO (address book Unique Identifier; alternative to shipping_from - supply either one, shipping_from wins when both are given)","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":200,"schedule_date":"2021-04-05 00:00:00","time_window_start":"2021-04-05 09:00:00","time_window_end":"2021-04-05 13:00:00.00","pickup_date":"2021-04-05 00:00:00.00","pickup_time_window_start":"2021-04-05 06:00:00","pickup_time_window_end":"2021-04-05 08:00:00","service_time":1,"pickup_service_time":1,"notification_language":"en","skills":"1,2,3","latitude":43.82124,"longitude":-79.0171,"order_batch":"2021-08-23","auto_deduplication":1,"external_customer":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"a_scan_at":1633073073,"sorting_code":708,"carriers":["usps"],"services":["usps_priority_mail","usps_priority_mail_express"],"paid_by":2,"account_number":123456789,"account_country":"US","account_postcode":12001,"package_type":"parcel","fulfillment_center_code":"WH001"}]}},"address_1 + address_2":{"value":{"orders":[{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":true,"buzz_code":9393,"ref":"altima-4","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20311,"dimension_unit":1,"weight_unit":1,"weight":1000,"length":300,"width":200,"height":100,"package_value":"200.00","insurance_value":"200.00","external_tracking_number":123456789,"notes":"this is a package note","items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}]}],"allow_dropoff":1,"pin_verification_required":1,"shipping_from":87,"shipping_from_code":"WH-TORONTO","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"(发件人地址2,如果发出地编号为空时，本字段选填）","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":"200.00","schedule_date":"2021-04-05","time_window_start":"2021-04-05 09:00:00","time_window_end":"2021-04-05 13:00:00","pickup_date":"2021-04-05 00:00:00","pickup_time_window_start":"2021-04-05 06:00:00","pickup_time_window_end":"2021-04-05 08:00:00","service_time":1,"pickup_service_time":1,"notification_language":"fr","skills":"1,2,3","latitude":"43.82124","longitude":"-79.0171","order_batch":"2021-08-23","auto_deduplication":1,"external_customer (外部客户，选填)":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"a_scan_at":1633073073,"sorting_code":708,"fulfillment_center_code":"WH001","shipping_method":2,"carriers":["usps"],"services":["usps_priority_mail","usps_priority_mail_express"],"paid_by":2,"account_number":123456789,"account_country":"US","account_postcode":12001,"package_type":"parcel"},{"type":"D","order_channel_code":"SMALL","self_pickup":0,"customer_id":null,"customer_code":null,"postcode":"H9S2H9","address_1":"2667 boul des sources","address_2":123,"combine_address":true,"buzz_code":9393,"ref":"altima-4","city":"pointe-claire","province":"QC","country":"Canada","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"need_pick_up":1,"packages":1,"packagesDetail":[{"ref":20312,"dimension_unit":1,"weight_unit":1,"weight":1000,"length":300,"width":200,"height":100,"package_value":"200.00","insurance_value":"200.00","external_tracking_number":123456789,"notes":"this is a package note","items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}]}],"allow_dropoff":1,"pin_verification_required":1,"shipping_from":87,"shipping_from_code":"WH-TORONTO","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"(发件人地址2,如果发出地编号为空时，本字段选填）","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"pickup_instruction":"pickup instructions","delivery_instruction":"delivery instructions","note":"customer note","signature_option":1,"insurance_option":1,"insurance_value":"200.00","schedule_date":"2021-04-05","time_window_start":"2021-04-05 09:00:00","time_window_end":"2021-04-05 13:00:00","service_time":1,"notification_language":"fr","skills":"1,2,3","latitude":"43.82124","longitude":"-79.0171","order_batch":"2021-08-23","auto_deduplication":1,"external_customer (外部客户，选填)":{"id":11,"name":"test","email":"external_customer@test.com","system_code":"es1"},"a_scan_at":1633073073,"sorting_code":708,"fulfillment_center_code":"WH001","shipping_method":2,"carriers":["usps"],"services":["usps_priority_mail","usps_priority_mail_express"],"paid_by":2,"account_number":123456789,"account_country":"US","account_postcode":12001,"package_type":"parcel"}]}}}}},"required":true},"responses":{"200":{"headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome. The body also carries replayed: true.","schema":{"type":"string","enum":["true"]}}},"description":"successful operation Rows refused by the prepaid gate (Auto Pause Local Delivery Service, when balance + credit does not cover the fee) come back as `result: false` with `code: INSUFFICIENT_BALANCE` and an `insufficient_balance` block; those orders are not created and nothing is charged for them. The rest of the batch is unaffected. Rows whose delivery address is outside the delivery area come back as `result: false` with `code: OUT_OF_DELIVERY_AREA` when the business's Orders Outside the Delivery Area setting is Delete (with Keep or Hold the row is created; `warning` carries the out-of-area message always for a held row, and for a kept one only when the business's Show Out-of-Delivery-Area Notice setting is on).","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"asyncId":{"type":"integer","description":"Async id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"warning":{"type":"string","description":"Advisory text about the created order, e.g. an unresolved fulfillment center code, or a delivery address outside the delivery area (the order was kept or held per the business setting).\n\n**Details:** Type `string`."}}},"example":{"message":"Order batch created in async,please check later.","asyncId":28}}}},"400":{"description":"Bad Request"},"409":{"headers":{"Retry-After":{"description":"Present only on the 409 IDEMPOTENCY_IN_PROGRESS answer: the original request with this Idempotency-Key is still processing; retry after this many seconds.","schema":{"type":"string","examples":[1]}}},"description":"Idempotency-Key conflict","content":{"application/json":{"example":{"result":false,"code":"IDEMPOTENCY_CONFLICT","message":"Idempotency-Key was already used with a different request body"}}}}},"security":[{"bearerAuth":[]}],"description":"Orders routed to a third-party carrier whose price plan bills by the carrier's cost (fee mode 2 or 3) are quoted with that carrier before this endpoint answers, so shipping_price is the third-party price and is what gets charged - it is not revised afterwards. The price is checked first, then the regions: if no price can be found — the rate card has no row for the address, or the carrier returns no price — AND the postcode belongs to no active region, the delivery address counts as outside the delivery area, and the response never says which carrier was asked or what it answered. An address inside an active region is never outside the delivery area; without a price it is simply left unpriced. When the business keeps such orders and shows no notice, nothing is checked at all and the order is simply created unpriced. What happens next follows the business's Orders Outside the Delivery Area setting (Settings): Keep (default) or Hold create the order — shipping_price, price_details and currency come back null and `warning` carries the out-of-area message — always for a held order, and for a kept one only when the business's Show Out-of-Delivery-Area Notice setting is on (a held order sits in Hold until an operator releases it); Delete refuses it with result: false, code OUT_OF_DELIVERY_AREA and the same message, and nothing is created or charged. If the order later leaves that carrier - returned to self delivery, the assignment cancelled, or re-routed to another carrier - it goes back to the rate card (or to the new carrier's cost) and the difference is posted as an adjustment or credit, like any other price change. Rows refused by the prepaid gate (Auto Pause Local Delivery Service, when balance + credit does not cover the fee) come back as result: false with code INSUFFICIENT_BALANCE and an insufficient_balance block; those orders are not created and nothing is charged for them. The rest of the batch is unaffected. Coordinates supplied with the order (latitude/longitude) are kept as a confirmed pin that automatic geocoding never replaces unless the address itself changes. An order the auto-assignment rules route to a third-party carrier, and that is not priced by distance, is geocoded from free map sources only; the carrier receives the address text and finds the door itself."}},"/v1/client/async/{id}":{"get":{"tags":["Client"],"summary":"Get async result by id","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_number":{"type":"array","items":{"type":"string","description":"Tracking number. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Superroute or carrier tracking number.\n\n**Details:** Type `array`, items `string`."},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."}}}},"example":[{"result":true,"id":121380,"ref":"b-4","tracking_number":["SR319377023615"],"packages":[{"id":151284,"ref":20311,"tracking_number":"SR319377023615","external_tracking_number":123456789}]},{"result":false,"message":"Customer not found","skipped_ref":"a-4"},{"result":false,"message":{"postcode":["The postcode field is required."]},"skipped_ref":"c-4"},{"result":false,"message":"shipping from address not found.","skipped_ref":"e-4"},{"result":false,"message":"'Duplicate external pacakge ref or external tracking number","skipped_ref":"d-4","skipped_package_ref":[20312],"skipped_external_tracking_number":[]}]}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/labelservice/rate":{"post":{"tags":["LabelService"],"summary":"get rate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelServiceOrder"},"examples":{"English - address_1 + address_2":{"value":{"postcode":"H4E3R3","address_1":"6701 RUE HADLEY","address_2":123,"address_type":1,"combine_address":true,"buzz_code":9393,"ref":"API001","city":"Montreal","province":"QC","country":"CA","name":"John","company_name":"HELLO WORLD","email":"join@gmail.com","telephone":5555555555,"note":"customer note","weight":1,"length":1,"width":1,"height":1,"dimension_unit":1,"weight_unit":1,"signature_option":1,"insurance_option":1,"package_value":200,"insurance_value":200,"package_ref":20311,"package_note":"Package Note","items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}],"packages":[{"ref":20311,"weight":1000,"length":300,"width":200,"height":100,"dimension_unit":1,"weight_unit":1,"package_value":200,"insurance_value":200,"external_tracking_number":123456789,"items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}]}],"schedule_date":"2021-04-05 00:00:00","notification_language":"en","shipping_from":"87 (if want to manual set sender address, please leave it empty or null)","shipping_from_code":"WH-TORONTO (address book Unique Identifier; alternative to shipping_from - supply either one, shipping_from wins when both are given)","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"shipping_method":59,"paid_by":2,"account_number":123456789,"account_country":"US","account_postcode":12001,"package_type":"parcel","order_batch":"2021-08-23","external_order_id":123456789}},"address_1 + address_2":{"value":{"postcode":92660,"address_1":"3100 Irvine Ave","address_2":123,"address_type":1,"combine_address":true,"buzz_code":9393,"ref":"US001","city":"NEWPORT BEACH","province":"CA","country":"US","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"note":"customer note","weight":1,"length":1,"width":1,"height":1,"dimension_unit":1,"weight_unit":1,"signature_option":1,"insurance_option":1,"package_value":"200.00","insurance_value":"200.00","package_ref":20311,"package_note":"Package Note","items":[{"name":"Product 1","quantity":1,"unit_price":"1.48","origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}],"packages":[{"ref":20311,"weight":1000,"length":300,"width":200,"height":100,"dimension_unit":1,"weight_unit":1,"insurance_value":"200.00","external_tracking_number":123456789,"items":[{"name":"Product 1","quantity":1,"unit_price":"1.48","origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}]}],"schedule_date":"2021-04-05","notification_language":"fr","shipping_from":87,"shipping_from_code":"WH-TORONTO","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"(发件人地址2,如果发出地编号为空时，本字段选填）","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"shipping_method":2,"paid_by":2,"account_number":123456789,"account_country":"US","account_postcode":12001,"package_type":"parcel","order_batch":"2021-08-23","external_order_id":123456789}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"shipping_price":{"type":"string","description":"Shipping price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"price_details":{"type":"object","properties":{"shipping_fee":{"type":"string","description":"Shipping fee. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."}},"description":"Price details. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"rates":{"type":"array","items":{"type":"object","properties":{"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"carrier_id":{"type":"string","description":"Carrier id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."},"service_name":{"type":"string","description":"Service name. Human-readable label.\n\n**Details:** Type `string`."},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"price_detail":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"amount":{"type":"number","description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"description":"Price detail. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `array`, items `object`."},"transit_days":{"type":"integer","description":"Transit days. Field in the JSON request body.\n\n**Details:** Type `integer`."},"test_mode":{"type":"boolean","description":"Test mode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `boolean`."}}},"description":"Rates. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"best_rate":{"type":"object","properties":{"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"carrier_id":{"type":"string","description":"Carrier id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."},"service_name":{"type":"string","description":"Service name. Human-readable label.\n\n**Details:** Type `string`."},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"price_detail":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"amount":{"type":"number","description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"description":"Price detail. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `array`, items `object`."},"transit_days":{"type":"integer","description":"Transit days. Field in the JSON request body.\n\n**Details:** Type `integer`."},"test_mode":{"type":"boolean","description":"Test mode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `boolean`."}},"description":"Best rate. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"id":89722,"shipping_price":"15.18","price_details":{"shipping_fee":"15.18"},"rates":[{"carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_expedited_parcel","service_name":"CANADAPOST EXPEDITED PARCEL","price":15.18,"price_detail":[{"name":"Base charge","amount":10.27,"currency":"CAD"},{"name":"GST","amount":0.66,"currency":"CAD"},{"name":"PST","amount":1.32,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":2.93,"currency":"CAD"}],"transit_days":1,"test_mode":true},{"carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_regular_parcel","service_name":"CANADAPOST REGULAR PARCEL","price":15.18,"price_detail":[{"name":"Base charge","amount":10.27,"currency":"CAD"},{"name":"GST","amount":0.66,"currency":"CAD"},{"name":"PST","amount":1.32,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":2.93,"currency":"CAD"}],"transit_days":2,"test_mode":true},{"carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_xpresspost","service_name":"CANADAPOST XPRESSPOST","price":16.73,"price_detail":[{"name":"Base charge","amount":11.32,"currency":"CAD"},{"name":"GST","amount":0.73,"currency":"CAD"},{"name":"PST","amount":1.45,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":3.23,"currency":"CAD"}],"transit_days":1,"test_mode":true},{"carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_priority","service_name":"CANADAPOST PRIORITY","price":31.67,"price_detail":[{"name":"Base charge","amount":21.43,"currency":"CAD"},{"name":"GST","amount":1.38,"currency":"CAD"},{"name":"PST","amount":2.75,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":6.11,"currency":"CAD"}],"transit_days":1,"test_mode":true}],"best_rate":{"carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_expedited_parcel","service_name":"CANADAPOST EXPEDITED PARCEL","price":15.18,"price_detail":[{"name":"Base charge","amount":10.27,"currency":"CAD"},{"name":"GST","amount":0.66,"currency":"CAD"},{"name":"PST","amount":1.32,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":2.93,"currency":"CAD"}],"transit_days":1,"test_mode":true}}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/labelservice/submitOrder":{"post":{"tags":["LabelService"],"summary":"submit a new label order","parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","maxLength":255,"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of buying a second label. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). A non-200 outcome releases the key, so a rejected request can be fixed and retried with it. Absent header = exact legacy behaviour. Keys are scoped per user and per endpoint.\n\n**Details:** Optional · Type `string` · maxLength `255`."},"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of buying a second label. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). A non-200 outcome releases the key, so a rejected request can be fixed and retried with it. Absent header = exact legacy behaviour. Keys are scoped per user and per endpoint.\n\n**Details:** Optional · Type `string` · maxLength `255`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelServiceOrder"},"examples":{"English - address_1 + address_2":{"value":{"postcode":92660,"address_1":"3100 Irvine Ave","address_2":123,"address_type":1,"combine_address":true,"buzz_code":9393,"ref":"API001","order_code":"ABC","city":"Newport Beach","province":"CA","country":"US","name":"John","company_name":"HELLO WORLD","email":"join@gmail.com","telephone":5555555555,"note":"customer note","weight":1,"length":1,"width":1,"height":1,"dimension_unit":1,"weight_unit":1,"signature_option":1,"insurance_option":1,"package_value":200,"insurance_value":200,"package_ref":20311,"package_note":"Package Note","items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}],"packages":[{"ref":20311,"weight":1000,"length":300,"width":200,"height":100,"dimension_unit":1,"weight_unit":1,"package_value":200,"insurance_value":200,"external_tracking_number":123456789,"items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}]}],"export_reason":1,"schedule_date":"2021-04-05 00:00:00","notification_language":"en","shipping_from":"87 (if want to manual set sender address, please leave it empty or null)","shipping_from_code":"WH-TORONTO (address book Unique Identifier; alternative to shipping_from - supply either one, shipping_from wins when both are given)","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"shipping_method":2,"paid_by":2,"account_number":123456789,"account_country":"US","account_postcode":12001,"package_type":"parcel","order_batch":"2021-08-23","external_order_id":123456789,"auto_deduplication":1,"related_order_type":1,"related_order_id":12345,"carriers":["usps"],"services":["usps_priority_mail","usps_priority_mail_express"]}},"address_1 + address_2":{"value":{"postcode":92660,"address_1":"3100 Irvine Ave","address_2":123,"address_type":1,"combine_address":true,"buzz_code":9393,"ref":"US001","order_code":"ABC","city":"NEWPORT BEACH","province":"CA","country":"US","name":"John","company_name":"Super Route","email":"join@gmail.com","telephone":5555555555,"note":"customer note","weight":1,"length":1,"width":1,"height":1,"dimension_unit":1,"weight_unit":1,"signature_option":1,"insurance_option":1,"package_value":"200.00","insurance_value":"200.00","package_ref":20311,"package_note":"Package Note","items":[{"name":"Product 1","quantity":1,"unit_price":"1.48","origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}],"packages":[{"ref":20311,"weight":1000,"length":300,"width":200,"height":100,"dimension_unit":1,"weight_unit":1,"insurance_value":"200.00","external_tracking_number":123456789,"items":[{"name":"Product 1","quantity":1,"unit_price":"1.48","origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1231231243,"hscode":8009201332,"description":"Product 1 description"}]}],"export_reason":1,"schedule_date":"2021-04-05","notification_language":"fr","shipping_from":87,"shipping_from_code":"WH-TORONTO","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"(发件人地址2,如果发出地编号为空时，本字段选填）","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"shipping_method":2,"paid_by":2,"account_number":123456789,"account_country":"US","account_postcode":12001,"package_type":"parcel","order_batch":"2021-08-23","external_order_id":123456789,"auto_deduplication":1,"related_order_type":1,"related_order_id":12345,"carriers":["usps"],"services":["usps_priority_mail","usps_priority_mail_express"]}}}}},"required":true},"responses":{"200":{"headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome. The body also carries replayed: true.","schema":{"type":"string","enum":["true"]}}},"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"shipping_price":{"type":"string","description":"Shipping price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"price_details":{"type":"object","properties":{"shipping_fee":{"type":"string","description":"Shipping fee. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."}},"description":"Price details. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"rates":{"type":"array","items":{"type":"object","properties":{"rate_id":{"type":"string","description":"Rate id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"carrier_id":{"type":"string","description":"Carrier id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."},"service_name":{"type":"string","description":"Service name. Human-readable label.\n\n**Details:** Type `string`."},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"price_detail":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"amount":{"type":"number","description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"description":"Price detail. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `array`, items `object`."},"transit_days":{"type":"integer","description":"Transit days. Field in the JSON request body.\n\n**Details:** Type `integer`."},"test_mode":{"type":"boolean","description":"Test mode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `boolean`."}}},"description":"Rates. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"best_rate":{"type":"object","properties":{"rate_id":{"type":"string","description":"Rate id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"carrier_id":{"type":"string","description":"Carrier id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."},"service_name":{"type":"string","description":"Service name. Human-readable label.\n\n**Details:** Type `string`."},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"price_detail":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"amount":{"type":"number","description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"description":"Price detail. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `array`, items `object`."},"transit_days":{"type":"integer","description":"Transit days. Field in the JSON request body.\n\n**Details:** Type `integer`."},"test_mode":{"type":"boolean","description":"Test mode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `boolean`."}},"description":"Best rate. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"id":89722,"shipping_price":"15.18","price_details":{"shipping_fee":"15.18"},"rates":[{"rate_id":"rat_ddc7d8b277e745bab4c3fb66acadd490","carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_expedited_parcel","service_name":"CANADAPOST EXPEDITED PARCEL","price":15.18,"price_detail":[{"name":"Base charge","amount":10.27,"currency":"CAD"},{"name":"GST","amount":0.66,"currency":"CAD"},{"name":"PST","amount":1.32,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":2.93,"currency":"CAD"}],"transit_days":1,"test_mode":true},{"rate_id":"rat_ddc7d8b277e745bab4c3fb66acadd491","carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_regular_parcel","service_name":"CANADAPOST REGULAR PARCEL","price":15.18,"price_detail":[{"name":"Base charge","amount":10.27,"currency":"CAD"},{"name":"GST","amount":0.66,"currency":"CAD"},{"name":"PST","amount":1.32,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":2.93,"currency":"CAD"}],"transit_days":2,"test_mode":true},{"rate_id":"rat_ddc7d8b277e745bab4c3fb66acadd492","carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_xpresspost","service_name":"CANADAPOST XPRESSPOST","price":16.73,"price_detail":[{"name":"Base charge","amount":11.32,"currency":"CAD"},{"name":"GST","amount":0.73,"currency":"CAD"},{"name":"PST","amount":1.45,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":3.23,"currency":"CAD"}],"transit_days":1,"test_mode":true},{"rate_id":"rat_ddc7d8b277e745bab4c3fb66acadd493","carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_priority","service_name":"CANADAPOST PRIORITY","price":31.67,"price_detail":[{"name":"Base charge","amount":21.43,"currency":"CAD"},{"name":"GST","amount":1.38,"currency":"CAD"},{"name":"PST","amount":2.75,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":6.11,"currency":"CAD"}],"transit_days":1,"test_mode":true}],"best_rate":{"rate_id":"rat_ddc7d8b277e745bab4c3fb66acadd490","carrier_name":"canadapost","carrier_id":"CPTEST","currency":"CAD","service_code":"canadapost_expedited_parcel","service_name":"CANADAPOST EXPEDITED PARCEL","price":15.18,"price_detail":[{"name":"Base charge","amount":10.27,"currency":"CAD"},{"name":"GST","amount":0.66,"currency":"CAD"},{"name":"PST","amount":1.32,"currency":"CAD"},{"name":"HST","amount":0,"currency":"CAD"},{"name":"Fuel surcharge","amount":2.93,"currency":"CAD"}],"transit_days":1,"test_mode":true}}}}},"400":{"description":"Bad Request"},"409":{"headers":{"Retry-After":{"description":"Present only on the 409 IDEMPOTENCY_IN_PROGRESS answer: the original request with this Idempotency-Key is still processing; retry after this many seconds.","schema":{"type":"string","examples":[1]}}},"description":"Idempotency-Key conflict","content":{"application/json":{"example":{"result":false,"code":"IDEMPOTENCY_CONFLICT","message":"Idempotency-Key was already used with a different request body"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/labelservice/getShippingDetail":{"post":{"tags":["LabelService"],"summary":"get Shipping Detail By Order ID or Tracking Number or Third Party Tracking Number","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelServiceShippingDetailRequest"},"examples":{"Order ID":{"value":{"id":12708,"type":"ORDER_ID","rate_id":"rat_xxxx","warehouse_code":"test","carrier":"fedex test","service":"express test"}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"shippingPrice":{"type":"string","description":"Shipping price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"mainTrackingNumber":{"type":"string","description":"Main tracking number. Field in the JSON request body.\n\n**Details:** Type `string`."},"trackingNumber":{"type":"string","description":"Tracking number. Field in the JSON request body.\n\n**Details:** Type `string`."},"needSubmitShippingInformation":{"type":"boolean","description":"Need submit shipping information. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"rate":{"type":"object","properties":{"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"price_detail":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"amount":{"type":"number","description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."}}},"description":"Price detail. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `array`, items `object`."},"tax_items":{"type":"array","items":{"type":"string","description":"Tax items. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Tax items. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}},"description":"Rate. Field in the JSON request body.\n\n**Details:** Type `object`."},"shippingLabel":{"type":"string","description":"Shipping label. Human-readable label.\n\n**Details:** Type `string`."},"labelStatus":{"type":"string","enum":["ready","pending","failed"],"description":"State of the label PDF. `ready`: the file is stored and `shippingLabel` carries it. `pending`: the order is purchased and charged but the carrier has not produced the file yet; the platform polls for it every 30 seconds for up to 5 minutes, call again later. `failed`: that poll gave up; calling this endpoint again restarts it. Additive field (2026-09).\n\nAllowed values: `ready` · `pending` · `failed`.\n\n**Details:** Type `string`.","examples":["ready"]},"code":{"type":"string","description":"Present while `labelStatus` is not `ready`: `shipment_label_not_ready`.\n\n**Details:** Type `string`."},"labelFetch":{"$ref":"#/components/schemas/LabelFetchState","description":"Label fetch. Human-readable label.\n\n**Details:** Schema `$ref` → `LabelFetchState`."}}},"example":{"id":118442,"shippingPrice":"28.32","mainTrackingNumber":131212133214,"trackingNumber":794972447977,"needSubmitShippingInformation":false,"rate":{"carrier_name":"Fedex","price":20.06,"price_detail":[{"name":"Base Charge","amount":9.99},{"name":"Residential Delivery Fee","amount":2.81},{"name":"Remote Area Surcharge","amount":0},{"name":"Additional Handling Charge","amount":0},{"name":"Oversize Surcharge","amount":0},{"name":"Unauthorized Package Charge","amount":0},{"name":"Peak Unauthorized Package Charge","amount":0},{"name":"Peak Residential Delivery Fee","amount":2.63},{"name":"Peak Additional Handling Charge","amount":0},{"name":"Peak Oversize Surcharge","amount":0},{"name":"Signature Fee","amount":0},{"name":"Declared Value Fee","amount":0},{"name":"Fuel Surcharge","amount":4.63}],"tax_items":["HST","GST","PST","QST"]},"shippingLabel":"JVBERi0xLjQKMS... (base64 encoded)","labelStatus":"ready"}}}},"400":{"description":"Bad Request A customer with Auto Pause Label Service enabled is refused when balance + credit does not cover the label: `message` keeps its historical literal `Insufficient balance available`, and an `insufficient_balance` block carries the shortfall and the available top-up channels. Also answered while the carrier has accepted (and charged) the order but not produced the label file yet: `message` carries the carrier's wording, `code` is `shipment_label_not_ready`, `labelStatus` is `pending` (the platform polls the carrier every 30 seconds for up to 5 minutes) or `failed` (that poll gave up), and `labelFetch` describes the poll. Calling again after a failed poll restarts it; the order is never purchased twice.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"code":{"type":"string","description":"`INSUFFICIENT_BALANCE` when the refusal was a balance one; `OUT_OF_DELIVERY_AREA` when the delivery address is outside the delivery area and the business setting deletes such orders; `shipment_label_not_ready` when the order is purchased but the carrier has not produced the label file yet (see `labelStatus`).\n\n**Details:** Type `string`.","examples":["INSUFFICIENT_BALANCE"]},"insufficient_balance":{"$ref":"#/components/schemas/InsufficientBalance","description":"Insufficient balance. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `InsufficientBalance`."},"labelStatus":{"type":"string","enum":["pending","failed"],"description":"Only with `code` = `shipment_label_not_ready`: whether the background poll for the label file is still running or gave up.\n\nAllowed values: `pending` · `failed`.\n\n**Details:** Type `string`."},"labelFetch":{"$ref":"#/components/schemas/LabelFetchState","description":"Label fetch. Human-readable label.\n\n**Details:** Schema `$ref` → `LabelFetchState`."}}},"example":{"message":"Insufficient balance available","code":"INSUFFICIENT_BALANCE","insufficient_balance":{"msg":"Insufficient balance available","balance":7,"code":"INSUFFICIENT_BALANCE","message":"This charge is $12.00, but only $5.00 is available on your account. You are $7.00 short.","required":12,"available":5,"shortfall":7,"currency":"CAD","currency_symbol":"$","can_pay_online":true,"max_online_amount":null,"exceeds_max_online_amount":false,"channels":[{"id":"stripe:card","gateway":"stripe","method":"card","value":"card","display_name":"Credit / Debit Card","icon":"fas fa-credit-card","requires_saved_card":true}],"add_funds_url":"https://app.superroute.ca/payment/invoice?token=..."}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/labelservice/cancelShippingLabel":{"post":{"tags":["LabelService"],"summary":"cancel Shipping Label","parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","maxLength":255,"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of cancelling again. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). A non-200 outcome releases the key, so a rejected request can be fixed and retried with it. Absent header = exact legacy behaviour. Keys are scoped per user and per endpoint.\n\n**Details:** Optional · Type `string` · maxLength `255`."},"description":"Optional. When present, retries with the SAME key and the SAME body replay the first response instead of cancelling again. The same key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT; while the original request is still processing, retries return 409 IDEMPOTENCY_IN_PROGRESS (retry shortly). A non-200 outcome releases the key, so a rejected request can be fixed and retried with it. Absent header = exact legacy behaviour. Keys are scoped per user and per endpoint.\n\n**Details:** Optional · Type `string` · maxLength `255`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelServiceCancelLabelRequest"},"examples":{"Order ID":{"value":{"id":17832}},"Tracking Number":{"value":{"tracking_number":794973591300}}}}},"required":true},"responses":{"200":{"headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome. The body also carries replayed: true.","schema":{"type":"string","enum":["true"]}}},"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Shipping Label cancelled successfully"}}}},"400":{"description":"Bad Request"},"409":{"headers":{"Retry-After":{"description":"Present only on the 409 IDEMPOTENCY_IN_PROGRESS answer: the original request with this Idempotency-Key is still processing; retry after this many seconds.","schema":{"type":"string","examples":[1]}}},"description":"Idempotency-Key conflict","content":{"application/json":{"example":{"result":false,"code":"IDEMPOTENCY_CONFLICT","message":"Idempotency-Key was already used with a different request body"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/labelservice/uploadShippingLabel":{"post":{"operationId":"uploadshippinglabel","tags":["LabelService"],"consumes":["multipart/form-data"],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}},"example":{"result":true,"msg":"Successful","id":1}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"result":false,"msg":"Error Message"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Order ID\n\nResource identifier.\n\n**Details:** Type `integer`."},"shippingLabel":{"type":"string","format":"binary","description":"shippingLabel file(PDF Only)\n\n**Details:** Type `file`."},"packages":{"type":"array","items":{"type":"string"},"description":"packages tracking number\n\nLegacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`.","examples":[[{"id":112343,"tracking_number":123456789012},{"id":112344,"tracking_number":123456789013}]]}}}}}}}},"/v1/client/order-status":{"get":{"operationId":"clientListOrderStatuses","tags":["Client"],"summary":"get order status list","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"1":{"type":"string","description":"1. Field in the JSON request body.\n\n**Details:** Type `string`."},"2":{"type":"string","description":"2. Field in the JSON request body.\n\n**Details:** Type `string`."},"3":{"type":"string","description":"3. Field in the JSON request body.\n\n**Details:** Type `string`."},"4":{"type":"string","description":"4. Field in the JSON request body.\n\n**Details:** Type `string`."},"5":{"type":"string","description":"5. Field in the JSON request body.\n\n**Details:** Type `string`."},"6":{"type":"string","description":"6. Field in the JSON request body.\n\n**Details:** Type `string`."},"7":{"type":"string","description":"7. Field in the JSON request body.\n\n**Details:** Type `string`."},"8":{"type":"string","description":"8. Field in the JSON request body.\n\n**Details:** Type `string`."},"9":{"type":"string","description":"9. Field in the JSON request body.\n\n**Details:** Type `string`."},"10":{"type":"string","description":"10. Field in the JSON request body.\n\n**Details:** Type `string`."},"11":{"type":"string","description":"11. Field in the JSON request body.\n\n**Details:** Type `string`."},"12":{"type":"string","description":"12. Field in the JSON request body.\n\n**Details:** Type `string`."},"13":{"type":"string","description":"13. Field in the JSON request body.\n\n**Details:** Type `string`."},"14":{"type":"string","description":"14. Field in the JSON request body.\n\n**Details:** Type `string`."},"15":{"type":"string","description":"15. Field in the JSON request body.\n\n**Details:** Type `string`."},"16":{"type":"string","description":"16. Field in the JSON request body.\n\n**Details:** Type `string`."}}}},"example":[{"1":"Need Update Address Information","2":"New","3":"Waiting To Plan","4":"Planning","5":"Already Planned","6":"Plan Failed","7":"Already Pickuped","8":"Successful","9":"Rescheduled by same driver","10":"Need Reschedule","11":"Rescheduled","12":"Cancelled","13":"Received","14":"Hold","15":"Need to check address","16":"Need to Pickup"}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/client/build-route":{"post":{"tags":["Client"],"summary":"Build routes","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildRoute"}}},"required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"route_id":123,"message":"This route is being processed"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v2/client/build-route":{"post":{"tags":["Client"],"summary":"Build routes","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildRouteV2"}}},"required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"route_id":123,"message":"This route is being processed"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v3/client/build-route/options":{"get":{"tags":["Client"],"summary":"Get build route options","description":"Returns available configuration options for building routes: routing engines with their balance modes, capacity types, related order types, order sources, and default values. Only the engines allowed for your business are listed: 1 = sRoute, 2 = sRoute 2, 3 = sRoute 2T (a separate engine, enabled per business; like sRoute 2 its balance modes are preset names, and it has its own presets). Each engine's `name` is a display label (`sRoute`, `sRoute 2`, `sRoute 2T`; earlier versions returned `SROUTE`, `SROUTE 2`, `SROUTE 2T`) — match engines on `id`, never on `name`; the ids, keys and types are unchanged.","responses":{"200":{"description":"Available options","content":{"application/json":{"example":{"success":true,"data":{"routing_engines":[{"id":1,"name":"sRoute","balance_modes":[{"value":1,"name":"Balance on number of orders"},{"value":2,"name":"Balance on working hours"},{"value":3,"name":"Without Balance"},{"value":4,"name":"Balanced within tolerance"},{"value":5,"name":"Balanced by zone"},{"value":6,"name":"Working hours within tolerance"},{"value":7,"name":"Balanced by zone and working hours"}],"balance_tolerance":{"applies_to_balance_mode":4,"applies_to_balance_modes":[4,5,6,7],"min":1,"max":100,"default":15}},{"id":2,"name":"sRoute 2","balance_modes":[{"value":"balanced","name":"balanced"}]},{"id":3,"name":"sRoute 2T","balance_modes":[{"value":"balanced","name":"balanced"},{"value":"finish_together","name":"finish_together"},{"value":"compact_fair","name":"compact_fair"}]}],"capacity_types":[{"id":1,"name":"Orders"},{"id":2,"name":"Packages"},{"id":3,"name":"Load Units"}],"related_order_types":[{"id":"NONE","name":"None"},{"id":1,"name":"Batch Pickup"}],"order_sources":[{"id":1,"name":"Import"},{"id":2,"name":"Web"},{"id":3,"name":"API"}],"defaults":{"routing_engine":1,"balance_mode":1,"balance_tolerance":15,"capacity_type":1,"service_time":5,"package_processing_time":30,"pickup_time":5,"package_pickup_time":30}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - not a client user"}},"security":[{"bearerAuth":[]}]}},"/v3/client/build-route":{"post":{"tags":["Client"],"summary":"Build routes (V3)","description":"V3 client build route API with full /orders/build parameter support. Supports routing engine selection (sRoute/sRoute 2/sRoute 2T), unified balance mode, order source and related order type filtering, and structured driver objects with nested addresses and driver-default fallback.\n\nReading the outcome: a 201 with status \"processing\" only means the route was created and its planning was queued. Poll GET /api/v1/client/routes (GraphQL clientRoutes) with date set to route_date and includeFailed=1, and look for data[].id equal to the returned route_id. A row with status 3 (Success) has been planned; a row with status 4 (Failed) could not be planned, and plan_failure_code / plan_failure_reason say why (its orders are already back in the order pool). A row with status 1 (Requested) or 2 (Planning) is still being planned: status_label reads \"Processing\" in the language of the request, both failure fields are null, total is 0 and count is empty. No row at all means the id is not one of this account's routes on that date (or the route was cancelled). Example failed row: {\"id\": 123, \"name\": \"V3 Route\", \"date\": \"2026-09-14\", \"total\": 0, \"count\": {}, \"drivers\": [], \"status\": 4, \"status_label\": \"Failed\", \"plan_failure_code\": \"no_valid_coordinates\", \"plan_failure_reason\": \"None of the orders on this route has valid coordinates. The orders were returned to the order pool; fix their addresses and plan again.\"} Example processing row: {\"id\": 124, \"name\": \"V3 Route\", \"date\": \"2026-09-14\", \"total\": 0, \"count\": [], \"drivers\": [{\"id\": 688, \"alias\": \"VV\", \"name\": \"V\", \"vehicle_type\": 1}], \"status\": 1, \"status_label\": \"Processing\", \"plan_failure_code\": null, \"plan_failure_reason\": null} Planning rules the chosen engine cannot apply: the 201 body carries data.rule_notices, a list (empty when every planning rule applies) of {rule, engine (sroute | sroute2 | sroute2t), status (dropped | approximated), reason (engine_unsupported | engine_version), min_version and engine_version (both only with reason engine_version; engine_version is null when the engine version could not be read)}. A rule the engine does not support, or whose minimum version the engine does not report, is dropped; an approximated rule is planned as closely as the engine allows. Every other field of the response is unchanged. Phase P3: rule_notices may also name the facts release_time, delivery_alternatives, break_skip_policy and shifts, and reason balance_preset.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildRouteV3"}}},"required":true},"responses":{"201":{"description":"Route created or processing. When processing, read the planning outcome from GET /api/v1/client/routes with includeFailed=1 (see the description).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"status":{"type":"string","enum":["processing","created"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `processing` · `created`.\n\n**Details:** Type `string`."},"rule_notices":{"type":"array","description":"Planning rules in use (the request's solver_rules over the business Route Settings defaults) that the route's routing engine cannot apply as chosen. Empty when every rule applies, and always empty while Planning Rules is disabled for the account. Nothing is refused: the route is still built and planned, and the same notices are stored on the route as plan_explanation.rule_notices once it is planned. Additive field.\n\n**Details:** Type `array`.","items":{"$ref":"#/components/schemas/RuleNotice","description":"Rule notices. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `RuleNotice`."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"success":true,"message":"This route is being processed.","data":{"route_id":123,"status":"processing","rule_notices":[{"rule":"solve_time","engine":"sroute","status":"dropped","reason":"engine_unsupported"}]}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - not a client user"},"422":{"description":"Validation Error"}},"security":[{"bearerAuth":[]}]}},"/v1/client/tracking/{trackingNumber}":{"get":{"tags":["Client"],"summary":"Get internal tracking information by tracking number","description":"Retrieves detailed tracking information for a parcel including tracking events, sender/recipient addresses, and delivery status. Unlike the public tracking endpoint, every return reason on a failed stop is returned here, whether or not the business marked it visible to the public.","parameters":[{"in":"path","name":"trackingNumber","schema":{"type":"string","description":"The tracking number of the parcel\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`."},"required":true,"description":"The tracking number of the parcel\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`.","example":"SR123456789"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Indicates if the request was successful\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Response message\n\n**Details:** Type `string`."},"is_third_party_tracking":{"type":"boolean","description":"Indicates if tracking is from a third-party carrier\n\n**Details:** Type `boolean`."},"postcode":{"type":"string","description":"Delivery postcode\n\n**Details:** Type `string`."},"deliveried":{"type":"boolean","description":"Indicates if the parcel has been delivered\n\n**Details:** Type `boolean`."},"returntosender":{"type":"boolean","description":"Indicates if the parcel is being returned to sender\n\n**Details:** Type `boolean`."},"rejectedbyrecipient":{"type":"boolean","description":"Indicates if the parcel was rejected by recipient\n\n**Details:** Type `boolean`."},"data":{"type":"array","description":"List of tracking events\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"tracking_event_status_id":{"type":"integer","description":"Tracking event status identifier\n\n**Details:** Type `integer`."},"updated_at":{"type":"string","format":"date-time","description":"Event timestamp in UTC\n\n**Details:** Type `string`, format `date-time`."},"description":{"type":"string","description":"Human-readable event description\n\n**Details:** Type `string`."},"location_name":{"type":["string","null"],"description":"Location name where the event occurred. Only included if value exists.\n\n**Details:** Type `string` · Nullable."},"location_city":{"type":["string","null"],"description":"City of the event location. Only included if value exists.\n\n**Details:** Type `string` · Nullable."},"location_province":{"type":["string","null"],"description":"Province/state of the event location. Only included if value exists.\n\n**Details:** Type `string` · Nullable."},"location_country":{"type":["string","null"],"description":"country of the event location. Only included if value exists.\n\n**Details:** Type `string` · Nullable."},"location_postcode":{"type":["string","null"],"description":"Postal/ZIP code of the event location. Only included if value exists.\n\n**Details:** Type `string` · Nullable."},"reason":{"type":["string","null"],"description":"Return reason recorded on a failed delivery/pickup stop, when one was given. This authenticated endpoint returns every reason, including reasons the business marked as not visible to the public.\n\n**Details:** Type `string` · Nullable."},"time_zone":{"type":"string","description":"Timezone of the event location\n\n**Details:** Type `string`."},"gmt_offset":{"type":"string","description":"The gmt_offset represents the UTC offset at a specific point in time, calculated from the provided IANA timezone and automatically adjusted for Daylight Saving Time (DST) when applicable.\n\n**Details:** Type `string`."},"order_id":{"type":"integer","description":"Associated order ID\n\n**Details:** Type `integer`."},"display_distance_unit":{"type":"integer","description":"Distance unit for display (1: km, 2: miles)\n\n**Details:** Type `integer`."},"orders_status_id":{"type":"integer","description":"Current order status ID\n\nOrder lifecycle status id (`orders.orders_status_id`). Source: `OrdersStatusInput`.\n\nEnum values (from deployed code):\n- `1` — Need Update Address (`need_update_address`)\n- `2` — New Order (`new_order`)\n- `3` — Waiting To Plan (`waiting_to_plan`)\n- `4` — Planning (`planning`)\n- `5` — Already Planned (`already_planned`)\n- `6` — Plan Failed (`plan_failed`)\n- `14` — Already Pickup (`already_pickup`)\n- `8` — Successful (`successful`)\n- `9` — Redelivered Later (`redelivered_later`)\n- `10` — Need Rescheduled (`need_rescheduled`)\n- `11` — Rescheduled (`rescheduled`)\n- `12` — Cancelled (`cancelled`)\n- `16` — Need To Pick Up (`need_to_pick_up`)\n- `7` — Already Pickup (`already_pickup`)\n- `20` — Out For Delivery (`out_for_delivery`)\n- `21` — Out For Pickup (`out_for_pickup`)\n- `17` — Waiting For Self Pickup (`waiting_for_self_pickup`)\n- `19` — Return To Customer (`return_to_customer`)\n- `25` — Hand Off (`hand_off`)\n- `18` — Self Pickup Completed (`self_pickup_completed`)\n- `22` — Partial Received (`partial_received`)\n- `23` — Partial Delivered (`partial_delivered`)\n- `24` — Partial Pickuped (`partial_pickuped`)\n- `26` — Review (`review`)\n- `27` — Destroyed (`destroyed`)\n- `29` — In Transit (`in_transit`)\n- `30` — Package Lost (`package_lost`)\n- `31` — Package Damaged (`package_damaged`)\n- `32` — Waiting Customer Options (`waiting_customer_options`)\n- `33` — Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)\n- `34` — Waiting Batch Pickup (`waiting_batch_pickup`)\n- `28` — Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)\n- `35` — Payment Required (`payment_required`)\n- `36` — Bulk Transshipment Pending (`bulk_transshipment_pending`)\n- `37` — Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)\n- `38` — Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)\n- `39` — Inbound Scan Required (`inbound_scan_required`)\n- `40` — Rejected By Recipient (`rejected_by_recipient`)\n- `41` — Package Outbound (`package_outbound`)\n- `42` — Waiting For Quote (`waiting_for_quote`)\n- `43` — Waiting Third Party Handover (`waiting_third_party_handover`)\n- `44` — Waiting For Assignment (`waiting_for_assignment`)\n- `45` — Start Pickup (`start_pickup`)\n- `46` — Start Delivery (`start_delivery`)\n- `47` — Out Of Delivery Area (`out_of_delivery_area`)\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5,6,14,8,9,10,11,12,16,7,20,21,17,19,25,18,22,23,24,26,27,29,30,31,32,33,34,28,35,36,37,38,39,40,41,42,43,44,45,46,47],"x-enumDescriptions":["Need Update Address (`need_update_address`)","New Order (`new_order`)","Waiting To Plan (`waiting_to_plan`)","Planning (`planning`)","Already Planned (`already_planned`)","Plan Failed (`plan_failed`)","Already Pickup (`already_pickup`)","Successful (`successful`)","Redelivered Later (`redelivered_later`)","Need Rescheduled (`need_rescheduled`)","Rescheduled (`rescheduled`)","Cancelled (`cancelled`)","Need To Pick Up (`need_to_pick_up`)","Already Pickup (`already_pickup`)","Out For Delivery (`out_for_delivery`)","Out For Pickup (`out_for_pickup`)","Waiting For Self Pickup (`waiting_for_self_pickup`)","Return To Customer (`return_to_customer`)","Hand Off (`hand_off`)","Self Pickup Completed (`self_pickup_completed`)","Partial Received (`partial_received`)","Partial Delivered (`partial_delivered`)","Partial Pickuped (`partial_pickuped`)","Review (`review`)","Destroyed (`destroyed`)","In Transit (`in_transit`)","Package Lost (`package_lost`)","Package Damaged (`package_damaged`)","Waiting Customer Options (`waiting_customer_options`)","Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)","Waiting Batch Pickup (`waiting_batch_pickup`)","Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)","Payment Required (`payment_required`)","Bulk Transshipment Pending (`bulk_transshipment_pending`)","Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)","Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)","Inbound Scan Required (`inbound_scan_required`)","Rejected By Recipient (`rejected_by_recipient`)","Package Outbound (`package_outbound`)","Waiting For Quote (`waiting_for_quote`)","Waiting Third Party Handover (`waiting_third_party_handover`)","Waiting For Assignment (`waiting_for_assignment`)","Start Pickup (`start_pickup`)","Start Delivery (`start_delivery`)","Out Of Delivery Area (`out_of_delivery_area`)"]},"timestamp":{"type":"integer","description":"Unix timestamp of the event\n\n**Details:** Type `integer`."},"updated_at_localized":{"type":"string","description":"Event timestamp in local timezone\n\n**Details:** Type `string`."}}}},"proofs":{"type":"array","description":"Proof of delivery (POD) files captured at delivery (signatures and photos). Empty array until delivery proof has been uploaded.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"url":{"type":"string","description":"Relative public URL of the proof file\n\n**Details:** Type `string`."},"full_url":{"type":"string","description":"Absolute public URL of the proof file\n\n**Details:** Type `string`."},"type":{"type":"integer","description":"Proof file type (1: signature, 2: photo)\n\n**Details:** Type `integer`."},"file_id":{"type":"integer","description":"Stable file identifier, usable for consumer-side dedup/incremental sync\n\n**Details:** Type `integer`."},"uploaded_at":{"type":["string","null"],"description":"Upload time (Y-m-d H:i:s, UTC)\n\n**Details:** Type `string` · Nullable."},"uploaded_timestamp":{"type":["integer","null"],"description":"Unix timestamp of the upload time\n\n**Details:** Type `integer` · Nullable."},"signed_url":{"type":"string","description":"Expiring signed download URL — an alternative to the permanent public link. Re-query tracking to obtain a fresh one after expiry.\n\n**Details:** Type `string`."},"signed_url_expires_at":{"type":"integer","description":"Unix timestamp when signed_url expires\n\n**Details:** Type `integer`."},"tracking_event_id":{"type":["integer","null"],"description":"Tracking event the proof was captured for. A file uploaded on its own, with no event recorded, is read off the order's timeline: the outcome it was uploaded right before (what the driver went on to report) or right after (what the driver had already reported). null only when the order has no such outcome.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_status_id":{"type":["integer","null"],"description":"Status code of that event (500 delivered, 504 partially delivered, 510 picked up, 501/502/503 failed delivery, 512/513 failed pickup, …). null without an event.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_key":{"type":["string","null"],"description":"Stable key of that event status (deliver_success, pickuped, not_delivered, …). null without an event.\n\n**Details:** Type `string` · Nullable."},"service_type":{"type":["integer","null"],"enum":[1,2,null],"description":"Code of the service the proof belongs to, derived from the event's leg type: 1 = delivery, 2 = pickup. null without an event.\n\nAllowed values: `1` · `2` · `null`.\n\n**Details:** Type `integer` · Nullable."},"service_status":{"type":["integer","null"],"enum":[1,2,null],"description":"Code of the outcome the proof documents, derived from the event status: 1 = success (500, 504, 510), 2 = failed (501, 502, 503, 512, 513). null without an event or for other statuses.\n\nAllowed values: `1` · `2` · `null`.\n\n**Details:** Type `integer` · Nullable."}}}},"sender_address":{"type":"object","description":"Sender address information\n\n**Details:** Type `object`.","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"email":{"type":["string","null"],"description":"Account email address.\n\n**Details:** Type `string` · Nullable."},"lat":{"type":"string","description":"Latitude coordinate\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Longitude coordinate\n\n**Details:** Type `string`."},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`."}}},"recipient_address":{"type":"object","description":"Recipient address information\n\n**Details:** Type `object`.","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"email":{"type":["string","null"],"description":"Account email address.\n\n**Details:** Type `string` · Nullable."},"lat":{"type":"string","description":"Latitude coordinate\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Longitude coordinate\n\n**Details:** Type `string`."},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`."}}},"is_alliance_data":{"type":"boolean","description":"Indicates if this data was accessed through alliance cross-client permissions\n\n**Details:** Type `boolean`."},"alliance":{"type":"object","description":"Alliance information (only present when is_alliance_data is true)\n\n**Details:** Type `object`.","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Regional Delivery Alliance`.","examples":["Regional Delivery Alliance"]},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`.\n\n**Example:** `AB12CD34`.","examples":["AB12CD34"]}}},"original_carrier":{"type":"object","description":"Original carrier information (only present when is_alliance_data is true)\n\n**Details:** Type `object`.","properties":{"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"business_name":{"type":"string","description":"Business name. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `ABC Logistics Ltd`.","examples":["ABC Logistics Ltd"]}}}}},"example":{"result":true,"message":"Success","is_third_party_tracking":false,"postcode":"H2X1Y4","deliveried":true,"returntosender":false,"rejectedbyrecipient":false,"data":[{"tracking_event_status_id":500,"updated_at":"2025-01-16T18:45:00.000000Z","description":"Your parcel has been delivered successfully. Thank you!","location_city":"Montreal","location_province":"QC","location_country":"CA","location_postcode":"H2X 1Y4","operation_location":"Montreal,QC","reason":null,"time_zone":"America/Toronto","gmt_offset":"GMT −05:00","order_id":123456,"display_distance_unit":1,"orders_status_id":8,"timestamp":1737053100,"updated_at_localized":"2025-01-16 13:45:00"},{"tracking_event_status_id":300,"updated_at":"2025-01-15T10:30:00.000000Z","description":"Your parcel has arrived safely at Distribution Centre.","location_name":"Distribution Centre","location_city":"Toronto","location_province":"ON","location_country":"CA","location_postcode":"M6N 3L2","operation_location":"Distribution Centre,Toronto,ON","reason":null,"time_zone":"America/Toronto","gmt_offset":"GMT −05:00","order_id":123456,"display_distance_unit":1,"orders_status_id":2,"timestamp":1736937000,"updated_at_localized":"2025-01-15 05:30:00"},{"tracking_event_status_id":301,"updated_at":"2025-01-15T08:15:00.000000Z","description":"Your parcel has been collected and arrived at Distribution Centre.","location_name":"Distribution Centre","location_city":"Toronto","location_province":"ON","location_country":"CA","location_postcode":"M6N 3L2","operation_location":"Distribution Centre,Toronto,ON","reason":null,"time_zone":"America/Toronto","gmt_offset":"GMT −05:00","order_id":123456,"display_distance_unit":1,"orders_status_id":2,"timestamp":1736928900,"updated_at_localized":"2025-01-15 03:15:00"},{"tracking_event_status_id":100,"updated_at":"2025-01-14T14:00:00.000000Z","description":"We have received your package details and are processing your order.","location_name":"Distribution Centre","location_city":"Toronto","location_province":"ON","location_country":"CA","location_postcode":"M6N 3L2","operation_location":"Distribution Centre,Toronto,ON","reason":null,"time_zone":"America/Toronto","gmt_offset":"GMT −05:00","order_id":123456,"display_distance_unit":1,"orders_status_id":2,"timestamp":1736863200,"updated_at_localized":"2025-01-14 09:00:00"}],"proofs":[{"url":"/storage/proofs/2025/01/pod_98765_signature.png","full_url":"https://api.superroute.ca/storage/proofs/2025/01/pod_98765_signature.png","type":1,"file_id":98765,"uploaded_at":"2025-01-16 18:45:12","uploaded_timestamp":1737053112,"signed_url":"https://api.superroute.ca/files/pod/98765?expires=1739645112&signature=8f14e45fceea167a5a36dedd4bea2543068f6c2d3f9022ff0d7a2c1b6a9d4e21","signed_url_expires_at":1739645112,"tracking_event_id":8261082,"tracking_event_status_id":500,"tracking_event_key":"deliver_success","service_type":1,"service_status":1},{"url":"/storage/proofs/2025/01/pod_98766_photo.jpg","full_url":"https://api.superroute.ca/storage/proofs/2025/01/pod_98766_photo.jpg","type":2,"file_id":98766,"uploaded_at":"2025-01-16 18:45:15","uploaded_timestamp":1737053115,"signed_url":"https://api.superroute.ca/files/pod/98766?expires=1739645115&signature=45c48cce2e2d7fbdea1afc51c7c6ad26a3e1b6f8c0d9427e5b30fd1a89c2e7b4","signed_url_expires_at":1739645115,"tracking_event_id":8261082,"tracking_event_status_id":500,"tracking_event_key":"deliver_success","service_type":1,"service_status":1}],"sender_address":{"name":"Example Warehouse","telephone":4161234567,"address_1":"123 Industrial Blvd","address_2":"Unit 5","city":"Toronto","province":"Ontario","country":"CA","postcode":"M5V 1J2","email":null,"lat":"43.6426","lng":"-79.3871","code":""},"recipient_address":{"name":"John Doe","telephone":5141234567,"address_1":"456 Rue Sample","address_2":"Apt 101","city":"Montreal","province":"Quebec","country":"CA","postcode":"H2X 1Y4","email":"example@email.com","lat":"45.5017","lng":"-73.5673","code":""}}}}},"404":{"description":"Tracking number not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Tracking number not found"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/client/territory":{"get":{"operationId":"clientListTerritories","tags":["Client"],"summary":"get territory info list","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"center":{"type":"string","description":"Center. Field in the JSON request body.\n\n**Details:** Type `string`."},"poly":{"type":"string","description":"Poly. Field in the JSON request body.\n\n**Details:** Type `string`."}}}},"example":[{"id":5,"name":"Montreal","center":"[45.524643655706775,-73.63191570676673]","poly":"[{\"lat\":45.64352281098869,\"log\":-73.81778677441407},{\"lat\":45.7898033673854,\"log\":-73.64123675103916},{\"lat\":45.6561174746696,\"log\":-73.33285079016422},{\"lat\":45.57735200355098,\"log\":-73.24084029211734},{\"lat\":45.35486903601937,\"log\":-73.43378767981265},{\"lat\":45.334599769097125,\"log\":-73.65969405188297},{\"lat\":45.38574158285064,\"log\":-73.93847212805484},{\"lat\":45.455143201092355,\"log\":-73.99065718664859}]"}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/client/getaddressbypostcode":{"get":{"tags":["Client"],"parameters":[{"in":"query","name":"postcode","schema":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Required · Type `string`."},"required":true,"description":"Postal / ZIP code.\n\n**Details:** Required · Type `string`."},{"in":"query","name":"area","schema":{"type":"integer","enum":[1,2,3],"description":"Address / coverage area selector used by geocoding helpers.\n\nAddress / coverage area selector used by geocoding helpers.\n\nAllowed values: `1` · `2` · `3`.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Address / coverage area selector used by geocoding helpers.\n\nAddress / coverage area selector used by geocoding helpers.\n\nAllowed values: `1` · `2` · `3`.\n\n**Details:** Required · Type `integer`."}],"summary":"Get address by client","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`."},"province_name":{"type":"string","description":"Province name. Human-readable label.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"citys":{"type":"array","items":{"type":"string","description":"Citys. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"description":"Citys. Address component used for geocoding and delivery.\n\n**Details:** Type `array`, items `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Successful","postcode":2030,"type":"AU","province_name":"NSW","province":"NSW","citys":["DIAMOND BAY","DOVER HEIGHTS","HMAS WATSON","ROSE BAY NORTH","VAUCLUSE","WATSONS BAY"],"country":"AU"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/client/routes":{"get":{"tags":["Client"],"parameters":[{"in":"query","name":"date","description":"Filter routes by specific date (format: YYYY-MM-DD). When provided, isToday/isUpcoming/isHistory are ignored.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`.\n\n**Example:** `2025-03-11`.","schema":{"type":"string","format":"date","description":"Filter routes by specific date (format: YYYY-MM-DD). When provided, isToday/isUpcoming/isHistory are ignored.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`.\n\n**Example:** `2025-03-11`.","examples":["2025-03-11"]},"required":false},{"in":"query","name":"isToday","schema":{"type":"integer","enum":[0,1],"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"isUpcoming","schema":{"type":"integer","enum":[0,1],"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"isHistory","schema":{"type":"integer","enum":[0,1],"description":"Filter flag. `1` = historical / completed items; `0` = current items.\n\nFilter flag. `1` = historical / completed items; `0` = current items.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"Filter flag. `1` = historical / completed items; `0` = current items.\n\nFilter flag. `1` = historical / completed items; `0` = current items.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"withGeometry","description":"Set to 1 to include the encoded route geometry for each driver in the drivers array. Default 0 (geometry omitted).\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer` · Default: `0`.","schema":{"type":"integer","enum":[0,1],"default":0,"description":"Set to 1 to include the encoded route geometry for each driver in the drivers array. Default 0 (geometry omitted).\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer` · Default: `0`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false},{"in":"query","name":"includeFailed","description":"Set to 1 to also list routes whose planning is still running (status 1 Requested or 2 Planning, status_label \"Processing\" in the language of the request) and routes whose planning failed (status 4), and to add status, status_label, plan_failure_code and plan_failure_reason to every row (3 Success keeps the label \"Success\", 4 keeps \"Failed\"). Both failure fields are null unless status is 4; the reason is in the language of the request. A processing row has no plan yet: total 0, count empty, drivers the vehicles assigned to the build. The name is kept for compatibility. Default 0: planned routes only, rows exactly as before.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer` · Default: `0`.","schema":{"type":"integer","enum":[0,1],"default":0,"description":"Set to 1 to also list routes whose planning is still running (status 1 Requested or 2 Planning, status_label \"Processing\" in the language of the request) and routes whose planning failed (status 4), and to add status, status_label, plan_failure_code and plan_failure_reason to every row (3 Success keeps the label \"Success\", 4 keeps \"Failed\"). Both failure fields are null unless status is 4; the reason is in the language of the request. A processing row has no plan yet: total 0, count empty, drivers the vehicles assigned to the build. The name is kept for compatibility. Default 0: planned routes only, rows exactly as before.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer` · Default: `0`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false}],"summary":"Get routes","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"date":{"type":"string","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"count":{"type":"object","properties":{"successful":{"type":"integer","description":"Successful. Field in the JSON request body.\n\n**Details:** Type `integer`."},"out_for_delivery":{"type":"integer","description":"Out for delivery. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"drivers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"vehicle_type":{"type":"string","description":"Vehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"]},"geometry":{"type":["string","null"],"description":"Encoded route geometry for this driver's part of the route; null if no geometry is stored. Only present when withGeometry=1.\n\n**Details:** Type `string` · Nullable."}}},"description":"Drivers. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"status":{"type":"integer","description":"Only with includeFailed=1. 1 Requested or 2 Planning (still processing), 3 Success, 4 Failed.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"status_label":{"type":"string","description":"Only with includeFailed=1. \"Processing\" in the language of the request while status is 1 or 2; \"Success\" or \"Failed\" otherwise.\n\n**Details:** Type `string`."},"plan_failure_code":{"type":["string","null"],"enum":["no_orders","no_drivers","no_valid_coordinates","engine_error","no_routes",null],"description":"Only with includeFailed=1. Why planning failed; null unless status is 4.\n\nAllowed values: `no_orders` · `no_drivers` · `no_valid_coordinates` · `engine_error` · `no_routes`.\n\n**Details:** Type `string` · Nullable."},"plan_failure_reason":{"type":["string","null"],"description":"Only with includeFailed=1. The failure reason in the language of the request; null unless status is 4.\n\n**Details:** Type `string` · Nullable."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"data":[{"id":15915,"name":20250311174435,"date":"2025-03-11","total":12,"count":{"successful":6,"out_for_delivery":6},"drivers":[{"id":688,"alias":"VV","name":"V","vehicle_type":"1 (1: Car, 2: Truck, 3: Motorcycle, 4: Bicycle 5:Pedestrian)","geometry":"XXX"}]},{"id":15916,"name":20250311174623,"date":"2025-03-11","total":3,"count":{"already_pickup":1,"out_for_delivery":2},"drivers":[{"id":699,"alias":"AA","name":"A","vehicle_type":"1 (1: Car, 2: Truck, 3: Motorcycle, 4: Bicycle 5:Pedestrian)","geometry":"XXX"}]},{"id":15930,"name":20250312112409,"date":"2025-03-11","total":14,"count":{"already_planned":14},"drivers":[{"id":699,"alias":"A","name":"AA","vehicle_type":"1 (1: Car, 2: Truck, 3: Motorcycle, 4: Bicycle 5:Pedestrian)","geometry":"XXX"},{"id":700,"alias":"BB","name":"D","vehicle_type":"1 (1: Car, 2: Truck, 3: Motorcycle, 4: Bicycle 5:Pedestrian)","geometry":"XXX"}]}]}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}],"description":"The list a V3 build-route caller polls for the outcome of a queued planning run: pass includeFailed=1 to see a route still being planned (status 1 or 2, Processing) and a route that failed to plan, with the reason. Example failed row: {\"id\": 123, \"name\": \"V3 Route\", \"date\": \"2026-09-14\", \"total\": 0, \"count\": {}, \"drivers\": [], \"status\": 4, \"status_label\": \"Failed\", \"plan_failure_code\": \"no_valid_coordinates\", \"plan_failure_reason\": \"None of the orders on this route has valid coordinates. The orders were returned to the order pool; fix their addresses and plan again.\"} Example processing row: {\"id\": 124, \"name\": \"V3 Route\", \"date\": \"2026-09-14\", \"total\": 0, \"count\": [], \"drivers\": [{\"id\": 688, \"alias\": \"VV\", \"name\": \"V\", \"vehicle_type\": 1}], \"status\": 1, \"status_label\": \"Processing\", \"plan_failure_code\": null, \"plan_failure_reason\": null}"}},"/v1/client/routes/orders-by-date":{"get":{"tags":["Client"],"summary":"Get all orders from successfully planned routes on a specific date","parameters":[{"in":"query","name":"date","schema":{"type":"string","format":"date","description":"The route date (YYYY-MM-DD). Only routes with status 'Success' are included.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Required · Type `string`, format `date`.\n\n**Example:** `2024-01-15`.","examples":["2024-01-15"]},"required":true,"description":"The route date (YYYY-MM-DD). Only routes with status 'Success' are included.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Required · Type `string`, format `date`.\n\n**Example:** `2024-01-15`."},{"in":"query","name":"driverId","schema":{"type":"integer","description":"Filter orders by driver ID\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Filter orders by driver ID\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","description":"Item. Field in the JSON request body.\n\n**Details:** Type `object`."}},"example":[{"id":299545,"type":"P","order_type":"P2P","is_p2p":1,"is_locked":0,"ref":"T1","address_1":"1108 RUE D'AMBOISE","address_2":"","address_type":"","signature_option":0,"city":"Saint-Jerome","province":"QC","country":"Canada","postcode":"J5L0E1","buzz_code":"","latitude":"45.797655","longitude":"-74.049801","name":"y","email":null,"telephone":null,"tracking_number":"SR904766214130","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":1,"driver_id":343,"route_id":3964,"status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"allow_dropoff":1,"driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"1108 RUE D'AMBOISE,Saint-Jerome,QC,J5L0E1","operation_mode":0,"route_name":"Route A","route_date":"2024-01-15","is_multiple":1,"total_orders":2,"current_order":1}]}}},"400":{"description":"Bad Request - Missing mandatory field date"},"404":{"description":"No routes found for the given date"}},"security":[{"bearerAuth":[]}]}},"/v1/client/routes/{routeId}/orders":{"get":{"tags":["Client"],"summary":"Get orders on route for one driver or all","parameters":[{"in":"path","name":"routeId","schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"driverId","schema":{"type":"integer","description":"Driver id. Identifier referencing the related record.\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Driver id. Identifier referencing the related record.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`."},"order_type":{"type":"string","description":"Order type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nEnum values (from deployed code):\n- `D` — Delivery\n- `P` — Pickup\n- `L` — Label Service\n- `P2P` — Peer to Peer\n- `S` — Storage Order\n- `M` — Moving Order\n- `SH` — Shipping Service\n- `SO` — Shipout\n- `LTL` — LTL Service\n- `I` — Instant Delivery\n\n**Details:** Type `string`.","enum":["D","P","L","P2P","S","M","SH","SO","LTL","I"],"x-enumDescriptions":["Delivery","Pickup","Label Service","Peer to Peer","Storage Order","Moving Order","Shipping Service","Shipout","LTL Service","Instant Delivery"]},"is_p2p":{"type":"integer","description":"Is p2p. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_locked":{"type":"integer","description":"Is locked. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"address_type":{"type":"string","description":"Address type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"signature_option":{"type":"integer","description":"Signature option. Field in the JSON request body.\n\n**Details:** Type `integer`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"buzz_code":{"type":"string","description":"Buzz code. Stable machine-readable code.\n\n**Details:** Type `string`."},"latitude":{"type":"string","description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"longitude":{"type":"string","description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"email":{"type":["string","null"],"description":"Account email address.\n\n**Details:** Type `string` · Nullable."},"telephone":{"type":["string","null"],"description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string` · Nullable."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."},"driver_alias":{"type":"string","description":"Driver alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"stop_number":{"type":"integer","description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"driver_id":{"type":"integer","description":"Driver id.\n\n**Details:** Type `integer`."},"leg_number":{"type":["string","null"],"description":"Number of the driver's leg of this route: the fleet code followed by a sequence (\"ACME-2\"), or \"L-<n>\" when the fleet has no code, numbered across the whole route. Assigned on first read and then kept. Additive; null before a number exists.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"packages":{"type":"integer","description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `integer`."},"notification_language":{"type":"string","description":"Notification language. Field in the JSON request body.\n\n**Details:** Type `string`."},"return_reason_id":{"type":["string","null"],"description":"Return reason id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"orders_status_id":{"type":"integer","description":"Order lifecycle status id (`orders.orders_status_id`). Source: `OrdersStatusInput`.\n\nEnum values (from deployed code):\n- `1` — Need Update Address (`need_update_address`)\n- `2` — New Order (`new_order`)\n- `3` — Waiting To Plan (`waiting_to_plan`)\n- `4` — Planning (`planning`)\n- `5` — Already Planned (`already_planned`)\n- `6` — Plan Failed (`plan_failed`)\n- `14` — Already Pickup (`already_pickup`)\n- `8` — Successful (`successful`)\n- `9` — Redelivered Later (`redelivered_later`)\n- `10` — Need Rescheduled (`need_rescheduled`)\n- `11` — Rescheduled (`rescheduled`)\n- `12` — Cancelled (`cancelled`)\n- `16` — Need To Pick Up (`need_to_pick_up`)\n- `7` — Already Pickup (`already_pickup`)\n- `20` — Out For Delivery (`out_for_delivery`)\n- `21` — Out For Pickup (`out_for_pickup`)\n- `17` — Waiting For Self Pickup (`waiting_for_self_pickup`)\n- `19` — Return To Customer (`return_to_customer`)\n- `25` — Hand Off (`hand_off`)\n- `18` — Self Pickup Completed (`self_pickup_completed`)\n- `22` — Partial Received (`partial_received`)\n- `23` — Partial Delivered (`partial_delivered`)\n- `24` — Partial Pickuped (`partial_pickuped`)\n- `26` — Review (`review`)\n- `27` — Destroyed (`destroyed`)\n- `29` — In Transit (`in_transit`)\n- `30` — Package Lost (`package_lost`)\n- `31` — Package Damaged (`package_damaged`)\n- `32` — Waiting Customer Options (`waiting_customer_options`)\n- `33` — Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)\n- `34` — Waiting Batch Pickup (`waiting_batch_pickup`)\n- `28` — Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)\n- `35` — Payment Required (`payment_required`)\n- `36` — Bulk Transshipment Pending (`bulk_transshipment_pending`)\n- `37` — Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)\n- `38` — Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)\n- `39` — Inbound Scan Required (`inbound_scan_required`)\n- `40` — Rejected By Recipient (`rejected_by_recipient`)\n- `41` — Package Outbound (`package_outbound`)\n- `42` — Waiting For Quote (`waiting_for_quote`)\n- `43` — Waiting Third Party Handover (`waiting_third_party_handover`)\n- `44` — Waiting For Assignment (`waiting_for_assignment`)\n- `45` — Start Pickup (`start_pickup`)\n- `46` — Start Delivery (`start_delivery`)\n- `47` — Out Of Delivery Area (`out_of_delivery_area`)\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5,6,14,8,9,10,11,12,16,7,20,21,17,19,25,18,22,23,24,26,27,29,30,31,32,33,34,28,35,36,37,38,39,40,41,42,43,44,45,46,47],"x-enumDescriptions":["Need Update Address (`need_update_address`)","New Order (`new_order`)","Waiting To Plan (`waiting_to_plan`)","Planning (`planning`)","Already Planned (`already_planned`)","Plan Failed (`plan_failed`)","Already Pickup (`already_pickup`)","Successful (`successful`)","Redelivered Later (`redelivered_later`)","Need Rescheduled (`need_rescheduled`)","Rescheduled (`rescheduled`)","Cancelled (`cancelled`)","Need To Pick Up (`need_to_pick_up`)","Already Pickup (`already_pickup`)","Out For Delivery (`out_for_delivery`)","Out For Pickup (`out_for_pickup`)","Waiting For Self Pickup (`waiting_for_self_pickup`)","Return To Customer (`return_to_customer`)","Hand Off (`hand_off`)","Self Pickup Completed (`self_pickup_completed`)","Partial Received (`partial_received`)","Partial Delivered (`partial_delivered`)","Partial Pickuped (`partial_pickuped`)","Review (`review`)","Destroyed (`destroyed`)","In Transit (`in_transit`)","Package Lost (`package_lost`)","Package Damaged (`package_damaged`)","Waiting Customer Options (`waiting_customer_options`)","Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)","Waiting Batch Pickup (`waiting_batch_pickup`)","Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)","Payment Required (`payment_required`)","Bulk Transshipment Pending (`bulk_transshipment_pending`)","Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)","Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)","Inbound Scan Required (`inbound_scan_required`)","Rejected By Recipient (`rejected_by_recipient`)","Package Outbound (`package_outbound`)","Waiting For Quote (`waiting_for_quote`)","Waiting Third Party Handover (`waiting_third_party_handover`)","Waiting For Assignment (`waiting_for_assignment`)","Start Pickup (`start_pickup`)","Start Delivery (`start_delivery`)","Out Of Delivery Area (`out_of_delivery_area`)"]},"current_route_id":{"type":"integer","description":"Current route id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"related_order_type":{"type":["integer","null"],"description":"How this order links to another business document (`orders.related_order_type`). Source: `RelatedOrderTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Batch Pickup\n- `2` — Super Proxy\n- `3` — Storage Order\n- `4` — Return Request\n- `5` — Moving Order\n- `6` — Kiosk Pickup\n- `7` — Smart Locker Pickup\n- `8` — Product Purchase\n- `9` — Shipping Order\n- `10` — Storage Shipout\n- `11` — Return Label\n- `12` — Third-party Delivery Transfer\n- `16` — Sales Order\n- `17` — Third-party Partial Delivery Split\n- `18` — Order Split\n\n**Details:** Type `integer` · Nullable.","enum":[1,2,3,4,5,6,7,8,9,10,11,12,16,17,18,null],"x-enumDescriptions":["Batch Pickup","Super Proxy","Storage Order","Return Request","Moving Order","Kiosk Pickup","Smart Locker Pickup","Product Purchase","Shipping Order","Storage Shipout","Return Label","Third-party Delivery Transfer","Sales Order","Third-party Partial Delivery Split","Order Split"]},"related_order_id":{"type":["integer","null"],"description":"Id of the related document pointed to by `related_order_type` (storage order, shipping order, sales order, …).\n\n**Details:** Type `integer` · Nullable."},"allow_dropoff":{"type":"integer","description":"Allow dropoff. Field in the JSON request body.\n\n**Details:** Type `integer`."},"driverNotes":{"type":"array","items":{"type":"string","description":"Driver notes. Free-text note.\n\n**Details:** Type `string`."},"description":"Driver notes. Free-text note.\n\n**Details:** Type `array`, items `string`."},"files":{"type":"object","properties":{"photo_urls":{"type":"array","items":{"type":"string","description":"Photo urls. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Photo urls. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"signature_urls":{"type":"array","items":{"type":"string","description":"Signature urls. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Signature urls. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}},"description":"Files. Field in the JSON request body.\n\n**Details:** Type `object`."},"is_finished":{"type":"integer","description":"Is finished. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_postponed":{"type":"integer","description":"Is postponed. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"full_address":{"type":"string","description":"Full address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"operation_mode":{"type":"integer","description":"Operation mode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"is_multiple":{"type":"integer","description":"Is multiple. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"total_orders":{"type":"integer","description":"Total orders. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"current_order":{"type":"integer","description":"Current order. Field in the JSON request body.\n\n**Details:** Type `integer`."}}}},"example":[{"id":299545,"type":"P","order_type":"P2P","is_p2p":1,"is_locked":0,"ref":"T1","address_1":"1108 RUE D'AMBOISE","address_2":"","address_type":"","signature_option":0,"city":"Saint-Jerome","province":"QC","country":"Canada","postcode":"J5L0E1","buzz_code":"","latitude":"45.797655","longitude":"-74.049801","name":"y","email":null,"telephone":null,"tracking_number":"SR904766214130","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":1,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"related_order_type":null,"related_order_id":null,"allow_dropoff":1,"driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"6701 rue hadley,Montreal,QC,H4E3R3","operation_mode":0,"is_multiple":1,"total_orders":2,"current_order":2},{"id":299548,"type":"P","order_type":"P","is_p2p":0,"is_locked":0,"ref":"","address_1":"1108 RUE D'AMBOISE","address_2":"","city":"Saint-Jerome","province":"QC","country":"Canada","postcode":"J5L0E1","buzz_code":"","latitude":"45.797655","longitude":"-74.049801","name":"X","email":"","telephone":"","tracking_number":"SR270017412103","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":2,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"allow_dropoff":1,"driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"1108 RUE D'AMBOISE,Saint-Jerome,QC,J5L0E1","operation_mode":0,"is_multiple":1,"total_orders":3,"current_order":1},{"id":299546,"type":"D","order_type":"D","is_p2p":0,"is_locked":0,"ref":1231,"address_1":"1108 RUE D'AMBOISE","address_2":"","city":"Saint-Jerome","province":"QC","country":"Canada","postcode":"J5L0E1","buzz_code":"","latitude":"45.797655","longitude":"-74.049801","name":"","email":"","telephone":"","tracking_number":"SR662910478770","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":3,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"allow_dropoff":1,"driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"1108 RUE D'AMBOISE,Saint-Jerome,QC,J5L0E1","operation_mode":0,"is_multiple":1,"total_orders":3,"current_order":2},{"id":299547,"type":"P","order_type":"D","is_p2p":0,"is_locked":0,"ref":123,"address_1":"6701 RUE HADLEY","address_2":"","city":"Montreal","province":"QC","country":"Canada","postcode":"H4E3R3","buzz_code":"","latitude":"45.452116","longitude":"-73.591895","name":"X","email":null,"telephone":null,"tracking_number":"SR329762240553","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":4,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"allow_dropoff":1,"driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"1108 RUE D'AMBOISE,Saint-Jerome,QC,J5L0E1","operation_mode":0,"is_multiple":1,"total_orders":3,"current_order":3},{"id":299545,"type":"D","order_type":"P2P","is_p2p":1,"is_locked":1,"ref":"T1","address_1":"6701 rue hadley","address_2":"","city":"Montreal","province":"QC","country":"Canada","postcode":"H4E3R3","buzz_code":"","latitude":"45.452116","longitude":"-73.591895","name":"x","email":"","telephone":"","tracking_number":"SR904766214130","external_tracking_number":"","note":"","driver_alias":"pd1","stop_number":5,"driver_id":343,"leg_number":"L-1","status":"Already Planned","packages":1,"notification_language":"en","return_reason_id":null,"orders_status_id":5,"current_route_id":3964,"allow_dropoff":1,"driverNotes":[],"files":{"photo_urls":[],"signature_urls":[]},"is_finished":0,"is_postponed":0,"full_address":"6701 rue hadley,Montreal,QC,H4E3R3","operation_mode":0,"is_multiple":1,"total_orders":2,"current_order":2}]}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/client/routes/replace-driver":{"post":{"tags":["Client"],"summary":"Replace a driver from an existing route","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostReplaceDriver"}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"message":"success"}}}},"400":{"description":"Bad Request"},"401":{"description":"Not Auth"}},"security":[{"bearerAuth":[]}]}},"/v1/client/routes/add-order":{"post":{"tags":["Client"],"summary":"add order(s) to route","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddOrderToRoute"}}},"required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"driver_id":{"type":"integer","description":"Driver id.\n\n**Details:** Type `integer`."},"added_order_ids":{"type":"array","items":{"type":"integer","description":"Added order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Added order ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"skipped_order_ids":{"type":"array","items":{"type":"integer","description":"Skipped order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Skipped order ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"inserted_after_stop_number":{"type":["integer","null"],"description":"The position that was asked for, echoed back. Null when the orders were appended after the driver's last stop.\n\n**Details:** Type `integer` · Nullable."}}},"example":{"result":true,"message":"Successful","route_id":123,"driver_id":456,"added_order_ids":[1,2,3],"skipped_order_ids":[4,5,6],"inserted_after_stop_number":13}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"422":{"description":"Validation failed, or refused by a recurring pickup route's switches (error_code recurring_pickups.adhoc_pickups_off / recurring_pickups.deliveries_off)","content":{"application/json":{"example":{"message":"This recurring pickup route does not accept ad-hoc pickups. (555001)","errors":{"order_ids":["This recurring pickup route does not accept ad-hoc pickups. (555001)"]},"success":false,"error_code":"recurring_pickups.adhoc_pickups_off"}}}}},"security":[{"bearerAuth":[]}],"description":"A recurring pickup route only takes what its switches allow: an ad-hoc pickup while allow_adhoc_pickups is 0, or a delivery while allow_deliveries is 0, is refused with 422 and error_code recurring_pickups.adhoc_pickups_off or recurring_pickups.deliveries_off (the translated reason is in message / errors.order_ids)."}},"/v1/client/routes/move-order":{"post":{"tags":["Client"],"summary":"move order(s) between route","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveOrderFromRoute"}}},"required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"from_route_id":{"type":"integer","description":"From route id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"to_route_id":{"type":"integer","description":"To route id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"to_driver_id":{"type":"integer","description":"To driver id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"moved_order_ids":{"type":"array","items":{"type":"integer","description":"Moved order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Moved order ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"skipped_order_ids":{"type":"array","items":{"type":"integer","description":"Skipped order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Skipped order ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."}}},"example":{"result":true,"message":"Successful","from_route_id":123,"to_route_id":456,"to_driver_id":110,"moved_order_ids":[1,2,3],"skipped_order_ids":[4,5,6]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"422":{"description":"Validation failed, or refused by a recurring pickup route's switches (error_code recurring_pickups.adhoc_pickups_off / recurring_pickups.deliveries_off)","content":{"application/json":{"example":{"message":"This recurring pickup route does not accept ad-hoc pickups. (555001)","errors":{"order_ids":["This recurring pickup route does not accept ad-hoc pickups. (555001)"]},"success":false,"error_code":"recurring_pickups.adhoc_pickups_off"}}}}},"security":[{"bearerAuth":[]}],"description":"A recurring pickup route only takes what its switches allow: an ad-hoc pickup while allow_adhoc_pickups is 0, or a delivery while allow_deliveries is 0, is refused with 422 and error_code recurring_pickups.adhoc_pickups_off or recurring_pickups.deliveries_off (the translated reason is in message / errors.order_ids)."}},"/v1/client/routes/remove-order":{"post":{"tags":["Client"],"summary":"Remove order(s) from route","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveOrderFromRoute"}}},"required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"deleted_order_ids":{"type":"array","items":{"type":"integer","description":"Deleted order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Deleted order ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"skipped_order_ids":{"type":"array","items":{"type":"integer","description":"Skipped order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Skipped order ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."}}},"example":{"result":true,"message":"Successful","route_id":123,"deleted_order_ids":[1,2,3],"skipped_order_ids":[4,5,6]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/client/routes/optimize":{"post":{"tags":["Client"],"summary":"optimize route","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeRoute"}}},"required":true},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Optimize job is running in background"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/optimize-route":{"post":{"tags":["Driver"],"summary":"optimize route","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeRouteForDriver"}}},"required":true},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Optimize job is running in background"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/client/routes/cancel":{"post":{"tags":["Client"],"summary":"cancel route","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRoute"}}},"required":true},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"message":"Route cancelled successfully"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/client/orders/third-party-handover":{"post":{"tags":["Client"],"summary":"Hand a scanned parcel over to its third-party carrier","description":"One scan takes the parcel out of our warehouse and hands it to the third-party carrier that owns the order. The order must be a live third-party order: an order with no assignment, or one whose assignment was cancelled, rejected or withdrawn to self delivery, is refused. The booking is pushed to the carrier when it has never been pushed, and an already-pushed booking is left alone (a second push would book a second shipment). The scan writes one \"handed over to <provider>\" operation event and one customer-facing in-transit tracking event (status 430) carrying the provider's processing centre as its destination, or no destination when that setting is empty. Scanning a parcel number hands over that parcel; scanning the order ref hands over the whole assignment. Re-scanning an already handed-over parcel reports the current state without recording anything twice.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Required. Scanned identifier: order ref or id, package tracking number, carrier tracking number, package ref or package id.\n\n**Details:** Type `string`."},"note":{"type":["string","null"],"description":"Optional note stored on the handover record. Defaults to \"Handed over to <provider> (warehouse scan)\".\n\n**Details:** Type `string` · Nullable."}},"required":["id"]},"example":{"id":"SR000000001","note":"Loaded on the carrier truck at gate 3"}}},"required":true},"responses":{"200":{"description":"Handed over (or already handed over)","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"scanned_id":{"type":"string","description":"Scanned id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"orders_status_id":{"type":"integer","description":"Order lifecycle status id (`orders.orders_status_id`). Source: `OrdersStatusInput`.\n\nEnum values (from deployed code):\n- `1` — Need Update Address (`need_update_address`)\n- `2` — New Order (`new_order`)\n- `3` — Waiting To Plan (`waiting_to_plan`)\n- `4` — Planning (`planning`)\n- `5` — Already Planned (`already_planned`)\n- `6` — Plan Failed (`plan_failed`)\n- `14` — Already Pickup (`already_pickup`)\n- `8` — Successful (`successful`)\n- `9` — Redelivered Later (`redelivered_later`)\n- `10` — Need Rescheduled (`need_rescheduled`)\n- `11` — Rescheduled (`rescheduled`)\n- `12` — Cancelled (`cancelled`)\n- `16` — Need To Pick Up (`need_to_pick_up`)\n- `7` — Already Pickup (`already_pickup`)\n- `20` — Out For Delivery (`out_for_delivery`)\n- `21` — Out For Pickup (`out_for_pickup`)\n- `17` — Waiting For Self Pickup (`waiting_for_self_pickup`)\n- `19` — Return To Customer (`return_to_customer`)\n- `25` — Hand Off (`hand_off`)\n- `18` — Self Pickup Completed (`self_pickup_completed`)\n- `22` — Partial Received (`partial_received`)\n- `23` — Partial Delivered (`partial_delivered`)\n- `24` — Partial Pickuped (`partial_pickuped`)\n- `26` — Review (`review`)\n- `27` — Destroyed (`destroyed`)\n- `29` — In Transit (`in_transit`)\n- `30` — Package Lost (`package_lost`)\n- `31` — Package Damaged (`package_damaged`)\n- `32` — Waiting Customer Options (`waiting_customer_options`)\n- `33` — Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)\n- `34` — Waiting Batch Pickup (`waiting_batch_pickup`)\n- `28` — Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)\n- `35` — Payment Required (`payment_required`)\n- `36` — Bulk Transshipment Pending (`bulk_transshipment_pending`)\n- `37` — Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)\n- `38` — Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)\n- `39` — Inbound Scan Required (`inbound_scan_required`)\n- `40` — Rejected By Recipient (`rejected_by_recipient`)\n- `41` — Package Outbound (`package_outbound`)\n- `42` — Waiting For Quote (`waiting_for_quote`)\n- `43` — Waiting Third Party Handover (`waiting_third_party_handover`)\n- `44` — Waiting For Assignment (`waiting_for_assignment`)\n- `45` — Start Pickup (`start_pickup`)\n- `46` — Start Delivery (`start_delivery`)\n- `47` — Out Of Delivery Area (`out_of_delivery_area`)\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5,6,14,8,9,10,11,12,16,7,20,21,17,19,25,18,22,23,24,26,27,29,30,31,32,33,34,28,35,36,37,38,39,40,41,42,43,44,45,46,47],"x-enumDescriptions":["Need Update Address (`need_update_address`)","New Order (`new_order`)","Waiting To Plan (`waiting_to_plan`)","Planning (`planning`)","Already Planned (`already_planned`)","Plan Failed (`plan_failed`)","Already Pickup (`already_pickup`)","Successful (`successful`)","Redelivered Later (`redelivered_later`)","Need Rescheduled (`need_rescheduled`)","Rescheduled (`rescheduled`)","Cancelled (`cancelled`)","Need To Pick Up (`need_to_pick_up`)","Already Pickup (`already_pickup`)","Out For Delivery (`out_for_delivery`)","Out For Pickup (`out_for_pickup`)","Waiting For Self Pickup (`waiting_for_self_pickup`)","Return To Customer (`return_to_customer`)","Hand Off (`hand_off`)","Self Pickup Completed (`self_pickup_completed`)","Partial Received (`partial_received`)","Partial Delivered (`partial_delivered`)","Partial Pickuped (`partial_pickuped`)","Review (`review`)","Destroyed (`destroyed`)","In Transit (`in_transit`)","Package Lost (`package_lost`)","Package Damaged (`package_damaged`)","Waiting Customer Options (`waiting_customer_options`)","Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)","Waiting Batch Pickup (`waiting_batch_pickup`)","Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)","Payment Required (`payment_required`)","Bulk Transshipment Pending (`bulk_transshipment_pending`)","Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)","Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)","Inbound Scan Required (`inbound_scan_required`)","Rejected By Recipient (`rejected_by_recipient`)","Package Outbound (`package_outbound`)","Waiting For Quote (`waiting_for_quote`)","Waiting Third Party Handover (`waiting_third_party_handover`)","Waiting For Assignment (`waiting_for_assignment`)","Start Pickup (`start_pickup`)","Start Delivery (`start_delivery`)","Out Of Delivery Area (`out_of_delivery_area`)"]},"package_id":{"type":["integer","null"],"description":"The scanned parcel, or null when the scan matched the order only.\n\n**Details:** Type `integer` · Nullable."},"assignment_no":{"type":"string","description":"Assignment no. Field in the JSON request body.\n\n**Details:** Type `string`."},"assignment_status":{"type":"string","description":"Assignment status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`."},"provider_id":{"type":"integer","description":"Provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"provider_name":{"type":"string","description":"Provider name. Human-readable label.\n\n**Details:** Type `string`."},"processing_center_name":{"type":["string","null"],"description":"The carrier's processing centre, or null when the provider has none configured.\n\n**Details:** Type `string` · Nullable."},"pushed_now":{"type":"boolean","description":"True when this scan pushed the booking to the carrier; false when it was already pushed.\n\n**Details:** Type `boolean`."},"push_status":{"type":"string","enum":["pending","pushed","failed"],"description":"Allowed values: `pending` · `pushed` · `failed`.\n\n**Details:** Type `string`."},"already_handed_over":{"type":"boolean","description":"True on a re-scan: nothing was recorded again.\n\n**Details:** Type `boolean`."},"handed_count":{"type":"integer","description":"Handed count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"total_count":{"type":"integer","description":"Total count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"assignment_handed_over":{"type":"boolean","description":"True once every parcel of the order has been scanned.\n\n**Details:** Type `boolean`."},"tracking_event_id":{"type":["integer","null"],"description":"Tracking event id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_status_id":{"type":["integer","null"],"description":"430 (in transit).\n\n**Details:** Type `integer` · Nullable."},"tracking_event_destination":{"type":["string","null"],"description":"Destination written on the in-transit event; null when the provider has no processing centre.\n\n**Details:** Type `string` · Nullable."},"operation_event_id":{"type":["integer","null"],"description":"Operation event id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."}}},"example":{"result":true,"message":"Order SR000000001 handed over to Speedy Carrier successfully.","scanned_id":"SR000000001","order_id":1580756,"orders_status_id":33,"package_id":903211,"assignment_no":"TPD20260805052757QZVP4E","assignment_status":"accepted","provider_id":12,"provider_name":"Speedy Carrier","processing_center_name":"Toronto Sorting Center","pushed_now":false,"push_status":"pushed","already_handed_over":false,"handed_count":1,"total_count":1,"assignment_handed_over":true,"tracking_event_id":44120987,"tracking_event_status_id":430,"tracking_event_destination":"Toronto Sorting Center","operation_event_id":88231455}}}},"400":{"description":"No scanned identifier provided"},"404":{"description":"No order of this business matches the scanned identifier"},"422":{"description":"Not a third-party order, the assignment is no longer active, the order status blocks a handover, or the carrier push failed"}}}},"/v1/client/orders/receive-package":{"post":{"tags":["Client"],"summary":"Receive package by given orderId/ref/tracking/externalTracking","parameters":[{"in":"query","name":"search","schema":{"type":"string","description":"orderId/ref/tracking/externalTracking\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Required · Type `string`."},"description":"orderId/ref/tracking/externalTracking\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Required · Type `string`.","required":true},{"in":"query","name":"third_party_action","schema":{"type":"string","enum":["continue_handover","withdraw_self"],"description":"Optional. Only meaningful when the order is still held by a third-party carrier. 'continue_handover' (default when omitted) keeps the carrier and parks the order at Waiting Third Party Handover; 'withdraw_self' cancels the carrier order first and then receives the package back into self-delivery.\n\nAllowed values: `continue_handover` · `withdraw_self`.\n\n**Details:** Optional · Type `string`."},"description":"Optional. Only meaningful when the order is still held by a third-party carrier. 'continue_handover' (default when omitted) keeps the carrier and parks the order at Waiting Third Party Handover; 'withdraw_self' cancels the carrier order first and then receives the package back into self-delivery.\n\nAllowed values: `continue_handover` · `withdraw_self`.\n\n**Details:** Optional · Type `string`.","required":false}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"channel_name":{"type":"string","description":"Channel name. Human-readable label.\n\n**Details:** Type `string`."},"order_status":{"type":"string","description":"Order status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`."},"location_id":{"type":"integer","description":"Location id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"location_name":{"type":"string","description":"Location name. Human-readable label.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."},"third_party_decision":{"type":["object","null"],"description":"Present only when the received order was held by a third-party carrier. Only present for non-customer callers.\n\n**Details:** Type `object` · Nullable.","properties":{"required":{"type":"boolean","description":"True when no third_party_action was sent, so the default was applied and the operator still has to confirm it.\n\n**Details:** Type `boolean`."},"applied":{"type":"string","description":"continue_handover or withdraw_self\n\n**Details:** Type `string`."},"assignment_no":{"type":"string","description":"Assignment no. Field in the JSON request body.\n\n**Details:** Type `string`."},"options":{"type":"array","description":"Selectable actions, default first.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"value":{"type":"string","description":"Value. Field in the JSON request body.\n\n**Details:** Type `string`."},"label":{"type":"string","description":"Label. Human-readable label.\n\n**Details:** Type `string`."}}}}}}}},"example":{"result":true,"message":"Package received successfully","id":1206,"ref":"","channel_name":"","order_status":"New","location_id":239,"location_name":"DEMO","tracking_number":"DEMO","external_tracking_number":"","third_party_decision":{"required":true,"applied":"continue_handover","assignment_no":"TPD20260805052757QZVP4E","options":[{"value":"continue_handover","label":"Continue handover to carrier"},{"value":"withdraw_self","label":"Withdraw to self-delivery"}]}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"channel_name":{"type":"string","description":"Channel name. Human-readable label.\n\n**Details:** Type `string`."},"order_status":{"type":"string","description":"Order status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`."},"location_id":{"type":"integer","description":"Location id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"location_name":{"type":"string","description":"Location name. Human-readable label.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"DEMO","id":1206,"ref":"","channel_name":"","order_status":"New","location_id":239,"location_name":"DEMO","tracking_number":"DEMO","external_tracking_number":""}}}},"401":{"description":"Not Auth","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":""}}}}},"security":[{"bearerAuth":[]}]}},"/v1/client/orders/batch-receive-package":{"post":{"tags":["Client"],"summary":"Receive package by given batch string","parameters":[{"in":"query","name":"order_batch","schema":{"type":"string","description":"Order batch. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."},"required":false,"description":"Order batch. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Order batch abc status has been received"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}},"example":[{"result":false,"message":"Please provider a order batch"},{"result":false,"message":"Can't find any order in order batch abc"}]}}},"401":{"description":"Not Auth","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"You are not authenticated to receive package"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/shipping/getStopNumber":{"post":{"tags":["Shipping"],"summary":"get Stop Number by Order ID/Ref/Tracking Number and routeID","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetStopNumber"},"examples":{"English":{"value":{"route_id":365,"ref":20304,"count_by_sub_route":0}},"example":{"value":{"route_id":365,"ref":20304,"count_by_sub_route":0}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"binary":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/shipping/verifyScan":{"post":{"tags":["Shipping"],"summary":"verification scan: resolve an Order ID/Ref/Tracking Number within a route and count it as verified","description":"The depot's second pass over a sorted route. Same request and the same resolution as /v1/shipping/getStopNumber, but the scan is counted in the stop's verification count instead of its sorting count, and the response reports how much of the route has been verified together with the scanned stop's own sorting and verification counts. Verifying never changes the sorting count.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyScan"},"examples":{"English":{"value":{"route_id":365,"ref":20304,"count_by_sub_route":0}},"example":{"value":{"route_id":365,"ref":20304,"count_by_sub_route":0}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"integer","description":"1 when the scan resolved to a stop.\n\n**Details:** Type `integer`.","examples":[1]},"stopnumber":{"type":"string","description":"Driver alias and stop number.\n\n**Details:** Type `string`.\n\n**Example:** `pd1-3`.","examples":["pd1-3"]},"stop_number":{"type":"integer","description":"The bare stop number. Read this instead of splitting `stopnumber`: a driver alias may itself contain \"-\".\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","examples":[3]},"route_driver_id":{"type":["integer","null"],"description":"The driver's leg of the route (routes_drivers_details id).\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1207`.","examples":[1207]},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `299545`.","examples":[299545]},"packages":{"type":"integer","description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `T1`.","examples":["T1"]},"tracking_number":{"type":["string","null"],"description":"Superroute or carrier tracking number.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `SR904766214130`.","examples":["SR904766214130"]},"store_grid":{"type":["string","null"],"description":"Store grid. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable.","examples":[""]},"note":{"type":"string","description":"Driver alias.\n\n**Details:** Type `string`.\n\n**Example:** `pd1`.","examples":["pd1"]},"route_id":{"type":"integer","description":"The route the scan resolved to.\n\n**Details:** Type `integer`.\n\n**Example:** `3964`.","examples":[3964]},"sorting_scan_count":{"type":"integer","description":"How many times this stop has been sorted at the depot (0 = never sorted).\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"verify_scan_count":{"type":"integer","description":"How many times this stop has now been verified, this scan included.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"orders_verified":{"type":"integer","description":"Stops of the route (or of the driver's leg when count_by_sub_route is 1) verified at least once.\n\n**Details:** Type `integer`.\n\n**Example:** `12`.","examples":[12]},"orders_unverified":{"type":"integer","description":"Stops still to verify. Pickup stops are not counted.\n\n**Details:** Type `integer`.\n\n**Example:** `5`.","examples":[5]},"orders_total":{"type":"integer","description":"All stops of the route (or leg).\n\n**Details:** Type `integer`.\n\n**Example:** `17`.","examples":[17]}}},"example":{"result":1,"stopnumber":"pd1-3","stop_number":3,"route_driver_id":1207,"order_id":299545,"packages":1,"ref":"T1","tracking_number":"SR904766214130","store_grid":"","note":"pd1","route_id":3964,"sorting_scan_count":1,"verify_scan_count":1,"orders_verified":12,"orders_unverified":5,"orders_total":17}}}},"400":{"description":"Bad Request: the ref is not on the route (`message`: No results found)."}},"security":[{"bearerAuth":[]}]}},"/v1/labelservice/getShippingLabel":{"post":{"tags":["LabelService"],"summary":"download Shipping Label pdf by Order ID or Tracking Number or Third Party Tracking Number","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetShippingLabel"},"examples":{"ORDER_ID":{"value":{"id":17341,"type":"ORDER_ID","rate_id":"rat_xxxx","base64":0}},"TRACKING_NUMBER":{"value":{"id":17341,"type":"TRACKING_NUMBER","rate_id":"rat_xxxx","base64":0}},"THIRD_PARTY_TRACKING_NUMBER":{"value":{"id":17341,"type":"THIRD_PARTY_TRACKING_NUMBER","rate_id":"rat_xxxx","base64":0}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"binary":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"400":{"description":"Bad Request A customer with Auto Pause Label Service enabled is refused when balance + credit does not cover the label: `message` keeps its historical literal `Insufficient balance available`, and an `insufficient_balance` block carries the shortfall and the available top-up channels.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"code":{"type":"string","description":"`INSUFFICIENT_BALANCE` when the refusal was a balance one; `OUT_OF_DELIVERY_AREA` when the delivery address is outside the delivery area and the business setting deletes such orders.\n\n**Details:** Type `string`.","examples":["INSUFFICIENT_BALANCE"]},"insufficient_balance":{"$ref":"#/components/schemas/InsufficientBalance","description":"Insufficient balance. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `InsufficientBalance`."}}},"example":{"message":"Insufficient balance available","code":"INSUFFICIENT_BALANCE","insufficient_balance":{"msg":"Insufficient balance available","balance":7,"code":"INSUFFICIENT_BALANCE","message":"This charge is $12.00, but only $5.00 is available on your account. You are $7.00 short.","required":12,"available":5,"shortfall":7,"currency":"CAD","currency_symbol":"$","can_pay_online":true,"max_online_amount":null,"exceeds_max_online_amount":false,"channels":[{"id":"stripe:card","gateway":"stripe","method":"card","value":"card","display_name":"Credit / Debit Card","icon":"fas fa-credit-card","requires_saved_card":true}],"add_funds_url":"https://app.superroute.ca/payment/invoice?token=..."}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/shipping/getShippingLabel":{"post":{"tags":["Shipping"],"summary":"get Shipping Label (pdf or base64) by Order ID/Ref/Tracking Number","description":"The response shape depends on the `base64` flag. With `base64: 0` (the default) the body is the raw PDF file stream sent as `Content-Type: application/pdf`, so it must not be parsed as JSON. With `base64: 1` the body is `Content-Type: application/json` and its value is a top-level JSON **string** holding the base64-encoded PDF, for example `\"JVBERi0xLjcK...\"`. It is not a JSON object, so there is no `pdf_data` field and clients that require a top-level object (org.json JSONObject, .NET JObject.Parse, Go unmarshalling into a map) will reject it. Decode the parsed string directly, or call `POST /v2/shipping/getShippingLabel`, which returns the same PDF inside a regular JSON object and is recommended for new integrations.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetShippingLabel"},"examples":{"ORDER_ID":{"value":{"id":17341,"type":"ORDER_ID","packages":1,"hide_sender_address":0,"hide_receiver_address":0,"base64":0}},"REF":{"value":{"id":282355,"type":"REF","packages":1,"hide_sender_address":0,"hide_receiver_address":0,"base64":0}},"TRACKING_NUMBER":{"value":{"id":"SR672874166828","type":"TRACKING_NUMBER","packages":1,"hide_sender_address":0,"hide_receiver_address":0,"base64":0}},"EXTERNAL_TRACKING_NUMBER":{"value":{"id":"NZ203132001","type":"EXTERNAL_TRACKING_NUMBER","packages":1,"hide_sender_address":0,"hide_receiver_address":0,"base64":0}},"example":{"value":{"id":"SR672874166828","type":"TRACKING_NUMBER","packages":1,"hide_sender_address":0,"hide_receiver_address":0,"base64":0}}}}},"required":true},"responses":{"200":{"description":"successful operation. `base64: 0` returns the binary PDF stream; `base64: 1` returns a top-level JSON string containing the base64-encoded PDF, not an object.","content":{"application/pdf":{"schema":{"type":"string","description":"Returned when base64 is 0 or omitted.","contentMediaType":"application/octet-stream"}},"application/json":{"schema":{"type":"string","description":"Returned when base64 is 1. The whole response body is a single JSON string holding the base64-encoded PDF, a top-level scalar rather than an object."},"example":"JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZwo...."}}},"400":{"description":"Bad Request. Every guard returns the same envelope: `result` is always false and `message` carries the reason (`Type invaild.` keeps its historical spelling, `Not Auth`, `Packages need >= 1`, or the order-lookup message).","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Not Auth`.","examples":["Not Auth"]}}},"example":{"result":false,"message":"Not Auth"}}}}},"security":[{"bearerAuth":[]}]}},"/v2/shipping/getShippingLabel":{"post":{"tags":["Shipping"],"summary":"get Shipping Label (base64 Only) by Order ID/Ref/Tracking Number","description":"For label-service (carrier) orders the carrier's official label PDF is returned in pdf_data (generating it on first call); label_code is empty and the packages parameter is ignored for these orders because the package count is fixed by the carrier submission. For all other orders the label is rendered from the order data and the optional packages parameter adjusts the order's package count. Unlike /v1/shipping/getShippingLabel this endpoint always answers with a JSON object, so pdf_data can be read as an ordinary field.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetShippingLabel"},"examples":{"ORDER_ID":{"value":{"id":17341,"type":"ORDER_ID","packages":1,"hide_sender_address":0,"hide_receiver_address":0}},"REF":{"value":{"id":282355,"type":"REF","packages":1,"hide_sender_address":0,"hide_receiver_address":0}},"TRACKING_NUMBER":{"value":{"id":"SR672874166828","type":"TRACKING_NUMBER","packages":1,"hide_sender_address":0,"hide_receiver_address":0}},"EXTERNAL_TRACKING_NUMBER":{"value":{"id":"NZ203132001","type":"EXTERNAL_TRACKING_NUMBER","packages":1,"hide_sender_address":0,"hide_receiver_address":0}},"example":{"value":{"id":"SR672874166828","type":"TRACKING_NUMBER","packages":1,"hide_sender_address":0,"hide_receiver_address":0}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"label_code":{"type":"string","description":"Sorting/region code for the destination postcode. Always a string: the empty string when the shipping method defines no regions, or when the destination postcode matches none of them.\n\n**Details:** Type `string`.\n\n**Example:** `Mar`.","examples":["Mar"]},"tracking_numbers":{"type":"array","items":{"type":"string","description":"Tracking numbers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Tracking numbers. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"pdf_data":{"type":"string","description":"Pdf data. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"result":true,"label_code":"Mar","tracking_numbers":["FE10931581DEMO"],"pdf_data":"JVBERi...."}}}},"400":{"description":"Bad Request. Every guard returns the same envelope: `result` is always false and `message` carries the reason (`Type invaild.` keeps its historical spelling, `Not Auth`, `Packages need >= 1`, or the order-lookup message).","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Not Auth`.","examples":["Not Auth"]}}},"example":{"result":false,"message":"Not Auth"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/labelservice/getShippingMethodList":{"post":{"tags":["LabelService"],"summary":"get Shipping Method List","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"detail":{"type":"boolean","description":"Detail. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}},"examples":{"ID":{"value":{"id":8,"detail":true}}}}},"required":false},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"unique_identifier":{"type":"string","description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"options":{"type":"object","properties":{"signature_option":{"type":"boolean","description":"Signature option. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"insurance_option":{"type":"boolean","description":"Insurance option. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"insurance_value":{"type":"boolean","description":"Insurance amount for the package or order in the business currency.\n\n**Details:** Type `boolean`."},"multi_package":{"type":"boolean","description":"Multi package. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Options. Field in the JSON request body.\n\n**Details:** Type `object`."},"package_type":{"type":"object","properties":{"parcel":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"options":{"type":"object","properties":{"weight_options":{"type":"boolean","description":"Weight options. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `boolean`."},"dimension_options":{"type":"boolean","description":"Dimension options. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `boolean`."},"signature_option":{"type":"boolean","description":"Signature option. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"insurance_option":{"type":"boolean","description":"Insurance option. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"insurance_value":{"type":"boolean","description":"Insurance amount for the package or order in the business currency.\n\n**Details:** Type `boolean`."},"multi_package":{"type":"boolean","description":"Multi package. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Options. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Parcel. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Package handling type. Source: `PackageTypeInput`.\n\nEnum values (from deployed code):\n- `parcel` — Parcel\n- `pallet` — Pallet\n\n**Details:** Type `object`.","enum":["parcel","pallet"],"x-enumDescriptions":["Parcel","Pallet"]},"from_contry_limit":{"type":"array","items":{"type":"string","description":"From contry limit. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"From contry limit. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"allowManualShippingFromAddress":{"type":"integer","description":"Allow manual shipping from address. Address component used for geocoding and delivery.\n\n**Details:** Type `integer`."},"isUploadMethod":{"type":"boolean","description":"Is upload method. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `boolean`."},"services":{"type":"object","properties":{"stamps_com":{"type":"object","properties":{"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"carrier_code":{"type":"string","description":"Carrier code. Stable machine-readable code.\n\n**Details:** Type `string`."},"accounts":{"type":"object","properties":{"6bluinc":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Account number. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"requiresFundedAccount":{"type":"boolean","description":"Requires funded account. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `boolean`."},"balance":{"type":"number","description":"Balance. Field in the JSON request body.\n\n**Details:** Type `number`."},"nickname":{"type":"string","description":"Nickname. Human-readable label.\n\n**Details:** Type `string`."},"shippingProviderId":{"type":"integer","description":"Shipping provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"primary":{"type":"boolean","description":"Primary. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"6bluinc. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Accounts. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"services":{"type":"array","items":{"type":"object","properties":{"service_name":{"type":"string","description":"Service name. Human-readable label.\n\n**Details:** Type `string`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."}}},"description":"Services. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Stamps com. Field in the JSON request body.\n\n**Details:** Type `object`."},"ups":{"type":"object","properties":{"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"carrier_code":{"type":"string","description":"Carrier code. Stable machine-readable code.\n\n**Details:** Type `string`."},"accounts":{"type":"object","properties":{"7Y76F9":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Account number. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"requiresFundedAccount":{"type":"boolean","description":"Requires funded account. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `boolean`."},"balance":{"type":"integer","description":"Balance. Field in the JSON request body.\n\n**Details:** Type `integer`."},"nickname":{"type":["string","null"],"description":"Nickname. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"shippingProviderId":{"type":"integer","description":"Shipping provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"primary":{"type":"boolean","description":"Primary. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"7y76f9. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Accounts. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"services":{"type":"array","items":{"type":"object","properties":{"service_name":{"type":"string","description":"Service name. Human-readable label.\n\n**Details:** Type `string`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."}}},"description":"Services. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Ups. Field in the JSON request body.\n\n**Details:** Type `object`."},"fedex":{"type":"object","properties":{"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"carrier_code":{"type":"string","description":"Carrier code. Stable machine-readable code.\n\n**Details:** Type `string`."},"accounts":{"type":"object","properties":{"202998649":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Account number. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"requiresFundedAccount":{"type":"boolean","description":"Requires funded account. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `boolean`."},"balance":{"type":"integer","description":"Balance. Field in the JSON request body.\n\n**Details:** Type `integer`."},"nickname":{"type":"string","description":"Nickname. Human-readable label.\n\n**Details:** Type `string`."},"shippingProviderId":{"type":"integer","description":"Shipping provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"primary":{"type":"boolean","description":"Primary. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"202998649. Field in the JSON request body.\n\n**Details:** Type `object`."},"692474880":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Account number. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"requiresFundedAccount":{"type":"boolean","description":"Requires funded account. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `boolean`."},"balance":{"type":"integer","description":"Balance. Field in the JSON request body.\n\n**Details:** Type `integer`."},"nickname":{"type":"string","description":"Nickname. Human-readable label.\n\n**Details:** Type `string`."},"shippingProviderId":{"type":"integer","description":"Shipping provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"primary":{"type":"boolean","description":"Primary. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"692474880. Field in the JSON request body.\n\n**Details:** Type `object`."},"727214917":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Account number. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"requiresFundedAccount":{"type":"boolean","description":"Requires funded account. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `boolean`."},"balance":{"type":"integer","description":"Balance. Field in the JSON request body.\n\n**Details:** Type `integer`."},"nickname":{"type":"string","description":"Nickname. Human-readable label.\n\n**Details:** Type `string`."},"shippingProviderId":{"type":"integer","description":"Shipping provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"primary":{"type":"boolean","description":"Primary. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"727214917. Field in the JSON request body.\n\n**Details:** Type `object`."},"886388977":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Account number. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"requiresFundedAccount":{"type":"boolean","description":"Requires funded account. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `boolean`."},"balance":{"type":"integer","description":"Balance. Field in the JSON request body.\n\n**Details:** Type `integer`."},"nickname":{"type":["string","null"],"description":"Nickname. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"shippingProviderId":{"type":"integer","description":"Shipping provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"primary":{"type":"boolean","description":"Primary. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"886388977. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Accounts. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"services":{"type":"array","items":{"type":"object","properties":{"service_name":{"type":"string","description":"Service name. Human-readable label.\n\n**Details:** Type `string`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."}}},"description":"Services. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Fedex. Field in the JSON request body.\n\n**Details:** Type `object`."},"dhl_global_mail":{"type":"object","properties":{"carrier_name":{"type":"string","description":"Carrier name. Human-readable label.\n\n**Details:** Type `string`."},"carrier_code":{"type":"string","description":"Carrier code. Stable machine-readable code.\n\n**Details:** Type `string`."},"accounts":{"type":"object","properties":{"tsujpxshZmgrNgcZ1sQzmXo7JumLgcVM-5384291":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Account number. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"requiresFundedAccount":{"type":"boolean","description":"Requires funded account. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `boolean`."},"balance":{"type":"integer","description":"Balance. Field in the JSON request body.\n\n**Details:** Type `integer`."},"nickname":{"type":"string","description":"Nickname. Human-readable label.\n\n**Details:** Type `string`."},"shippingProviderId":{"type":"integer","description":"Shipping provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"primary":{"type":"boolean","description":"Primary. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Tsujpxsh zmgr ngc z1s qzm xo7jum lgc vm 5384291. Field in the JSON request body.\n\n**Details:** Type `object`."},"tsujpxshZmgrNgcZ1sQzmXo7JumLgcVM-5389529":{"type":"object","properties":{"accountNumber":{"type":"string","description":"Account number. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"requiresFundedAccount":{"type":"boolean","description":"Requires funded account. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `boolean`."},"balance":{"type":"integer","description":"Balance. Field in the JSON request body.\n\n**Details:** Type `integer`."},"nickname":{"type":"string","description":"Nickname. Human-readable label.\n\n**Details:** Type `string`."},"shippingProviderId":{"type":"integer","description":"Shipping provider id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"primary":{"type":"boolean","description":"Primary. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Tsujpxsh zmgr ngc z1s qzm xo7jum lgc vm 5389529. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Accounts. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"services":{"type":"array","items":{"type":"object","properties":{"service_name":{"type":"string","description":"Service name. Human-readable label.\n\n**Details:** Type `string`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."}}},"description":"Services. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Dhl global mail. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Services. Field in the JSON request body.\n\n**Details:** Type `object`."},"shippingFromList":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"unique_identifier":{"type":"integer","description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"company":{"type":"string","description":"Company. Field in the JSON request body.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"address_type":{"type":"integer","description":"Address type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."}}},"description":"Shipping from list. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}},"example":[{"id":13,"name":"example","unique_identifier":"example","options":{"signature_option":false,"insurance_option":false,"insurance_value":false,"multi_package":true},"package_type":{"parcel":{"name":"Parcel","options":{"weight_options":true,"dimension_options":true,"signature_option":true,"insurance_option":true,"insurance_value":true,"multi_package":true}}},"from_contry_limit":[],"allowManualShippingFromAddress":0,"isUploadMethod":false,"services":{"stamps_com":{"carrier_name":"Stamps.com","carrier_code":"stamps_com","accounts":{"6bluinc":{"accountNumber":"example","requiresFundedAccount":true,"balance":421.78,"nickname":"example","shippingProviderId":238436,"primary":true}},"services":[{"service_name":"USPS Priority Mail","service_code":"usps_priority_mail"},{"service_name":"USPS Priority Mail Express","service_code":"usps_priority_mail_express"},{"service_name":"USPS Parcel Select Ground","service_code":"usps_parcel_select"},{"service_name":"USPS First Class Mail","service_code":"usps_first_class_mail"},{"service_name":"USPS Media Mail","service_code":"usps_media_mail"},{"service_name":"USPS Ground Advantage","service_code":"usps_ground_advantage"},{"service_name":"USPS Priority Mail Intl","service_code":"usps_priority_mail_international"},{"service_name":"USPS Priority Mail Express Intl","service_code":"usps_priority_mail_express_international"},{"service_name":"USPS First Class Mail Intl","service_code":"usps_first_class_mail_international"},{"service_name":"GlobalPost Economy Intl","service_code":"globalpost_economy"},{"service_name":"GlobalPost Standard Intl","service_code":"globalpost_priority"},{"service_name":"GlobalPost Plus","service_code":"gp_plus"},{"service_name":"GlobalPost Parcel Select SmartSaver","service_code":"globalpost_parcel_select_smart_saver"}]},"ups":{"carrier_name":"UPS","carrier_code":"ups","accounts":{"7Y76F9":{"accountNumber":"example","requiresFundedAccount":false,"balance":0,"nickname":null,"shippingProviderId":270290,"primary":true}},"services":[{"service_name":"UPS Standard®","service_code":"ups_standard_international"},{"service_name":"UPS Next Day Air® Early","service_code":"ups_next_day_air_early_am"},{"service_name":"UPS Ground® (International)","service_code":"ups_ground_international"},{"service_name":"UPS Worldwide Express®","service_code":"ups_worldwide_express"},{"service_name":"UPS Next Day Air®","service_code":"ups_next_day_air"},{"service_name":"UPS Worldwide Express Plus®","service_code":"ups_worldwide_express_plus"},{"service_name":"UPS Next Day Air Saver®","service_code":"ups_next_day_air_saver"},{"service_name":"UPS Worldwide Expedited®","service_code":"ups_worldwide_expedited"},{"service_name":"UPS 2nd Day Air AM®","service_code":"ups_2nd_day_air_am"},{"service_name":"UPS 2nd Day Air® (International)","service_code":"ups_2nd_day_air_international"},{"service_name":"UPS 2nd Day Air®","service_code":"ups_2nd_day_air"},{"service_name":"UPS Worldwide Saver®","service_code":"ups_worldwide_saver"},{"service_name":"UPS 3 Day Select®","service_code":"ups_3_day_select"},{"service_name":"UPS® Ground","service_code":"ups_ground"},{"service_name":"UPS Next Day Air® (International)","service_code":"ups_next_day_air_international"}]},"fedex":{"carrier_name":"FedEx","carrier_code":"fedex","accounts":{"202998649":{"accountNumber":"example","requiresFundedAccount":false,"balance":0,"nickname":"example Innovation","shippingProviderId":363824,"primary":false},"692474880":{"accountNumber":"example","requiresFundedAccount":false,"balance":0,"nickname":"example (1500)","shippingProviderId":335629,"primary":false},"727214917":{"accountNumber":"example","requiresFundedAccount":false,"balance":0,"nickname":"Walmart","shippingProviderId":271257,"primary":false},"886388977":{"accountNumber":"example","requiresFundedAccount":false,"balance":0,"nickname":null,"shippingProviderId":239176,"primary":true}},"services":[{"service_name":"FedEx International Priority Express®","service_code":"fedex_international_priority_express"},{"service_name":"FedEx Ground®","service_code":"fedex_ground"},{"service_name":"FedEx Home Delivery®","service_code":"fedex_home_delivery"},{"service_name":"FedEx 2Day®","service_code":"fedex_2day"},{"service_name":"FedEx 2Day® A.M.","service_code":"fedex_2day_am"},{"service_name":"FedEx Express Saver®","service_code":"fedex_express_saver"},{"service_name":"FedEx Standard Overnight®","service_code":"fedex_standard_overnight"},{"service_name":"FedEx Priority Overnight®","service_code":"fedex_priority_overnight"},{"service_name":"FedEx First Overnight®","service_code":"fedex_first_overnight"},{"service_name":"FedEx 1Day® Freight","service_code":"fedex_1_day_freight"},{"service_name":"FedEx 2Day® Freight","service_code":"fedex_2_day_freight"},{"service_name":"FedEx 3Day® Freight","service_code":"fedex_3_day_freight"},{"service_name":"FedEx First Overnight® Freight","service_code":"fedex_first_overnight_freight"},{"service_name":"FedEx International Ground®","service_code":"fedex_ground_international"},{"service_name":"FedEx International Economy®","service_code":"fedex_international_economy"},{"service_name":"FedEx International Priority®","service_code":"fedex_international_priority"},{"service_name":"FedEx International First®","service_code":"fedex_international_first"},{"service_name":"FedEx International Economy® Freight","service_code":"fedex_international_economy_freight"},{"service_name":"FedEx International Priority® Freight","service_code":"fedex_international_priority_freight"},{"service_name":"FedEx International Connect Plus®","service_code":"fedex_international_connect_plus"}]},"dhl_global_mail":{"carrier_name":"DHL eCommerce","carrier_code":"dhl_global_mail","accounts":{"tsujpxshZmgrNgcZ1sQzmXo7JumLgcVM-5384291":{"accountNumber":"example-5384291","requiresFundedAccount":false,"balance":0,"nickname":"example","shippingProviderId":268324,"primary":true},"tsujpxshZmgrNgcZ1sQzmXo7JumLgcVM-5389529":{"accountNumber":"example-5389529","requiresFundedAccount":false,"balance":0,"nickname":"example","shippingProviderId":379224,"primary":false}},"services":[{"service_name":"DHL SmartMail Parcel Ground","service_code":"smartmail_parcels_ground"},{"service_name":"DHL SmartMail Parcel Expedited","service_code":"smartmail_parcels_expedited"},{"service_name":"DHL Packet International","service_code":"globalmail_packet_priority"},{"service_name":"DHL Globalmail Packet Standard","service_code":"globalmail_packet_standard"},{"service_name":"DHL Packet Plus International","service_code":"globalmail_packet_plus"},{"service_name":"DHL Globalmail Packet IPA","service_code":"globalmail_packet_ipa"},{"service_name":"DHL Globalmail Packet ISAL","service_code":"globalmail_packet_isal"},{"service_name":"DHL Parcel International Priority","service_code":"globalmail_parcel_priority"},{"service_name":"DHL Parcel International Standard","service_code":"globalmail_parcel_standard"},{"service_name":"DHL Parcel International Direct - DDP","service_code":"globalmail_parcel_direct_ddp"},{"service_name":"DHL Parcel International Direct - DDU","service_code":"globalmail_parcel_direct_ddu"},{"service_name":"DHL Parcel International Expedited - DDP","service_code":"globalmail_parcel_direct_express_ddp"},{"service_name":"DHL Parcel International Expedited - DDU","service_code":"globalmail_parcel_direct_express_ddu"},{"service_name":"DHL SmartMail BPM Expedited","service_code":"dhl_smartmail_bpm_expedited"},{"service_name":"DHL SmartMail BPM Ground","service_code":"dhl_smartmail_bpm_ground"},{"service_name":"DHL SM Marketing Parcel Expedited","service_code":"dhl_sm_marketing_parcel_expedited"},{"service_name":"DHL SM Marketing Parcel Ground","service_code":"dhl_sm_marketing_parcel_ground"},{"service_name":"DHL SmartMail Parcel Return Light","service_code":"dhl_smartmail_parcel_return_light"},{"service_name":"DHL SmartMail Parcel Return Plus","service_code":"dhl_smartmail_parcel_return_plus"},{"service_name":"DHL SmartMail Parcel Return Ground","service_code":"dhl_smartmail_parcel_return_ground"},{"service_name":"DHL GlobalMail Business IPA","service_code":"dhl_globalmail_business_ipa"},{"service_name":"DHL SmartMail Parcel Plus Ground","service_code":"smartmail_parcel_plus_ground"},{"service_name":"DHL SmartMail Parcel Plus Expedited","service_code":"smartmail_parcel_plus_expedited"}]}},"shippingFromList":[{"id":124928,"unique_identifier":124928,"name":"example","postcode":"example","address_1":"example","address_2":"example","company":"example","city":"example","province":"example","country":"example","telephone":"example","address_type":1},{"id":129741,"unique_identifier":129741,"name":"example","postcode":"example","address_1":"example","address_2":"example","company":"example","city":"example","province":"example","country":"example","telephone":"example","address_type":1},{"id":169988,"unique_identifier":169988,"name":"example","postcode":"example","address_1":"example","address_2":"example","company":"example","city":"example","province":"example","country":"example","telephone":"example","address_type":1},{"id":196833,"unique_identifier":196833,"name":"example","postcode":"example","address_1":"example","address_2":"example","company":"example","city":"example","province":"example","country":"example","telephone":"example","address_type":1}]}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/labelservice/endofday":{"post":{"tags":["LabelService"],"summary":"submit all shipping information to 3rd party carriers","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"success":{"type":"integer","description":"Success. Field in the JSON request body.\n\n**Details:** Type `integer`."},"failed":{"type":"integer","description":"Failed. Field in the JSON request body.\n\n**Details:** Type `integer`."},"success_ids":{"type":"array","items":{"type":"integer","description":"Success ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Success ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"failed_ids":{"type":"array","items":{"type":"string","description":"Failed ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Failed ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `string`."}}},"example":{"result":true,"success":1,"failed":0,"success_ids":[987231],"failed_ids":[]}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/labelservice/submitShippingInformation":{"post":{"tags":["LabelService"],"summary":"Submit shipping information for one or multiple orders","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"description":"**Required.**\n\nArray of order IDs or single order ID","oneOf":[{"type":"array","items":{"type":"integer","description":"Ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"minItems":1,"description":"Ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer` · minItems `1`."},{"type":"integer","description":"Ids. List of identifiers for the related records.\n\n**Details:** Type `integer`."}]}},"required":["ids"]},"examples":{"Single Order":{"summary":"Submit shipping information for single order","value":{"ids":12345}},"Multiple Orders":{"summary":"Submit shipping information for multiple orders","value":{"ids":[12345,12346,12347]}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Overall operation result\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Summary message\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"total_processed":{"type":"integer","description":"Total number of orders processed\n\n**Details:** Type `integer`."},"success_count":{"type":"integer","description":"Number of successful submissions\n\n**Details:** Type `integer`."},"failure_count":{"type":"integer","description":"Number of failed submissions\n\n**Details:** Type `integer`."},"details":{"type":"array","items":{"type":"object","properties":{"order_id":{"type":"integer","description":"Order ID\n\n**Details:** Type `integer`."},"result":{"type":"boolean","description":"Individual order result\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Individual order message\n\n**Details:** Type `string`."}}},"description":"Details. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"examples":{"Success":{"summary":"Successful batch submission","value":{"result":true,"message":"Processed 3 orders. Success: 2, Failed: 1","data":{"total_processed":3,"success_count":2,"failure_count":1,"details":[{"order_id":12345,"result":true,"message":"Successful"},{"order_id":12346,"result":true,"message":"Successful"},{"order_id":12347,"result":false,"message":"Order not yet created"}]}}}}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Please provide at least one order ID`.","examples":["Please provide at least one order ID"]},"data":{"type":"array","description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`.","examples":[[]]}}}}}},"404":{"description":"No eligible orders found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `No eligible orders found for shipping information submission`.","examples":["No eligible orders found for shipping information submission"]},"data":{"type":"array","description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`.","examples":[[]]}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Batch operation failed: Database connection error`.","examples":["Batch operation failed: Database connection error"]},"data":{"type":"array","description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`.","examples":[[]]}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/batchprocessing/create":{"post":{"operationId":"createbatchprocessing","tags":["BatchProcessing"],"consumes":["multipart/form-data"],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}},"example":{"result":true,"msg":"Successful","id":1}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"result":false,"msg":"Error Message"}}}}},"security":[{"bearerAuth":[]}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Batch Processing Type\n\nType discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`."},"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"The files to upload\n\n**Details:** Type `array`, items `file`."}}}}}}}},"/v1/batchprocessing/result":{"post":{"tags":["BatchProcessing"],"summary":"get batch processing result","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}},"example":{"id":1}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"binary":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/warehouse":{"get":{"operationId":"wmsListWarehouses","tags":["Warehouse"],"parameters":[{"in":"query","name":"includeCustomerWarehouse","schema":{"type":"integer","enum":[0,1],"default":0,"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer` · Default: `0`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer` · Default: `0`."}],"summary":"get warehouse list","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"unique_identifier":{"type":"string","description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"apt":{"type":"string","description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"lat":{"type":"string","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"wms_setting_id":{"type":"integer","description":"Wms setting id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"warehouse_id":{"type":"string","description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `string`."},"territory":{"type":["string","null"],"description":"Territory. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"is_point":{"type":"integer","description":"Is point. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_warehouse":{"type":"integer","description":"Is warehouse. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_default_shipping_from":{"type":"integer","description":"Is default shipping from. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"wms_type":{"type":"string","description":"Wms type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"territory_info":{"type":["string","null"],"description":"Territory info. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}}},"example":[{"id":106,"name":1,"unique_identifier":1,"business_id":333,"description":1,"postcode":"H4E3R3","street_number":6701,"street_name":"RUE HADLEY","apt":"","city":"Montreal","province":"QC","country":"Canada","lat":"45.452116","lng":"-73.591895","telephone":4388780678,"wms_setting_id":4,"warehouse_id":"DYT2","territory":null,"is_point":1,"is_warehouse":1,"status":1,"created_at":"2023-04-06 03:10:55.00","updated_at":"2023-04-09 01:10:56.00","wms_type":"ARMLOGI","territory_info":null}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/getNearestWarehouse":{"post":{"tags":["Warehouse"],"summary":"getNearestWarehouse","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"ids":{"type":"array","items":{"type":"integer","description":"Ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"warehouse_codes":{"type":"array","items":{"type":"string","description":"Warehouse codes. Stable machine-readable code.\n\n**Details:** Type `string`."},"description":"Warehouse codes. Stable machine-readable code.\n\n**Details:** Type `array`, items `string`."},"includeCustomerWarehouse":{"type":"integer","description":"Include customer warehouse. Field in the JSON request body.\n\n**Details:** Type `integer`."}}},"example":{"address_1":"example","address_2":"example","city":"example","province":"example","country":"CA","postcode":"example","ids":[1,2,3],"warehouse_codes":["example-1","example-2"],"includeCustomerWarehouse":0}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"descrption":{"type":"string","description":"Descrption. Field in the JSON request body.\n\n**Details:** Type `string`."},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"lat":{"type":"string","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"distance":{"type":"number","description":"Distance. Field in the JSON request body.\n\n**Details:** Type `number`."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"message":"Successful","data":[{"id":110,"code":"USCA-DF","name":"USCA-DF","descrption":"USCA-DF","address":"1118 rue d'amboise Saint-Jerome QC Canada J5L0E1","telephone":2123123121,"lat":"45.797655","lng":"-74.049801","distance":52385.32},{"id":111,"code":"asdasd","name":"test","descrption":"asdasdsa","address":"985 Brian Good Avenue asdasd Manotick ON 18732885546 K4M 0R3","telephone":123123123,"lat":"45.259113","lng":"-75.690338","distance":165359.62},{"id":112,"code":"TEST","name":"Test","descrption":"Testing warehouse","address":"56 Opera Hts Ottawa Ontario Canada K4M0R2","telephone":1234567899,"lat":"45.257737","lng":"-75.691553","distance":165475.64}]}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/getShippingMethod":{"post":{"tags":["Warehouse"],"summary":"getShippingMethodFromWarehouse","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"warehouse_id":{"type":"string","description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `string`."},"warehouse_code":{"type":"string","description":"Warehouse code. Stable machine-readable code.\n\n**Details:** Type `string`."}}},"example":{"warehouse_id":108,"warehouse_code":"DY2"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"WAYFAIR_UPS_PREPAID":{"type":"string","description":"Wayfair ups prepaid. Identifier referencing the related record.\n\n**Details:** Type `string`."},"WAYFAIR_FEDEX_PREPAID":{"type":"string","description":"Wayfair fedex prepaid. Identifier referencing the related record.\n\n**Details:** Type `string`."},"LTL":{"type":"string","description":"Ltl. Field in the JSON request body.\n\n**Details:** Type `string`."},"FTL":{"type":"string","description":"Ftl. Field in the JSON request body.\n\n**Details:** Type `string`."},"LTL_ARM":{"type":"string","description":"Ltl arm. Field in the JSON request body.\n\n**Details:** Type `string`."},"USPS_PREPAID":{"type":"string","description":"Usps prepaid. Identifier referencing the related record.\n\n**Details:** Type `string`."},"FEDEX_HOME_A127":{"type":"string","description":"Fedex home a127. Field in the JSON request body.\n\n**Details:** Type `string`."},"FEDEX_GROUND_A127":{"type":"string","description":"Fedex ground a127. Field in the JSON request body.\n\n**Details:** Type `string`."},"UPS_GROUND_RES_A127":{"type":"string","description":"Ups ground res a127. Field in the JSON request body.\n\n**Details:** Type `string`."},"UPS_GROUND_COM_A127":{"type":"string","description":"Ups ground com a127. Field in the JSON request body.\n\n**Details:** Type `string`."},"USPS_DNA_PM_A127":{"type":"string","description":"Usps dna pm a127. Field in the JSON request body.\n\n**Details:** Type `string`."},"USPS_DNA_FC_A127":{"type":"string","description":"Usps dna fc a127. Field in the JSON request body.\n\n**Details:** Type `string`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"msg":"Successful","data":{"WAYFAIR_UPS_PREPAID":"WAYFAIR_UPS_PREPAID","WAYFAIR_FEDEX_PREPAID":"WAYFAIR_FEDEX_PREPAID","LTL":"LTL","FTL":"FTL","LTL_ARM":"LTL_ARM","USPS_PREPAID":"USPS_PREPAID","FEDEX_HOME_A127":"FEDEX_HOME_A127","FEDEX_GROUND_A127":"FEDEX_GROUND_A127","UPS_GROUND_RES_A127":"UPS_GROUND_RES_A127","UPS_GROUND_COM_A127":"UPS_GROUND_COM_A127","USPS_DNA_PM_A127":"USPS_DNA_PM_A127","USPS_DNA_FC_A127":"USPS_DNA_FC_A127"}}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/wmsintegration/wms-type":{"get":{"operationId":"wmsIntegrationListTypes","tags":["WMS Integration"],"summary":"get warehouse type list","parameters":[{"in":"query","name":"type","schema":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `HYC`."},"example":"HYC","required":false,"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `HYC`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"HYC":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"fields":{"type":"object","properties":{"apikey":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Apikey. Stable machine-readable code.\n\n**Details:** Type `object`."}},"description":"Fields. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Hyc. Field in the JSON request body.\n\n**Details:** Type `object`."},"ARMLOGI":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"fields":{"type":"object","properties":{"apikey":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Apikey. Stable machine-readable code.\n\n**Details:** Type `object`."}},"description":"Fields. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Armlogi. Field in the JSON request body.\n\n**Details:** Type `object`."},"YUNWMS":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"fields":{"type":"object","properties":{"appToken":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"App token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `object`."},"appKey":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"App key. Stable machine-readable code.\n\n**Details:** Type `object`."},"domain":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Domain. Field in the JSON request body.\n\n**Details:** Type `object`."},"shippingMethod":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Shipping method. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `object`."}},"description":"Fields. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Yunwms. Field in the JSON request body.\n\n**Details:** Type `object`."},"Shipout":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"fields":{"type":"object","properties":{"appKey":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"App key. Stable machine-readable code.\n\n**Details:** Type `object`."},"appSecret":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"App secret. Secret credential — never logged or returned by the API.\n\n**Details:** Type `object`."},"token":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Bearer or one-time token for this flow.\n\n**Details:** Type `object`."},"apiEndpoint":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"method":{"type":"string","description":"Method. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Api endpoint. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Fields. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Shipout. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}},"example":[{"result":true,"message":"Successful","data":{"HYC":{"name":"HYC","fields":{"apikey":{"name":"Api Key","required":true}}},"ARMLOGI":{"name":"Armlogi","fields":{"apikey":{"name":"Api Key","required":true}}},"YUNWMS":{"name":"ECCang","fields":{"appToken":{"name":"App Token","required":true},"appKey":{"name":"App Key","required":true},"domain":{"name":"Domain","required":true},"shippingMethod":{"name":"Shipping Method","required":true}}},"Shipout":{"name":"Shipout","fields":{"appKey":{"name":"App Key","required":true},"appSecret":{"name":"App Secret","required":true},"token":{"name":"Token","required":true},"apiEndpoint":{"name":"Api Endpoint","method":"serverSelecter","required":true}}}}}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/wmsintegration/wms-field":{"get":{"operationId":"wmsIntegrationGetField","tags":["WMS Integration"],"summary":"get warehouse field by id","parameters":[{"in":"query","name":"type","schema":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Required · Type `string`.\n\n**Example:** `Shipout`."},"example":"Shipout","required":true,"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Required · Type `string`.\n\n**Example:** `Shipout`."},{"in":"query","name":"field","schema":{"type":"string","description":"Field. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Required · Type `string`.\n\n**Example:** `apiEndpoint`."},"example":"apiEndpoint","required":true,"description":"Field. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Required · Type `string`.\n\n**Example:** `apiEndpoint`."},{"in":"query","name":"value","schema":{"type":"string","description":"Value. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `https://open.shipout.com/api`."},"example":"https://open.shipout.com/api","required":false,"description":"Value. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `https://open.shipout.com/api`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"string","description":"Data. Field in the JSON request body.\n\n**Details:** Type `string`."}}}},"example":[{"result":true,"message":"Successful","data":"<select name='apiEndpoint' class='form-control'><option value='https://opendev.shipout.com/api' >Sandbox Server</option><option value='https://open.shipout.com/api' selected>Production Server</option></select>"}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/wmsintegration/wms-connect":{"get":{"operationId":"wmsIntegrationGetConnection","tags":["WMS Integration"],"summary":"get wms connect","parameters":[{"in":"query","name":"ids","schema":{"type":"string","description":"Ids. List of identifiers for the related records.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `1,2,3`.","examples":["1,2,3"]},"required":false,"description":"Ids. List of identifiers for the related records.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `1,2,3`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"1":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"unique_identifier":{"type":"string","description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`."},"config":{"type":"object","properties":{"apikey":{"type":"string","description":"Apikey. Stable machine-readable code.\n\n**Details:** Type `string`."}},"description":"Config. Field in the JSON request body.\n\n**Details:** Type `object`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}},"description":"1. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}},"example":[{"result":true,"message":"Successful","data":{"1":{"id":1,"business_id":1,"name":"ARMLOGI","unique_identifier":"ARMLOGI","type":"ARMLOGI","config":{"apikey":23131311231},"status":1}}}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"post":{"operationId":"wmsIntegrationCreateConnection","tags":["WMS Integration"],"summary":"create wms connect","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WMSConnect"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}}},"example":[{"result":true,"message":"Successful","id":7}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"put":{"operationId":"wmsIntegrationUpdateConnection","tags":["WMS Integration"],"summary":"update wms connect","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WMSConnectUpdate"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}},"example":[{"result":true,"message":"Successful"}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"wmsIntegrationDeleteConnection","tags":["WMS Integration"],"summary":"delete wms connect","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WMSConnectDelete"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"empty_record":{"type":"boolean","description":"Empty record. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}},"example":[{"result":true,"empty_record":false,"message":"Successful"}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/wmsintegration/warehouse-list/{id}":{"get":{"operationId":"wmsIntegrationListWarehouses","tags":["WMS Integration"],"summary":"get wms connect","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource identifier.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}},"example":[{"result":true,"message":"Successful","data":[{"id":"w1","name":"Warehouse 1"},{"id":"w2","name":"Warehouse 2"}]}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/inventory":{"post":{"operationId":"wmsListInventory","tags":["Warehouse"],"summary":"get inventory list","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","description":"Stock keeping unit / product code.\n\n**Details:** Type `string`."},"warehouse_ids":{"type":"array","items":{"type":"integer","description":"Warehouse ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Warehouse ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"warehouses":{"type":"array","items":{"type":"string","description":"Warehouses. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Warehouses. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}}},"examples":{"English":{"value":{"sku":"TEST001","warehouse_ids":[1,2,3],"warehouses":["DYT2"]}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":[{"result":true,"msg":"Successful","data":{"TEST001":{"DYT2":{"on_hand":0,"on_transit":14}}}}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/submitInboundRequest":{"post":{"tags":["Warehouse"],"summary":"submit a new inbound request","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"warehouse_id":{"type":"integer","description":"Required. Warehouse ID for the inbound request.\n\n**Details:** Type `integer`."},"warehouse_code":{"type":"string","description":"Warehouse code. Stable machine-readable code.\n\n**Details:** Type `string`."},"shipping_type":{"type":"integer","description":"Shipping type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"container_type":{"type":"integer","description":"Container type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"eta":{"type":"string","description":"Eta. Field in the JSON request body.\n\n**Details:** Type `string`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."},"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"length":{"type":"integer","description":"Length dimension.\n\n**Details:** Type `integer`."},"width":{"type":"integer","description":"Width dimension.\n\n**Details:** Type `integer`."},"height":{"type":"integer","description":"Height dimension.\n\n**Details:** Type `integer`."},"package_note":{"type":"string","description":"Package note. Free-text note.\n\n**Details:** Type `string`."},"insurance_value":{"type":"number","description":"Insurance amount for the package or order in the business currency.\n\n**Details:** Type `number`."},"submit":{"type":"integer","description":"Submit. Field in the JSON request body.\n\n**Details:** Type `integer`."},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`."},"unit_price":{"type":"number","description":"Unit price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"origin":{"type":"string","description":"Origin. Field in the JSON request body.\n\n**Details:** Type `string`."},"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"sku":{"type":"string","description":"Stock keeping unit / product code.\n\n**Details:** Type `string`."},"barcode":{"type":"string","description":"Barcode. Stable machine-readable code.\n\n**Details:** Type `string`."},"unit":{"type":"string","description":"Unit. Field in the JSON request body.\n\n**Details:** Type `string`."},"hscode":{"type":"string","description":"Hscode. Stable machine-readable code.\n\n**Details:** Type `string`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."}}},"description":"Optional. Array of items to receive.\n\n**Details:** Type `array`, items `object`."},"packages":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"length":{"type":"integer","description":"Length dimension.\n\n**Details:** Type `integer`."},"width":{"type":"integer","description":"Width dimension.\n\n**Details:** Type `integer`."},"height":{"type":"integer","description":"Height dimension.\n\n**Details:** Type `integer`."},"insurance_value":{"type":"number","description":"Insurance amount for the package or order in the business currency.\n\n**Details:** Type `number`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`."},"unit_price":{"type":"number","description":"Unit price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"origin":{"type":"string","description":"Origin. Field in the JSON request body.\n\n**Details:** Type `string`."},"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"unit":{"type":"string","description":"Unit. Field in the JSON request body.\n\n**Details:** Type `string`."},"sku":{"type":"string","description":"Stock keeping unit / product code.\n\n**Details:** Type `string`."},"barcode":{"type":"string","description":"Barcode. Stable machine-readable code.\n\n**Details:** Type `string`."},"hscode":{"type":"string","description":"Hscode. Stable machine-readable code.\n\n**Details:** Type `string`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."}}},"description":"Items. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"signature_option":{"type":"integer","description":"Signature option. Field in the JSON request body.\n\n**Details:** Type `integer`."},"insurance_option":{"type":"integer","description":"Insurance option. Field in the JSON request body.\n\n**Details:** Type `integer`."},"schedule_date":{"type":"string","description":"Schedule date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`."},"notification_language":{"type":"string","description":"Notification language. Field in the JSON request body.\n\n**Details:** Type `string`."},"shipping_from":{"type":"string","description":"Address-book / warehouse id used as the sender location; when set, most sender_* fields can be omitted.\n\n**Details:** Type `string`."},"shipping_from_code":{"type":"string","description":"Sender address book Unique Identifier - the same record shipping_from names by id. Supply either parameter; shipping_from wins when both are given.\n\n**Details:** Type `string`."},"sender_name":{"type":"string","description":"Sender name. Human-readable label.\n\n**Details:** Type `string`."},"sender_address_1":{"type":"string","description":"Sender address 1. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"sender_address_2":{"type":"string","description":"Sender address 2. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"sender_address_type":{"type":"integer","description":"Sender address type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"sender_postcode":{"type":"string","description":"Sender postcode. Stable machine-readable code.\n\n**Details:** Type `string`."},"sender_city":{"type":"string","description":"Sender city. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"sender_province":{"type":"string","description":"Sender province. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"sender_country":{"type":"string","description":"Sender country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`."},"sender_company_name":{"type":"string","description":"Sender company name. Human-readable label.\n\n**Details:** Type `string`."},"sender_email":{"type":"string","description":"Sender email. Email address.\n\n**Details:** Type `string`."},"sender_telephone":{"type":"string","description":"Sender telephone. Phone number in local or E.164 form.\n\n**Details:** Type `string`."},"sender_buzz_code":{"type":"string","description":"Sender buzz code. Stable machine-readable code.\n\n**Details:** Type `string`."},"shipping_method":{"type":"integer","description":"Shipping method. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"order_batch":{"type":"string","description":"Order batch. Field in the JSON request body.\n\n**Details:** Type `string`."}},"required":["warehouse_id"]},"examples":{"English":{"value":{"warehouse_id":1,"warehouse_code":"COI8","shipping_type":3,"container_type":1,"eta":"2023-11-06","note":"customer note","weight":1,"length":1,"width":1,"height":1,"package_note":"package notes","insurance_value":200,"submit":1,"items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","sku":"SKU001","barcode":1321312321,"unit":"PCS","hscode":8009201332,"description":"Product 1 description"}],"packages":[{"weight":1000,"length":300,"width":200,"height":100,"insurance_value":200,"note":"package note","items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1321312321,"hscode":8009201332,"description":"Product 1 description"}]}],"signature_option":1,"insurance_option":1,"schedule_date":"2021-04-05 00:00:00","notification_language":"en","shipping_from":"87 (if want to manual set sender address, please leave it empty or null)","shipping_from_code":"WH-TORONTO (address book Unique Identifier; alternative to shipping_from - supply either one, shipping_from wins when both are given)","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"shipping_method":2,"order_batch":"2021-08-23"}},"example":{"value":{"warehouse_id":1,"warehouse_code":"COI8","shipping_type":3,"container_type":1,"eta":"2023-11-06","note":"customer note","weight":1,"length":1,"width":1,"height":1,"package_note":"(包裹备注，当PACKAGES为空时有效)","submit":1,"items":[{"name":"Product 1","quantity":1,"unit_price":"1.48","origin":"CA","weight":1000,"currency":"CAD","sku":"SKU001","barcode":1321312321,"unit":"PCS","hscode":8009201332,"description":"Product 1 description"}],"packages":[{"weight":1000,"length":300,"width":200,"height":100,"insurance_value":"200.00","note":"包裹备注（可选）","items":[{"name":"Product 1","quantity":1,"unit_price":"1.48","origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","hscode":8009201332,"description":"Product 1 description"}]}],"signature_option":1,"insurance_option":1,"insurance_value":"200.00","schedule_date":"2021-04-05","notification_language":"fr","shipping_from":87,"shipping_from_code":"WH-TORONTO","sender_name":"test","sender_address_1":"6701 RUE HADLEY","sender_address_2":"(发件人地址2,如果发出地编号为空时，本字段选填）","sender_address_type":1,"sender_postcode":"H4E3R3","sender_city":"Montreal","sender_province":"QC","sender_country":"CA","sender_company_name":"Super Route","sender_email":"info@gmail.com","sender_telephone":666666666,"sender_buzz_code":5151,"shipping_method":2,"order_batch":"2021-08-23"}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"sync_status":{"type":"integer","description":"Sync status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `integer`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"inbound_order_id":{"type":"string","description":"Inbound order id. Identifier referencing the related record.\n\n**Details:** Type `string`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"msg":"Successful","data":{"sync_status":2,"order_id":103896,"inbound_order_id":"IN-230418-WSRR0030"}}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/cancelInboundRequest":{"post":{"tags":["Warehouse"],"summary":"Cancel Inbound Request","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}},"examples":{"ID":{"value":{"id":17832}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Successful"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/getInboundRequestDetail":{"post":{"tags":["Warehouse"],"summary":"Get Inbound Request Detail","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}},"examples":{"ID":{"value":{"id":17832}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"status_text":{"type":"string","description":"Status text. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`."},"packages":{"type":"array","items":{"type":"object","properties":{"package_id":{"type":"integer","description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"items":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"integer","description":"Item id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"sku":{"type":"string","description":"Stock keeping unit / product code.\n\n**Details:** Type `string`."},"barcode":{"type":"string","description":"Barcode. Stable machine-readable code.\n\n**Details:** Type `string`."},"qty":{"type":"integer","description":"Qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"quantity_received":{"type":"integer","description":"Quantity received. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}}},"description":"Items. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","description":"Stock keeping unit / product code.\n\n**Details:** Type `string`."},"barcode":{"type":"string","description":"Barcode. Stable machine-readable code.\n\n**Details:** Type `string`."},"qty":{"type":"integer","description":"Qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"quantity_received":{"type":"integer","description":"Quantity received. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}}},"description":"Items. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"msg":"Successful","data":{"status":7,"status_text":"Review","packages":[{"package_id":134650,"items":[{"item_id":86,"sku":"SKU1","barcode":1321312321,"qty":1,"quantity_received":0}]}],"items":[{"sku":"SKU1","barcode":1321312321,"qty":1,"quantity_received":0}]}}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/submitOutboundRequest":{"post":{"tags":["Warehouse"],"summary":"submit a new outbound request","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"warehouse_id":{"type":"integer","description":"Required. Warehouse ID for the outbound request.\n\n**Details:** Type `integer`."},"warehouse_code":{"type":"string","description":"Warehouse code. Stable machine-readable code.\n\n**Details:** Type `string`."},"shipping_type":{"type":"integer","description":"Shipping type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"container_type":{"type":"integer","description":"Container type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"shipping_method":{"type":"string","description":"Shipping method. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"carrier":{"type":"string","description":"Carrier. Field in the JSON request body.\n\n**Details:** Type `string`."},"service":{"type":"string","description":"Service. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"shipping_label":{"type":"string","description":"Shipping label. Human-readable label.\n\n**Details:** Type `string`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."},"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"length":{"type":"integer","description":"Length dimension.\n\n**Details:** Type `integer`."},"width":{"type":"integer","description":"Width dimension.\n\n**Details:** Type `integer`."},"height":{"type":"integer","description":"Height dimension.\n\n**Details:** Type `integer`."},"package_note":{"type":"string","description":"Package note. Free-text note.\n\n**Details:** Type `string`."},"insurance_value":{"type":"number","description":"Insurance amount for the package or order in the business currency.\n\n**Details:** Type `number`."},"submit":{"type":"integer","description":"Submit. Field in the JSON request body.\n\n**Details:** Type `integer`."},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`."},"unit_price":{"type":"number","description":"Unit price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"origin":{"type":"string","description":"Origin. Field in the JSON request body.\n\n**Details:** Type `string`."},"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"sku":{"type":"string","description":"Stock keeping unit / product code.\n\n**Details:** Type `string`."},"barcode":{"type":"string","description":"Barcode. Stable machine-readable code.\n\n**Details:** Type `string`."},"unit":{"type":"string","description":"Unit. Field in the JSON request body.\n\n**Details:** Type `string`."},"hscode":{"type":"string","description":"Hscode. Stable machine-readable code.\n\n**Details:** Type `string`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."}}},"description":"Optional. Array of items to ship out.\n\n**Details:** Type `array`, items `object`."},"packages":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"length":{"type":"integer","description":"Length dimension.\n\n**Details:** Type `integer`."},"width":{"type":"integer","description":"Width dimension.\n\n**Details:** Type `integer`."},"height":{"type":"integer","description":"Height dimension.\n\n**Details:** Type `integer`."},"insurance_value":{"type":"number","description":"Insurance amount for the package or order in the business currency.\n\n**Details:** Type `number`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`."},"unit_price":{"type":"number","description":"Unit price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"origin":{"type":"string","description":"Origin. Field in the JSON request body.\n\n**Details:** Type `string`."},"weight":{"type":"integer","description":"Weight of the package or shipment.\n\n**Details:** Type `integer`."},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`."},"unit":{"type":"string","description":"Unit. Field in the JSON request body.\n\n**Details:** Type `string`."},"sku":{"type":"string","description":"Stock keeping unit / product code.\n\n**Details:** Type `string`."},"barcode":{"type":"string","description":"Barcode. Stable machine-readable code.\n\n**Details:** Type `string`."},"hscode":{"type":"string","description":"Hscode. Stable machine-readable code.\n\n**Details:** Type `string`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."}}},"description":"Items. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"signature_option":{"type":"integer","description":"Signature option. Field in the JSON request body.\n\n**Details:** Type `integer`."},"insurance_option":{"type":"integer","description":"Insurance option. Field in the JSON request body.\n\n**Details:** Type `integer`."},"schedule_date":{"type":"string","description":"Schedule date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`."},"notification_language":{"type":"string","description":"Notification language. Field in the JSON request body.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"address_type":{"type":"integer","description":"Address type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"company_name":{"type":"string","description":"Contact company name at the stop.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"buzz_code":{"type":"string","description":"Buzz code. Stable machine-readable code.\n\n**Details:** Type `string`."},"label_type":{"type":"integer","description":"Label type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"order_batch":{"type":"string","description":"Order batch. Field in the JSON request body.\n\n**Details:** Type `string`."}},"required":["warehouse_id"]},"examples":{"English":{"value":{"warehouse_id":1,"warehouse_code":"COI8","shipping_type":3,"container_type":1,"shipping_method":"WMS_SUPPORTED_SHIPPING_METHOD","carrier":"DHL","service":"express","tracking_number":12321432,"shipping_label":"JVBERi0xLjQKMS... (base64 encoded)","note":"customer note","weight":1,"length":1,"width":1,"height":1,"package_note":"package notes","insurance_value":200,"submit":1,"items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","sku":"SKU001","barcode":1321312321,"unit":"PCS","hscode":8009201332,"description":"Product 1 description"}],"packages":[{"weight":1000,"length":300,"width":200,"height":100,"insurance_value":200,"note":"package note","items":[{"name":"Product 1","quantity":1,"unit_price":1.48,"origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","barcode":1321312321,"hscode":8009201332,"description":"Product 1 description"}]}],"signature_option":1,"insurance_option":1,"schedule_date":"2021-04-05 00:00:00","notification_language":"en","name":"test","address_1":"6701 RUE HADLEY","address_2":"","address_type":1,"postcode":"H4E3R3","city":"Montreal","province":"QC","country":"CA","company_name":"Super Route","email":"info@gmail.com","telephone":666666666,"buzz_code":5151,"label_type":0,"order_batch":"2021-08-23"}},"example":{"value":{"warehouse_id":1,"warehouse_code":"COI8","shipping_type":3,"container_type":1,"shipping_method":"WMS_SUPPORTED_SHIPPING_METHOD","carrier":"DHL","service":"express","tracking_number":12321432,"shipping_label":"JVBERi0xLjQKMS...","note":"customer note","weight":1,"length":1,"width":1,"height":1,"package_note":"(包裹备注，当PACKAGES为空时有效)","submit":1,"items":[{"name":"Product 1","quantity":1,"unit_price":"1.48","origin":"CA","weight":1000,"currency":"CAD","sku":"SKU001","barcode":1321312321,"unit":"PCS","hscode":8009201332,"description":"Product 1 description"}],"packages":[{"weight":1000,"length":300,"width":200,"height":100,"insurance_value":"200.00","note":"包裹备注（可选）","items":[{"name":"Product 1","quantity":1,"unit_price":"1.48","origin":"CA","weight":1000,"currency":"CAD","unit":"PCS","sku":"SKU001","hscode":8009201332,"description":"Product 1 description"}]}],"signature_option":1,"insurance_option":1,"insurance_value":"200.00","schedule_date":"2021-04-05","notification_language":"fr","name":"test","address_1":"6701 RUE HADLEY","address_2":"(收件人地址2,选填）","address_type":1,"postcode":"H4E3R3","city":"Montreal","province":"QC","country":"CA","company_name":"Super Route","email":"info@gmail.com","telephone":666666666,"buzz_code":5151,"label_type":0,"order_batch":"2021-08-23"}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"sync_status":{"type":"integer","description":"Sync status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `integer`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"outbound_order_id":{"type":"string","description":"Outbound order id. Identifier referencing the related record.\n\n**Details:** Type `string`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"msg":"Successful","data":{"sync_status":2,"order_id":103896,"outbound_order_id":"OUT-230418-WSRR0030"}}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/cancelOutboundRequest":{"post":{"tags":["Warehouse"],"summary":"Cancel Outbound Request","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}},"examples":{"ID":{"value":{"id":17832}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Successful"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/wms/uploadShippingLabel":{"post":{"tags":["Warehouse"],"summary":"Upload Shipping Label for Outbound Orders","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"shipping_method":{"type":"string","description":"Shipping method. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"carrier":{"type":"string","description":"Carrier. Field in the JSON request body.\n\n**Details:** Type `string`."},"service":{"type":"string","description":"Service. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Required. Tracking number.\n\n**Details:** Type `string`."},"label":{"type":"string","description":"Label. Human-readable label.\n\n**Details:** Type `string`."}},"required":["tracking_number"]},"examples":{"ID":{"value":{"id":17832,"shipping_method":"WMS_SUPPORTED_SHIPPING_METHOD","carrier":"canada_post","service":"expedited_parcel","tracking_number":123456789012,"label":"base64 encoded label"}}}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Successful"}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/addressbook":{"get":{"operationId":"addressBookList","tags":["AddressBook"],"summary":"get users address list","parameters":[{"in":"query","name":"address_ids","schema":{"type":"string","description":"Address ids. List of identifiers for the related records.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `1,2,3`.","examples":["1,2,3"]},"required":false,"description":"Address ids. List of identifiers for the related records.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `1,2,3`."},{"in":"query","name":"myaddress","schema":{"type":"integer","enum":[0,1],"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"fulfillment_center_only","description":"Set to 1 to return only fulfillment centers. Default 0 (no filter).\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","enum":[0,1],"description":"Set to 1 to return only fulfillment centers. Default 0 (no filter).\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"unique_identifier":{"type":"string","description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"apt":{"type":"string","description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"lat":{"type":"string","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"wms_setting_id":{"type":"integer","description":"Wms setting id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"warehouse_id":{"type":"string","description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `string`."},"territory":{"type":["string","null"],"description":"Territory. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"is_point":{"type":"integer","description":"Is point. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_warehouse":{"type":"integer","description":"Is warehouse. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_default_shipping_from":{"type":"integer","description":"Is default shipping from. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"business_name":{"type":"string","description":"Business name. Human-readable label.\n\n**Details:** Type `string`."},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"territory_info":{"type":["string","null"],"description":"Territory info. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"operating_hour_id":{"type":["integer","null"],"description":"Routing phase P5b (additive): the operating-hour set the address links, null when none.\n\n**Details:** Type `integer` · Nullable."},"holiday_calendar_id":{"type":["integer","null"],"description":"Routing phase P5b (additive): the holiday calendar the address links, null when none.\n\n**Details:** Type `integer` · Nullable."}}}},"example":[{"id":106,"name":1,"unique_identifier":1,"business_id":333,"description":1,"postcode":"H4E3R3","street_number":6701,"street_name":"RUE HADLEY","apt":"","city":"Montreal","province":"QC","country":"Canada","lat":"45.452116","lng":"-73.591895","telephone":4388780678,"wms_setting_id":4,"warehouse_id":"DYT2","territory":null,"is_point":1,"is_warehouse":1,"status":1,"created_at":"2023-04-06 03:10:55.00","updated_at":"2023-04-09 01:10:56.00","business_name":"Hello Inc.","address":"6701 RUE HADLEY","territory_info":null},{"id":107,"name":2,"unique_identifier":2,"business_id":333,"description":2,"postcode":"H4E3R3","street_number":6703,"street_name":"RUE HADLEY","apt":"","city":"Montreal","province":"QC","country":"Canada","lat":"45.452116","lng":"-73.591895","telephone":4388780678,"wms_setting_id":null,"warehouse_id":null,"territory":null,"is_point":1,"is_warehouse":0,"status":1,"created_at":"2023-04-06 03:11:19.00","updated_at":"2023-04-06 04:02:08.00","business_name":"Hello Inc.","address":"6703 RUE HADLEY","territory_info":null},{"id":112,"name":2,"unique_identifier":"2DSA","business_id":333,"description":"","postcode":"H4E3R3","street_number":6703,"street_name":"RUE HADLEY","apt":"","city":"Montreal","province":"QC","country":"Canada","lat":"45.452116","lng":"-73.591895","telephone":1232131,"wms_setting_id":null,"warehouse_id":null,"territory":null,"is_point":1,"is_warehouse":0,"status":1,"created_at":"2023-04-08 01:28:22.00","updated_at":"2023-04-08 01:28:22.00","business_name":"Hello Inc.","address":"6703 RUE HADLEY","territory_info":null},{"id":103,"name":"DH Mississauga Warehouse","unique_identifier":"DHW","business_id":333,"description":"Mississauga","postcode":"L4Z 1X8","street_number":267,"street_name":"Matheson Blvd E,","apt":"","city":"Mississauga","province":"Ontario","country":"Canada","lat":"43.622157","lng":"-79.661993","telephone":"+1 416-880-0507","wms_setting_id":null,"warehouse_id":null,"territory":null,"is_point":1,"is_warehouse":0,"status":1,"created_at":"2023-02-28 04:46:17.00","updated_at":"2023-04-08 21:02:16.00","business_name":"Hello Inc.","address":"267 Matheson Blvd E,","territory_info":null},{"id":111,"name":"WAREHOUSE","unique_identifier":"h1","business_id":333,"description":"","postcode":"H4E3R3","street_number":6701,"street_name":"RUE HADLEY","apt":"","city":"Montreal","province":"QC","country":"Canada","lat":"45.452116","lng":"-73.591895","telephone":4388780678,"wms_setting_id":4,"warehouse_id":"DYT2","territory":null,"is_point":1,"is_warehouse":1,"status":1,"created_at":"2023-04-08 01:27:33.00","updated_at":"2023-04-08 01:33:39.00","business_name":"Hello Inc.","address":"6701 RUE HADLEY","territory_info":null},{"id":110,"name":"warehouse","unique_identifier":"sss","business_id":333,"description":"H4E3R3","postcode":"H4E3R3","street_number":6701,"street_name":"RUE HADLEY","apt":"","city":"Montreal","province":"QC","country":"Canada","lat":"45.452116","lng":"-73.591895","telephone":2312,"wms_setting_id":null,"warehouse_id":null,"territory":null,"is_point":0,"is_warehouse":1,"status":1,"created_at":"2023-04-08 01:25:01.00","updated_at":"2023-04-09 02:02:22.00","business_name":"Hello Inc.","address":"6701 RUE HADLEY","territory_info":null}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"post":{"operationId":"addressBookCreate","tags":["AddressBook"],"summary":"Create an addressbook","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"unique_identifier":{"type":"integer","description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `integer`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"apt":{"type":"string","description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"is_point":{"type":"integer","description":"Is point. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_warehouse":{"type":"integer","description":"Is warehouse. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_default_shipping_from":{"type":"integer","description":"Optional. 1 marks this address as the account default shipping-from (only one per account). Used when an order has no processing center, before the registered address.\n\n**Details:** Type `integer`."},"wms_setting_id":{"type":"integer","description":"Wms setting id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"warehouse_id":{"type":"string","description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `string`."},"rewrite":{"type":"integer","description":"Rewrite. Field in the JSON request body.\n\n**Details:** Type `integer`."},"operating_hour_id":{"type":["integer","null"],"description":"Optional (routing phase P5b). One of the business's operating-hour sets; route planning uses the address as a reload depot or break place only while it is open. null clears it; omit to leave it unchanged.\n\n**Details:** Type `integer` · Nullable."},"holiday_calendar_id":{"type":["integer","null"],"description":"Optional (routing phase P5b). One of the business's holiday calendars (not a template); dates it marks closed keep route planning from reloading or taking breaks at the address. null clears it; omit to leave it unchanged.\n\n**Details:** Type `integer` · Nullable."}}},"examples":{"English":{"value":{"unique_identifier":123123123,"postcode":"H9S2H9","street_number":2667,"street_name":"boul des sources","apt":123,"city":"pointe-claire","province":"QC","country":"Canada","name":"John","email":"join@gmail.com","telephone":5555555555,"is_point":1,"is_warehouse":1,"is_default_shipping_from":0,"wms_setting_id":1,"warehouse_id":"test","rewrite":0}}}}},"required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"lat":{"type":"string","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"is_point":{"type":"integer","description":"Is point. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"territory_info":{"type":["string","null"],"description":"Territory info. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}}},"example":[{"id":2,"name":"The Montreal Museum of Fine Arts","street_number":1380,"street_name":"Sherbrooke St W","country":"canada","postcode":"H3G 1J5","lat":"45.4986786","lng":"-73.579347","telephone":"+15142852000","is_point":1,"status":0,"territory_info":null}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/addressbook/{address_id}":{"get":{"operationId":"addressBookShow","tags":["AddressBook"],"summary":"get users address detail","parameters":[{"in":"path","name":"address_id","schema":{"type":"integer","description":"Address id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Address id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"lat":{"type":"string","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"is_point":{"type":"integer","description":"Is point. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"territory_info":{"type":["string","null"],"description":"Territory info. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}}},"example":[{"id":2,"name":"The Montreal Museum of Fine Arts","street_number":1380,"street_name":"Sherbrooke St W","country":"canada","postcode":"H3G 1J5","lat":"45.4986786","lng":"-73.579347","telephone":"+15142852000","is_point":1,"status":0,"territory_info":null}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"put":{"operationId":"addressBookUpdate","tags":["AddressBook"],"summary":"update addressbook by id","parameters":[{"in":"path","name":"address_id","schema":{"type":"integer","description":"Address id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Address id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"unique_identifier":{"type":"string","description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"apt":{"type":"string","description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"is_point":{"type":"integer","description":"Is point. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_warehouse":{"type":"integer","description":"Is warehouse. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"is_default_shipping_from":{"type":"integer","description":"Optional. 1 marks this address as the account default shipping-from (only one per account). Used when an order has no processing center, before the registered address.\n\n**Details:** Type `integer`."},"wms_setting_id":{"type":"integer","description":"Wms setting id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"warehouse_id":{"type":"string","description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"operating_hour_id":{"type":["integer","null"],"description":"Optional (routing phase P5b). One of the business's operating-hour sets; route planning uses the address as a reload depot or break place only while it is open. null clears it; omit to leave it unchanged.\n\n**Details:** Type `integer` · Nullable."},"holiday_calendar_id":{"type":["integer","null"],"description":"Optional (routing phase P5b). One of the business's holiday calendars (not a template); dates it marks closed keep route planning from reloading or taking breaks at the address. null clears it; omit to leave it unchanged.\n\n**Details:** Type `integer` · Nullable."}}},"examples":{"English":{"value":{"unique_identifier":"test","postcode":"H9S2H9","street_number":2667,"street_name":"boul des sources","apt":123,"city":"pointe-claire","province":"QC","country":"Canada","name":"John","email":"join@gmail.com","telephone":5555555555,"is_point":1,"is_warehouse":1,"is_default_shipping_from":0,"wms_setting_id":1,"warehouse_id":"test","status":1}}}}},"required":true},"responses":{"202":{"description":"updated","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"lat":{"type":"string","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"lng":{"type":"string","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"is_point":{"type":"integer","description":"Is point. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"territory_info":{"type":["string","null"],"description":"Territory info. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}}},"example":[{"id":2,"name":"The Montreal Museum of Fine Arts","street_number":1380,"street_name":"Sherbrooke St W","country":"canada","postcode":"H3G 1J5","lat":"45.4986786","lng":"-73.579347","telephone":"+15142852000","is_point":1,"status":0,"territory_info":null}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"addressBookDelete","tags":["AddressBook"],"summary":"delete address book","parameters":[{"in":"path","name":"address_id","schema":{"type":"integer","description":"Address id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Address id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"301":{"description":"deleted"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/driverinfo":{"get":{"operationId":"driverInfoList","tags":["DriverInfo"],"summary":"get driver info list","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page. Field in the JSON request body.\n\n**Details:** Type `integer`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"vehicle_type":{"type":"string","description":"Vehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"]},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"tracking_number_prefix":{"type":["string","null"],"description":"Tracking number prefix. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"users_info_id":{"type":"integer","description":"Users info id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"capacity":{"type":["string","null"],"description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"business_name":{"type":"string","description":"Business name. Human-readable label.\n\n**Details:** Type `string`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`."},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`."},"start_location_id":{"type":["string","null"],"description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"end_location_id":{"type":["string","null"],"description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"gps_tracking":{"type":"integer","description":"Gps tracking. Field in the JSON request body.\n\n**Details:** Type `integer`."},"gps_device_type":{"type":"string","description":"Gps device type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"gps_identifier":{"type":"string","description":"Gps identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"first_page_url":{"type":"string","description":"First page url. Absolute or relative URL.\n\n**Details:** Type `string`."},"from":{"type":"integer","description":"From. Field in the JSON request body.\n\n**Details:** Type `integer`."},"last_page":{"type":"integer","description":"Last page. Field in the JSON request body.\n\n**Details:** Type `integer`."},"last_page_url":{"type":"string","description":"Last page url. Absolute or relative URL.\n\n**Details:** Type `string`."},"next_page_url":{"type":["string","null"],"description":"Next page url. Absolute or relative URL.\n\n**Details:** Type `string` · Nullable."},"path":{"type":"string","description":"Path. Field in the JSON request body.\n\n**Details:** Type `string`."},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`."},"prev_page_url":{"type":["string","null"],"description":"Prev page url. Absolute or relative URL.\n\n**Details:** Type `string` · Nullable."},"to":{"type":"integer","description":"To. Field in the JSON request body.\n\n**Details:** Type `integer`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}}}},"example":[{"current_page":1,"data":[{"id":1,"name":"driver003_1","email":"driver003@example.com","vehicle_type":"1 (1: Car, 2: Truck, 3: Motorcycle, 4: Bicycle 5:Pedestrian)","address":"","address_2":"","city":"","province":"","country":"Canada","postcode":"","telephone":5140000003,"tracking_number_prefix":null,"alias":"alias0003_1","users_info_id":3,"business_id":2,"capacity":null,"business_name":"Client Example","language":"en","territory_id":1,"start_location_id":null,"end_location_id":null,"gps_tracking":0,"gps_device_type":1,"gps_identifier":"","status":1}],"first_page_url":"http://api.superroute.ca/api/v1/driverinfo?page=1","from":1,"last_page":1,"last_page_url":"http://api.superroute.ca/api/v1/driverinfo?page=1","next_page_url":null,"path":"http://api.superroute.ca/api/v1/driverinfo","per_page":20,"prev_page_url":null,"to":1,"total":1}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"post":{"operationId":"driverInfoCreate","tags":["DriverInfo"],"summary":"Create a Driver","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"vehicle_type":{"type":"string","description":"Vehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"]},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"password":{"type":"string","description":"Account password (never logged or returned by the API).\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`."},"capacity":{"type":["string","null"],"description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"territory_id":{"type":["string","null"],"description":"Territory id.\n\n**Details:** Type `string` · Nullable."},"start_location_id":{"type":["string","null"],"description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"end_location_id":{"type":["string","null"],"description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}}},"examples":{"English":{"value":{"alias":"driver01","vehicle_type":1,"name":"John","password":12345678,"email":"join@gmail.com","telephone":5555555555,"address":"demo (nullable)","address_2":"demo (nullable)","city":"demo (nullable)","province":"demo (nullable)","country":"CA (nullable)","postcode":"H0H0H0 (nullable)","language":"en","capacity":null,"territory_id":null,"start_location_id":null,"end_location_id":null,"status":1}}}}},"required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"Email":{"type":"string","description":"Email. Email address.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`."},"capacity":{"type":["string","null"],"description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`."},"start_location_id":{"type":["string","null"],"description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"end_location_id":{"type":["string","null"],"description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."}}}},"example":[{"result":true,"id":1,"business_id":1,"Email":"driver001@example.com","name":"driver001","status":1,"alias":"alias0001","telephone":5140000012,"language":"en","capacity":null,"territory_id":1,"start_location_id":null,"end_location_id":null}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/driverinfo/{driver_id}":{"put":{"operationId":"driverInfoUpdate","tags":["DriverInfo"],"summary":"update driver by id","parameters":[{"in":"path","name":"driver_id","schema":{"type":"integer","description":"Driver id.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Driver id.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"vehicle_type":{"type":"string","description":"Vehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"]},"password":{"type":"string","description":"Account password (never logged or returned by the API).\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"start_location_id":{"type":"integer","description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"end_location_id":{"type":"integer","description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`."},"capacity":{"type":"integer","description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `integer`."},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}}},"examples":{"English":{"value":{"name":"driver003_1","alias":"alias0003_1","email":"driver003@example.com","vehicle_type":1,"password":12345678,"telephone":5140000003,"start_location_id":1,"end_location_id":1,"language":"en","capacity":60,"territory_id":1,"status":1}}}}},"required":true},"responses":{"200":{"description":"updated","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"Email":{"type":"string","description":"Email. Email address.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`."},"capacity":{"type":["string","null"],"description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`."},"start_location_id":{"type":["string","null"],"description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"end_location_id":{"type":["string","null"],"description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."}}}},"example":[{"id":1,"business_id":1,"Email":"driver001@example.com","name":"driver001","status":1,"alias":"alias0001","telephone":5140000012,"language":"en","capacity":null,"territory_id":1,"start_location_id":null,"end_location_id":null}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"driverInfoDelete","tags":["DriverInfo"],"summary":"delete driver","parameters":[{"in":"path","name":"driver_id","schema":{"type":"integer","description":"Driver id.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Driver id.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"deleted"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"not found"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/profile":{"get":{"operationId":"driverProfileShow","tags":["Driver"],"summary":"get driver profile","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"vehicle_type":{"type":"string","description":"Vehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"]},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"tracking_number_prefix":{"type":["string","null"],"description":"Tracking number prefix. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"users_info_id":{"type":"integer","description":"Users info id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"capacity":{"type":["string","null"],"description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"business_name":{"type":"string","description":"Business name. Human-readable label.\n\n**Details:** Type `string`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`."},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`."},"start_location_id":{"type":["string","null"],"description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"end_location_id":{"type":["string","null"],"description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"gps_tracking":{"type":"integer","description":"Gps tracking. Field in the JSON request body.\n\n**Details:** Type `integer`."},"gps_device_type":{"type":"string","description":"Gps device type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"gps_identifier":{"type":"string","description":"Gps identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}},"example":[{"data":{"id":1,"name":"driver003_1","email":"driver003@example.com","vehicle_type":"1 (1: Car, 2: Truck, 3: Motorcycle, 4: Bicycle 5:Pedestrian)","address":"","address_2":"","city":"","province":"","country":"Canada","postcode":"","telephone":5140000003,"tracking_number_prefix":null,"alias":"alias0003_1","users_info_id":3,"business_id":2,"capacity":null,"business_name":"Client Example","language":"en","territory_id":1,"start_location_id":null,"end_location_id":null,"gps_tracking":0,"gps_device_type":1,"gps_identifier":"","status":1}}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"put":{"operationId":"driverProfileUpdate","tags":["Driver"],"summary":"update driver profile","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"vehicle_type":{"type":"string","description":"Vehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"]},"password":{"type":"string","description":"Account password (never logged or returned by the API).\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"start_location_id":{"type":"integer","description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"end_location_id":{"type":"integer","description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`."},"capacity":{"type":"integer","description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `integer`."},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}}},"examples":{"English":{"value":{"name":"driver003_1","alias":"alias0003_1","email":"driver003@example.com","vehicle_type":1,"password":12345678,"telephone":5140000003,"start_location_id":1,"end_location_id":1,"language":"en","capacity":60,"territory_id":1,"status":1}}}}},"required":true},"responses":{"200":{"description":"updated","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"Email":{"type":"string","description":"Email. Email address.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`."},"capacity":{"type":["string","null"],"description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`."},"start_location_id":{"type":["string","null"],"description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"end_location_id":{"type":["string","null"],"description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."}}}},"example":[{"id":1,"business_id":1,"Email":"driver001@example.com","name":"driver001","status":1,"alias":"alias0001","telephone":5140000012,"language":"en","capacity":null,"territory_id":1,"start_location_id":null,"end_location_id":null}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders":{"get":{"summary":"Get Orders","description":"Retrieve a list of orders filtered by optional parameters such as status, id, unassigned flag, and pagination.","tags":["Driver"],"parameters":[{"name":"status","in":"query","description":"Filter by order status ID\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `integer`.","required":false,"schema":{"type":"integer","description":"Filter by order status ID\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `integer`."}},{"name":"id","in":"query","description":"Filter by specific order ID\n\nResource identifier.\n\n**Details:** Optional · Type `integer`.","required":false,"schema":{"type":"integer","description":"Filter by specific order ID\n\nResource identifier.\n\n**Details:** Optional · Type `integer`."}},{"name":"unassigned","in":"query","description":"Set to 1 to filter only unassigned orders (no driver and no route)\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer` · Default: `0`.","required":false,"schema":{"type":"integer","enum":[0,1],"default":0,"description":"Set to 1 to filter only unassigned orders (no driver and no route)\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer` · Default: `0`.","x-enumDescriptions":["No / false / off","Yes / true / on"]}},{"name":"page","in":"query","description":"Page number for pagination\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1`.","required":false,"schema":{"type":"integer","default":1,"description":"Page number for pagination\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1`."}},{"name":"pageSize","in":"query","description":"Number of items per page\n\n**Details:** Optional · Type `integer` · Default: `20`.","required":false,"schema":{"type":"integer","default":20,"description":"Number of items per page\n\n**Details:** Optional · Type `integer` · Default: `20`."}}],"responses":{"200":{"description":"Successful order list response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/driver/kiosk-receiving-packages":{"get":{"summary":"Get kiosk receiving area package count","description":"Query how many receiving packages exist at a kiosk pickup location. The driver must be assigned to the route, the route must not be ended, and the order must be a kiosk pickup order (related_order_type = 6).","tags":["Driver"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"route_id","in":"query","description":"The route ID that contains the kiosk pickup order\n\nRoute id (`routes.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `100`.","required":true,"schema":{"type":"integer","description":"The route ID that contains the kiosk pickup order\n\nRoute id (`routes.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `100`."},"example":100},{"name":"order_id","in":"query","description":"The kiosk pickup order ID on the route\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5000`.","required":true,"schema":{"type":"integer","description":"The kiosk pickup order ID on the route\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5000`."},"example":5000}],"responses":{"200":{"description":"Receiving area package count retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"location_id":{"type":"integer","description":"The addressbook ID of the kiosk location\n\n**Details:** Type `integer`.\n\n**Example:** `42`.","examples":[42]},"location_name":{"type":"string","description":"Name of the kiosk location\n\n**Details:** Type `string`.\n\n**Example:** `Kiosk Downtown`.","examples":["Kiosk Downtown"]},"receiving_package_count":{"type":"integer","description":"Total quantity of packages in the receiving area at this kiosk\n\n**Details:** Type `integer`.\n\n**Example:** `15`.","examples":[15]}}},"example":{"result":true,"location_id":42,"location_name":"Kiosk Downtown","receiving_package_count":15}}}},"400":{"description":"Validation or business logic error","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Specific error reason\n\n**Details:** Type `string`."}}},"examples":{"order_not_on_route":{"summary":"Order is not on the specified route","value":{"result":false,"message":"Order is not assigned to this route"}},"route_not_assigned":{"summary":"Route is not assigned to this driver","value":{"result":false,"message":"Route is not assigned to this driver"}},"route_ended":{"summary":"Route has already ended","value":{"result":false,"message":"Route has already ended"}},"not_kiosk_pickup":{"summary":"Order is not a kiosk pickup type","value":{"result":false,"message":"Order is not a kiosk pickup order"}}}}}}}}},"/v1/driver/kiosk-receive-package":{"post":{"summary":"Scan and receive an awaiting-processing package from kiosk receiving area","description":"Driver scans a code at a kiosk location and receives a single awaiting-processing package from the receiving area onto their vehicle inventory. The driver must be assigned to the route, the route must not be ended, and the order must be a kiosk pickup order (related_order_type = 6). Supports every customer-dropped type: returns, express drop-offs and storage drop-offs. The code may be a return code, a reference number, or the package's own unique code. Plain delivery packages are intentionally excluded.","tags":["Driver"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["route_id","order_id","scan_code"],"properties":{"route_id":{"type":"integer","description":"**Required.**\n\nThe route ID that contains the kiosk pickup order\n\n**Details:** Type `integer`.\n\n**Example:** `100`.","examples":[100]},"order_id":{"type":"integer","description":"**Required.**\n\nThe kiosk pickup order ID on the route\n\n**Details:** Type `integer`.\n\n**Example:** `5000`.","examples":[5000]},"scan_code":{"type":"string","description":"**Required.**\n\nThe code to scan: a return code, reference number, or the package's own unique code\n\n**Details:** Type `string`.\n\n**Example:** `ABC123`.","examples":["ABC123"]}}}}}},"responses":{"200":{"description":"Package received successfully","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Package received successfully`.","examples":["Package received successfully"]},"inventory_id":{"type":"integer","description":"The inventory record ID now assigned to the driver\n\n**Details:** Type `integer`.\n\n**Example:** `50`.","examples":[50]},"inventory_type":{"type":"integer","description":"Inventory type of the received package (4 = Return, 6 = Express Package, 3 = Storage Package)\n\n**Details:** Type `integer`.","examples":[4]},"return_request":{"type":"object","description":"Present only when the received package is a return\n\n**Details:** Type `object`.","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `10`.","examples":[10]},"return_code":{"type":"string","description":"Return code. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `ABC123`.","examples":["ABC123"]},"reference_number":{"type":"string","description":"Reference number. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `REF-001`.","examples":["REF-001"]},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`.\n\n**Example:** `5`.","examples":[5]},"original_order_id":{"type":"integer","description":"Original order id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `200`.","examples":[200]}}}}},"example":{"result":true,"message":"Package received successfully","inventory_id":50,"inventory_type":4,"return_request":{"id":10,"return_code":"ABC123","reference_number":"REF-001","status":5,"original_order_id":200}}}}},"400":{"description":"Validation or business logic error","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Specific error reason\n\n**Details:** Type `string`."}}},"examples":{"return_not_found":{"summary":"Return request not found or wrong status","value":{"result":false,"message":"Return request not found or not in dropped-off status"}},"not_in_receiving_area":{"summary":"Return package not at this kiosk location","value":{"result":false,"message":"Return package not found in the receiving area at this location"}},"order_not_on_route":{"summary":"Order is not on the specified route","value":{"result":false,"message":"Order is not assigned to this route"}},"route_not_assigned":{"summary":"Route is not assigned to this driver","value":{"result":false,"message":"Route is not assigned to this driver"}},"route_ended":{"summary":"Route has already ended","value":{"result":false,"message":"Route has already ended"}},"not_kiosk_pickup":{"summary":"Order is not a kiosk pickup type","value":{"result":false,"message":"Order is not a kiosk pickup order"}}}}}},"409":{"description":"Package has already been received","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Package has already been received`.","examples":["Package has already been received"]}}},"example":{"result":false,"message":"Package has already been received"}}}}}}},"/v1/driver/packagings":{"get":{"tags":["Driver"],"summary":"Get packaging types and packagings for the driver's service provider","description":"Returns a list of packaging types with their associated packagings (predefined dimensions). Used in the driver app for selecting packaging when adding/editing items on storage and moving orders. Supports multi-language via the `language` parameter.","parameters":[{"name":"language","in":"query","required":false,"description":"Language code for translated packaging names (e.g., 'en', 'zh', 'fr'). Defaults to 'en'.\n\n**Details:** Optional · Type `string` · Default: `en`.","schema":{"type":"string","default":"en","description":"Language code for translated packaging names (e.g., 'en', 'zh', 'fr'). Defaults to 'en'.\n\n**Details:** Optional · Type `string` · Default: `en`."}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"allow_custom":{"type":"boolean","description":"Whether the service provider allows custom packaging sizes\n\n**Details:** Type `boolean`."},"packaging_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Packaging type ID (0 = uncategorized)\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Translated packaging type name\n\n**Details:** Type `string`."},"packagings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Translated packaging name\n\n**Details:** Type `string`."},"length":{"type":"number","format":"float","description":"Length dimension.\n\n**Details:** Type `number`, format `float`."},"width":{"type":"number","format":"float","description":"Width dimension.\n\n**Details:** Type `number`, format `float`."},"height":{"type":"number","format":"float","description":"Height dimension.\n\n**Details:** Type `number`, format `float`."},"dimension_unit":{"type":"integer","description":"1=mm, 2=cm, 3=m, 4=inch\n\n**Details:** Type `integer`."}}},"description":"Packagings. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"description":"Packaging types. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"allow_custom":true,"packaging_types":[{"id":1,"name":"Cardboard Boxes","packagings":[{"id":1,"name":"Small Box","length":30,"width":20,"height":15,"dimension_unit":2},{"id":2,"name":"Medium Box","length":50,"width":40,"height":30,"dimension_unit":2}]},{"id":2,"name":"Furniture & Appliances","packagings":[{"id":4,"name":"Small Appliance Wrap","length":60,"width":50,"height":40,"dimension_unit":2}]}]}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/unit-mappings":{"get":{"tags":["Driver"],"summary":"Get dimension and weight unit mappings","description":"Returns the available dimension units (mm, cm, m, inch) and weight units (g, kg, oz, lb) with translated labels and accuracy values. Used by the driver app to populate unit dropdowns dynamically instead of hardcoding.","parameters":[{"name":"language","in":"query","required":false,"description":"Language code for translated unit labels (e.g., 'en', 'zh', 'fr'). Defaults to 'en'.\n\n**Details:** Optional · Type `string` · Default: `en`.","schema":{"type":"string","default":"en","description":"Language code for translated unit labels (e.g., 'en', 'zh', 'fr'). Defaults to 'en'.\n\n**Details:** Optional · Type `string` · Default: `en`."}}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"dimension_units":{"type":"array","items":{"type":"object","properties":{"value":{"type":"integer","description":"Unit ID used in API requests\n\n**Details:** Type `integer`."},"label":{"type":"string","description":"Translated unit label\n\n**Details:** Type `string`."},"accuracy":{"type":"integer","description":"Number of decimal places for this unit\n\n**Details:** Type `integer`."}}},"description":"Dimension units. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `array`, items `object`."},"weight_units":{"type":"array","items":{"type":"object","properties":{"value":{"type":"integer","description":"Unit ID used in API requests\n\n**Details:** Type `integer`."},"label":{"type":"string","description":"Translated unit label\n\n**Details:** Type `string`."},"accuracy":{"type":"integer","description":"Number of decimal places for this unit\n\n**Details:** Type `integer`."}}},"description":"Weight units. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"dimension_units":[{"value":1,"label":"mm","accuracy":0},{"value":2,"label":"cm","accuracy":1},{"value":3,"label":"m","accuracy":3},{"value":4,"label":"inch","accuracy":3}],"weight_units":[{"value":1,"label":"g","accuracy":0},{"value":2,"label":"kg","accuracy":3},{"value":3,"label":"oz","accuracy":1},{"value":4,"label":"lb","accuracy":3}]}}}},"400":{"description":"Bad Request"}},"security":[{"bearerAuth":[]}]}},"/v1/skills":{"get":{"operationId":"skillList","tags":["Skills"],"summary":"get skills list","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page. Field in the JSON request body.\n\n**Details:** Type `integer`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"drivers":{"type":"array","items":{"type":"string","description":"Drivers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Drivers. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"first_page_url":{"type":"string","description":"First page url. Absolute or relative URL.\n\n**Details:** Type `string`."},"from":{"type":"integer","description":"From. Field in the JSON request body.\n\n**Details:** Type `integer`."},"last_page":{"type":"integer","description":"Last page. Field in the JSON request body.\n\n**Details:** Type `integer`."},"last_page_url":{"type":"string","description":"Last page url. Absolute or relative URL.\n\n**Details:** Type `string`."},"next_page_url":{"type":["string","null"],"description":"Next page url. Absolute or relative URL.\n\n**Details:** Type `string` · Nullable."},"path":{"type":"string","description":"Path. Field in the JSON request body.\n\n**Details:** Type `string`."},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`."},"prev_page_url":{"type":["string","null"],"description":"Prev page url. Absolute or relative URL.\n\n**Details:** Type `string` · Nullable."},"to":{"type":"integer","description":"To. Field in the JSON request body.\n\n**Details:** Type `integer`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}}},"example":{"current_page":1,"data":[{"id":3,"name":"skill_01","business_id":2,"status":1,"drivers":[]},{"id":2,"name":"skill_02","business_id":2,"status":1,"drivers":[{"id":11,"drivers_id":1,"skills_id":2,"related_drivers":{"id":1,"alias":"alias0003_1","users_info_id":3,"business_id":2,"map_type":1,"start_location_id":null,"end_location_id":null,"capacity":null}},{"id":12,"drivers_id":5,"skills_id":2,"related_drivers":{"id":5,"alias":"alias0006","users_info_id":7,"business_id":2,"map_type":1,"start_location_id":null,"end_location_id":null,"capacity":null}}]}],"first_page_url":"http://api.superroute.ca/api/v1/skills?page=1","from":1,"last_page":1,"last_page_url":"http://api.superroute.ca/api/v1/skills?page=1","next_page_url":null,"path":"http://api.superroute.ca/api/v1/skills","per_page":20,"prev_page_url":null,"to":2,"total":2}}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"post":{"operationId":"skillCreate","tags":["Skills"],"summary":"Create a Skill","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}}},"examples":{"English":{"value":{"name":"skill_01"}}}}},"required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}},"example":{"name":"skill_01","business_id":2,"status":1,"id":3}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/skills/{skill_id}":{"put":{"operationId":"skillUpdate","tags":["Skills"],"summary":"update skill by id","parameters":[{"in":"path","name":"skill_id","schema":{"type":"integer","description":"Skill id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Skill id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}}},"examples":{"English":{"value":{"name":"skill_03","status":1}}}}},"required":true},"responses":{"200":{"description":"updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"drivers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"drivers_id":{"type":"string","description":"Drivers id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"skills_id":{"type":"integer","description":"Skills id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"related_drivers":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"users_info_id":{"type":"integer","description":"Users info id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"map_type":{"type":"integer","description":"Map type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"start_location_id":{"type":["string","null"],"description":"Start location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"end_location_id":{"type":["string","null"],"description":"End location id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"capacity":{"type":["string","null"],"description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."}},"description":"Related drivers. Geographic latitude in decimal degrees.\n\n**Details:** Type `object`."}}},"description":"Drivers. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"id":2,"name":"skill_02","business_id":2,"status":1,"drivers":[{"id":11,"drivers_id":1,"skills_id":2,"related_drivers":{"id":1,"alias":"alias0003_1","users_info_id":3,"business_id":2,"map_type":1,"start_location_id":null,"end_location_id":null,"capacity":null}},{"id":12,"drivers_id":5,"skills_id":2,"related_drivers":{"id":5,"alias":"alias0006","users_info_id":7,"business_id":2,"map_type":1,"start_location_id":null,"end_location_id":null,"capacity":null}}]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"skillDelete","tags":["Skills"],"summary":"delete skill","parameters":[{"in":"path","name":"skill_id","schema":{"type":"integer","description":"Skill id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Skill id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"deleted"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"not found"}},"security":[{"bearerAuth":[]}]}},"/v1/returnreasons":{"get":{"operationId":"returnReasonList","tags":["ReturnReasons"],"summary":"get Return Reasons list","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"reason":{"type":"string","description":"The reason text. Returned in the language set on the requesting account (for a driver, their account language); a reason with no wording for that language falls back to the text as it was configured.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"visible_to_public":{"type":"integer","description":"Visible to public. Field in the JSON request body.\n\n**Details:** Type `integer`."},"sort_number":{"type":"integer","description":"Sort number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"for_pickup":{"type":"integer","description":"For pickup. Field in the JSON request body.\n\n**Details:** Type `integer`."},"for_delivery":{"type":"integer","description":"For delivery. Field in the JSON request body.\n\n**Details:** Type `integer`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."}}}},"example":[{"id":2,"reason":"test","business_id":2,"status":0,"visible_to_public":0,"sort_number":1,"for_pickup":1,"for_delivery":0,"created_at":"2021-03-10 21:53:58.00","updated_at":"2021-03-10 21:53:58.00"}]}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"post":{"operationId":"returnReasonCreate","tags":["ReturnReasons"],"summary":"Create a Return Reasons","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."},"reason_translations":{"type":"object","additionalProperties":{"type":"string","description":"Reason translations. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"description":"Optional per-language wording, keyed by UI language code (en, chs, cht, de, es, fr, it, nl, pt, sr, hu, pl, sk, cs). A driver reads the entry for the language set on their account; any language absent or blank here falls back to 'reason'. Omit the field entirely on update to leave the stored wording untouched. Unknown language codes are rejected.\n\n**Details:** Type `object`.","examples":[{"chs":"地址错误","fr":"Adresse incorrecte"}]},"sort_number":{"type":"integer","description":"Sort number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"visible_to_public":{"type":"integer","description":"Visible to public. Field in the JSON request body.\n\n**Details:** Type `integer`."}}},"examples":{"English":{"value":{"reason":"test","sort_number":1,"visible_to_public":0}}}}},"required":true},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"The reason text. Returned in the language set on the requesting account (for a driver, their account language); a reason with no wording for that language falls back to the text as it was configured.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"sort_number":{"type":"integer","description":"Sort number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"visible_to_public":{"type":"integer","description":"Visible to public. Field in the JSON request body.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}},"example":{"reason":"test","business_id":2,"sort_number":1,"visible_to_public":0,"status":0,"updated_at":"2021-03-10 21:53:58.00","created_at":"2021-03-10 21:53:58.00","id":2}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/returnreasons/{order_id}":{"get":{"operationId":"getByOrderId","tags":["ReturnReasons"],"summary":"get Return Reasons list filtered by order type","parameters":[{"in":"path","name":"order_id","schema":{"type":"integer","description":"Order ID to filter return reasons by order type (pickup/delivery)\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Order ID to filter return reasons by order type (pickup/delivery)\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"reason":{"type":"string","description":"The reason text. Returned in the language set on the requesting account (for a driver, their account language); a reason with no wording for that language falls back to the text as it was configured.\n\n**Details:** Type `string`."},"for_delivery":{"type":"integer","description":"For delivery. Field in the JSON request body.\n\n**Details:** Type `integer`."},"for_pickup":{"type":"integer","description":"For pickup. Field in the JSON request body.\n\n**Details:** Type `integer`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"visible_to_public":{"type":"integer","description":"Visible to public. Field in the JSON request body.\n\n**Details:** Type `integer`."},"sort_number":{"type":"integer","description":"Sort number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."}}}},"example":[{"id":2,"reason":"Customer not available","for_delivery":1,"for_pickup":1,"business_id":2,"status":1,"visible_to_public":0,"sort_number":1,"created_at":"2021-03-10 21:53:58.00","updated_at":"2021-03-10 21:53:58.00"}]}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object"},"examples":{"Order not found":{"value":{"message":["Order not found or does not belong to this business"]}},"Label service order":{"value":{"message":["Order is a label service order"]}}}}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/returnreasons/{rr_id}":{"put":{"operationId":"returnReasonUpdate","tags":["ReturnReasons"],"summary":"update Return Reason by id","parameters":[{"in":"path","name":"rr_id","schema":{"type":"integer","description":"Rr id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Rr id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."},"reason_translations":{"type":"object","additionalProperties":{"type":"string","description":"Reason translations. Geographic latitude in decimal degrees.\n\n**Details:** Type `string`."},"description":"Optional per-language wording, keyed by UI language code (en, chs, cht, de, es, fr, it, nl, pt, sr, hu, pl, sk, cs). A driver reads the entry for the language set on their account; any language absent or blank here falls back to 'reason'. Omit the field entirely on update to leave the stored wording untouched. Unknown language codes are rejected.\n\n**Details:** Type `object`.","examples":[{"chs":"地址错误","fr":"Adresse incorrecte"}]},"sort_number":{"type":"integer","description":"Sort number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"visible_to_public":{"type":"integer","description":"Visible to public. Field in the JSON request body.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."}}},"examples":{"English":{"value":{"reason":"test","sort_number":1,"visible_to_public":0,"status":1}}}}},"required":true},"responses":{"200":{"description":"updated","content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"The reason text. Returned in the language set on the requesting account (for a driver, their account language); a reason with no wording for that language falls back to the text as it was configured.\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"sort_number":{"type":"integer","description":"Sort number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"visible_to_public":{"type":"integer","description":"Visible to public. Field in the JSON request body.\n\n**Details:** Type `integer`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."}}},"example":{"reason":"test","business_id":2,"sort_number":1,"visible_to_public":0,"status":0,"updated_at":"2021-03-10 21:53:58.00","created_at":"2021-03-10 21:53:58.00","id":2}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"returnReasonDelete","tags":["ReturnReasons"],"summary":"delete Return Reason by id","parameters":[{"in":"path","name":"rr_id","schema":{"type":"integer","description":"Rr id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Rr id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"deleted"},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"not found"}},"security":[{"bearerAuth":[]}]}},"/v1/coverages":{"post":{"operationId":"coverageListPostcodes","tags":["Coverages"],"summary":"get coverage postcodes","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"warehouse_ids":{"type":"array","items":{"type":"integer","description":"Warehouse ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Warehouse ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"warehouse_codes":{"type":"array","items":{"type":"string","description":"Warehouse codes. Stable machine-readable code.\n\n**Details:** Type `string`."},"description":"Warehouse codes. Stable machine-readable code.\n\n**Details:** Type `array`, items `string`."},"include_transit":{"type":"boolean","description":"Include transit. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}},"examples":{"example":{"value":{"warehouse_ids":[1,2,3],"warehouse_codes":["MONTREAL","TORONTO"],"include_transit":true}}}}},"required":true},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"array","items":{"type":"string","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}}},"example":{"result":true,"message":"Successful","data":["L1C","L1E","L1G"]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/coverages/checkpostcodes":{"post":{"operationId":"coverageCheckPostcodes","tags":["Coverages"],"summary":"check postcodes in coverages or not","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"postcodes":{"type":"array","items":{"type":"string","description":"Postcodes. Stable machine-readable code.\n\n**Details:** Type `string`."},"description":"Required. Array of postcodes to check coverage for.\n\n**Details:** Type `array`, items `string`."},"warehouse_ids":{"type":"array","items":{"type":"integer","description":"Warehouse ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Warehouse ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"warehouse_codes":{"type":"array","items":{"type":"string","description":"Warehouse codes. Stable machine-readable code.\n\n**Details:** Type `string`."},"description":"Warehouse codes. Stable machine-readable code.\n\n**Details:** Type `array`, items `string`."},"include_transit":{"type":"boolean","description":"Include transit. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"include_3rd_party_label":{"type":"boolean","description":"Include 3rd party label. Human-readable label.\n\n**Details:** Type `boolean`."}},"required":["postcodes"]},"examples":{"example":{"value":{"postcodes":["H4E3R3","L3R3L1"],"warehouse_ids":[1,2,3],"warehouse_codes":["MONTREAL","TORONTO"],"include_transit":true,"include_3rd_party_label":false}}}}},"required":true},"responses":{"200":{"description":"Successful","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"array","items":{"type":"string","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}}},"example":{"result":true,"message":"Successful","data":["L1C","L1E","L1G"]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/inventories/search-package":{"post":{"tags":["Inventories"],"summary":"Search package by given package id/package ref/tracking/externalTracking/Inventory Ref","parameters":[{"in":"query","name":"search","schema":{"type":"string","description":"package id/package ref/tracking/externalTracking/Inventory Ref\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Required · Type `string`."},"description":"package id/package ref/tracking/externalTracking/Inventory Ref\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Required · Type `string`.","required":true},{"in":"query","name":"route_driver_id","schema":{"type":"integer","description":"search package by in specific route driver id\n\n**Details:** Optional · Type `integer`."},"description":"search package by in specific route driver id\n\n**Details:** Optional · Type `integer`.","required":false},{"in":"query","name":"forinstock","schema":{"type":"boolean","description":"check order status could be instock or not (default: false)\n\n**Details:** Optional · Type `boolean`."},"description":"check order status could be instock or not (default: false)\n\n**Details:** Optional · Type `boolean`.","required":false}],"responses":{"200":{"description":"successful operation - returns rich location data including warehouse, grid, shelf, receiving area, staging area, and driver inventory placements","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"package_id":{"type":"integer","description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"third_party_provider":{"type":"boolean","description":"Whether the order is currently assigned to a third-party delivery provider. Only present for non-customer callers; absent for customer callers.\n\n**Details:** Type `boolean`."},"third_party_provider_info":{"type":["object","null"],"description":"Present only when third_party_provider is true.\n\n**Details:** Type `object` · Nullable.","properties":{"provider":{"type":"string","description":"Provider. Field in the JSON request body.\n\n**Details:** Type `string`."},"external_order_number":{"type":["string","null"],"description":"External order number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}},"package":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"ref":{"type":["string","null"],"description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"tracking_number":{"type":["string","null"],"description":"Superroute or carrier tracking number.\n\n**Details:** Type `string` · Nullable."},"external_tracking_number":{"type":["string","null"],"description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string` · Nullable."},"third_party_tracking_number":{"type":["string","null"],"description":"Third party tracking number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"received_at":{"type":["string","null"],"format":"date-time","description":"Received at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"received_warehouse_id":{"type":["integer","null"],"description":"Received warehouse id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."}},"description":"Package. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"order":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":["string","null"],"description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status_id":{"type":["integer","null"],"description":"Numeric status id. For order endpoints this is `orders_status_id` (`OrdersStatusInput`).\n\n**Details:** Type `integer` · Nullable."},"status_name":{"type":["string","null"],"description":"Status name. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string` · Nullable."},"location_id":{"type":["integer","null"],"description":"Location id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"location_name":{"type":["string","null"],"description":"Location name. Human-readable label.\n\n**Details:** Type `string` · Nullable."}},"description":"Sort direction: typically `asc` or `desc`.\n\n**Details:** Type `object` · Nullable."},"inventory_locations":{"type":"array","description":"Every inventory row for this package — each entry lists the warehouse, grid, shelf, receiving area, staging area, or driver that row currently sits in.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"inventory_id":{"type":"integer","description":"Inventory id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"inventory_ref":{"type":["string","null"],"description":"Inventory reference\n\n**Details:** Type `string` · Nullable."},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`."},"in_warehouse":{"type":"boolean","description":"In warehouse. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"warehouse":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable."}},"description":"Warehouse. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"in_grid":{"type":"boolean","description":"In grid. Identifier referencing the related record.\n\n**Details:** Type `boolean`."},"grid":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"code":{"type":["string","null"],"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable."},"type":{"type":["string","null"],"description":"normal | placeholder | unavailable\n\n**Details:** Type `string` · Nullable."}},"description":"Grid. Identifier referencing the related record.\n\n**Details:** Type `object` · Nullable."},"in_shelf":{"type":"boolean","description":"In shelf. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"shelf":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"code":{"type":["string","null"],"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable."},"location":{"type":["string","null"],"description":"Location. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}},"description":"Shelf. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"in_receiving_area":{"type":"boolean","description":"In receiving area. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"receiving_area":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"warehouse_id":{"type":["integer","null"],"description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `integer` · Nullable."},"warehouse_name":{"type":["string","null"],"description":"Human-readable warehouse / hub name reported by the external system.\n\n**Details:** Type `string` · Nullable."}},"description":"Receiving area. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"in_staging_area":{"type":"boolean","description":"In staging area. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"staging_area":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"warehouse_id":{"type":["integer","null"],"description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `integer` · Nullable."},"warehouse_name":{"type":["string","null"],"description":"Human-readable warehouse / hub name reported by the external system.\n\n**Details:** Type `string` · Nullable."}},"description":"Staging area. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"with_driver":{"type":"boolean","description":"With driver. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"driver":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"user_id":{"type":["integer","null"],"description":"User id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable."},"email":{"type":["string","null"],"description":"Account email address.\n\n**Details:** Type `string` · Nullable."},"route_id":{"type":["integer","null"],"description":"Route id (`routes.id`).\n\n**Details:** Type `integer` · Nullable."}},"description":"Driver. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."}}}}}},"example":{"result":true,"message":"Successful","package_id":132123,"order_id":12123,"third_party_provider":true,"third_party_provider_info":{"provider":"XXX EXPRESS","external_order_number":"DEMOXXXX"},"package":{"id":132123,"order_id":12123,"ref":"PKG-132123","tracking_number":"TRK0001","external_tracking_number":null,"third_party_tracking_number":null,"status":"received","received_at":"2026-04-01 10:30:00","received_warehouse_id":5},"order":{"id":12123,"ref":"ORD-12123","status_id":4,"status_name":"Received","location_id":5,"location_name":"Main Warehouse"},"inventory_locations":[{"inventory_id":4567,"inventory_ref":"INV-REF-001","quantity":1,"in_warehouse":true,"warehouse":{"id":5,"name":"Main Warehouse"},"in_grid":true,"grid":{"id":88,"code":"A-01-03","type":"normal"},"in_shelf":true,"shelf":{"id":12,"code":"A-01","location":"Front zone"},"in_receiving_area":false,"receiving_area":null,"in_staging_area":false,"staging_area":null,"with_driver":false,"driver":null}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"package_id":{"type":["integer","null"],"description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."}}},"example":{"result":false,"message":"Can't found the package","package_id":null,"order_id":null}}}},"401":{"description":"Not Auth","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":""}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inventories/receive-package":{"post":{"tags":["Inventories"],"summary":"Receive package by given orderId/ref/tracking/externalTracking/Inventory Ref","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Required. Search keyword to find and receive a package (order ID, ref, tracking number, or external tracking number).\n\n**Details:** Type `string`."},"warehouse_id":{"type":["string","null"],"description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `string` · Nullable."},"third_party_action":{"type":["string","null"],"enum":["continue_handover","withdraw_self",null],"description":"Optional. Only meaningful when the order is still held by a third-party carrier. 'continue_handover' (default when omitted) keeps the carrier and parks the order at Waiting Third Party Handover; 'withdraw_self' cancels the carrier order first and then receives the package back into self-delivery.\n\nAllowed values: `continue_handover` · `withdraw_self`.\n\n**Details:** Type `string` · Nullable."}},"required":["search"]},"example":{"search":"demo","warehouse_id":null,"third_party_action":null}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"channel_name":{"type":"string","description":"Channel name. Human-readable label.\n\n**Details:** Type `string`."},"order_status":{"type":"string","description":"Order status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`."},"location_id":{"type":"integer","description":"Location id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"location_name":{"type":"string","description":"Location name. Human-readable label.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."},"third_party_provider":{"type":"boolean","description":"Whether the order is currently assigned to a third-party delivery provider. Only present for non-customer callers; absent for customer callers.\n\n**Details:** Type `boolean`."},"third_party_provider_info":{"type":["object","null"],"description":"Present only when third_party_provider is true.\n\n**Details:** Type `object` · Nullable.","properties":{"provider":{"type":"string","description":"Provider. Field in the JSON request body.\n\n**Details:** Type `string`."},"external_order_number":{"type":["string","null"],"description":"External order number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}},"third_party_decision":{"type":["object","null"],"description":"Present only when the received order was held by a third-party carrier. Only present for non-customer callers.\n\n**Details:** Type `object` · Nullable.","properties":{"required":{"type":"boolean","description":"True when no third_party_action was sent, so the default was applied and the operator still has to confirm it.\n\n**Details:** Type `boolean`."},"applied":{"type":"string","description":"continue_handover or withdraw_self\n\n**Details:** Type `string`."},"assignment_no":{"type":"string","description":"Assignment no. Field in the JSON request body.\n\n**Details:** Type `string`."},"options":{"type":"array","description":"Selectable actions, default first.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"value":{"type":"string","description":"Value. Field in the JSON request body.\n\n**Details:** Type `string`."},"label":{"type":"string","description":"Label. Human-readable label.\n\n**Details:** Type `string`."}}}}}}}},"example":{"result":true,"message":"Package received successfully","id":1206,"ref":"","channel_name":"","order_status":"New","location_id":239,"location_name":"DEMO","tracking_number":"DEMO","external_tracking_number":"","third_party_provider":true,"third_party_provider_info":{"provider":"XXX EXPRESS","external_order_number":"DEMOXXXX"},"third_party_decision":{"required":true,"applied":"continue_handover","assignment_no":"TPD20260805052757QZVP4E","options":[{"value":"continue_handover","label":"Continue handover to carrier"},{"value":"withdraw_self","label":"Withdraw to self-delivery"}]}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"channel_name":{"type":"string","description":"Channel name. Human-readable label.\n\n**Details:** Type `string`."},"order_status":{"type":"string","description":"Order status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`."},"location_id":{"type":"integer","description":"Location id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"location_name":{"type":"string","description":"Location name. Human-readable label.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Order Status Not Allowed To Receive.","id":1206,"ref":"","channel_name":"","order_status":"New","location_id":239,"location_name":"DEMO","tracking_number":"DEMO","external_tracking_number":""}}}},"401":{"description":"Not Auth","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":""}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inventories/package-outbound":{"post":{"tags":["Inventories"],"summary":"Package outbound by given orderId/ref/tracking/externalTracking","description":"Mark a package as outbound. Only orders with status 'In Transit' can be marked as outbound.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["search"],"properties":{"search":{"type":"string","description":"**Required.**\n\nOrder ID, ref, tracking number, external tracking number, or package ID\n\n**Details:** Type `string`."},"warehouse_id":{"type":["integer","null"],"description":"Warehouse ID. If not provided, uses user's current location or order's location\n\n**Details:** Type `integer` · Nullable."}}},"example":{"search":"TRACK123","warehouse_id":5}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object"},"example":{"status":true,"message":"Package outbound successful","order_id":1206,"ref":"ORDER123","from_status":"In Transit","to_status":"Package Outbound","from_status_id":29,"to_status_id":41}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object"},"example":{"status":false,"message":"Order Status Not Allowed For Outbound.","order_id":1206,"ref":"ORDER123"}}}},"401":{"description":"Not Auth","content":{"application/json":{"schema":{"type":"object"},"example":{"result":false,"message":"You are not authenticated to outbound package"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inventories/stockin":{"post":{"tags":["Inventories"],"summary":"stock in by given orderId/ref/tracking/externalTracking/Inventory Ref","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"grid_code":{"type":"string","description":"Required. Grid code to assign the item to.\n\n**Details:** Type `string`."},"inventory_id":{"type":["string","null"],"description":"Optional. Existing inventory ID to stock in. If null, uses tracking/external_tracking_number to find the item.\n\n**Details:** Type `string` · Nullable."},"tracking_number":{"type":["string","null"],"description":"Optional. Tracking number to identify the item.\n\n**Details:** Type `string` · Nullable."},"external_tracking_number":{"type":"string","description":"Optional. External tracking number to identify the item.\n\n**Details:** Type `string`."},"inventory_type":{"type":"integer","description":"Optional. Inventory type (1: Package, 2: Product, 3: Storage Package, 4: Return, 5: Carrier Package). Defaults to 1.\n\n**Details:** Type `integer`."},"inventory_ref":{"type":"string","description":"Optional. Inventory reference code.\n\n**Details:** Type `string`."},"quantity":{"type":"integer","description":"Optional. Quantity. Defaults to 1.\n\n**Details:** Type `integer`."}}},"description":"Required. Array of items to stock in.\n\n**Details:** Type `array`, items `object`."},"warehouse_id":{"type":["string","null"],"description":"Optional. Warehouse ID. If not provided, uses default warehouse.\n\n**Details:** Type `string` · Nullable."}},"required":["data"]},"example":{"data":[{"grid_code":"GC001","inventory_id":null,"tracking_number":null,"external_tracking_number":"TRK001","inventory_type":1,"inventory_ref":"RefA","quantity":10},{"grid_code":"GC002","inventory_id":null,"tracking_number":"TRK002","external_tracking_number":null,"inventory_type":1,"inventory_ref":"RefB","quantity":20}],"warehouse_id":null}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"success_count":{"type":"integer","description":"Success count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"failed_count":{"type":"integer","description":"Failed count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"success":{"type":"array","items":{"type":"object","properties":{"grid_code":{"type":"string","description":"Grid code. Stable machine-readable code.\n\n**Details:** Type `string`."},"inventory_id":{"type":["string","null"],"description":"Inventory id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"tracking_number":{"type":["string","null"],"description":"Superroute or carrier tracking number.\n\n**Details:** Type `string` · Nullable."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."},"inventory_type":{"type":"integer","description":"Inventory type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"inventory_ref":{"type":"string","description":"Inventory ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`."}}},"description":"Success. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"failed":{"type":"array","items":{"type":"string","description":"Failed. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Failed. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"success_count":2,"failed_count":0,"success":[{"grid_code":"GC001","inventory_id":null,"tracking_number":null,"external_tracking_number":"TRK001","inventory_type":1,"inventory_ref":"RefA","quantity":10},{"grid_code":"GC002","inventory_id":null,"tracking_number":"TRK002","external_tracking_number":null,"inventory_type":1,"inventory_ref":"RefB","quantity":20}],"failed":[]}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"package_id":{"type":["string","null"],"description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"order_id":{"type":["string","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `string` · Nullable."}}},"example":{"result":false,"message":"Can't found the package","package_id":null,"order_id":null}}}},"401":{"description":"Not Auth","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":""}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inventories/stockout":{"post":{"tags":["Inventories"],"summary":"stock out by given orderId/ref/tracking/externalTracking/Inventory Ref","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Free-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string`."},"route_driver_id":{"type":["string","null"],"description":"Route driver id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."}}},"example":{"search":"demo","route_driver_id":null}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"package_id":{"type":"integer","description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."}}},"example":{"result":true,"message":"Package DEMO1 stock out from DEMO_WAREHOUSE's grid:DEMO_GRID","package_id":1102912,"order_id":938067}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"package_id":{"type":["string","null"],"description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"order_id":{"type":["string","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `string` · Nullable."}}},"example":{"result":false,"message":"Can't found the package","package_id":null,"order_id":null}}}},"401":{"description":"Not Auth","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":""}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inventories/stockoutlist/{id}":{"get":{"operationId":"inventoryDriverStockOutList","tags":["Inventories"],"summary":"get driver stock out list","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"alias":{"type":"string","description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"work_from":{"type":"string","description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string`."},"work_end":{"type":"string","description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string`."},"route_name":{"type":"string","description":"Route name. Human-readable label.\n\n**Details:** Type `string`."},"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"route_date":{"type":"string","description":"Route date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`."},"orders":{"type":"array","items":{"type":"object","properties":{"package_id":{"type":"integer","description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"inventory_ref":{"type":"string","description":"Inventory ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"grid_code":{"type":"string","description":"Grid code. Stable machine-readable code.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"telephone":{"type":["string","null"],"description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string` · Nullable."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string`."},"stop_number":{"type":"string","description":"Stop number. Field in the JSON request body.\n\n**Details:** Type `string`."},"weight":{"type":"string","description":"Weight of the package or shipment.\n\n**Details:** Type `string`."},"length":{"type":"integer","description":"Length dimension.\n\n**Details:** Type `integer`."},"width":{"type":"integer","description":"Width dimension.\n\n**Details:** Type `integer`."},"height":{"type":"integer","description":"Height dimension.\n\n**Details:** Type `integer`."},"weight_unit":{"type":"string","description":"Weight unit code from `Packages::WEIGHT_UNIT`: 1=g, 2=kg, 3=oz, 4=lb. Default 1.\n\n**Details:** Type `string`."},"dimension_unit":{"type":"string","description":"Dimension unit code from `Packages::DIMENSION_UNIT`: 1=mm, 2=cm, 3=m, 4=inch. Default 1.\n\n**Details:** Type `string`."}}},"description":"Orders. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}},"example":[{"result":true,"data":{"id":99999,"alias":"DEMO0","name":"Michael Brown","work_from":"09:00","work_end":"18:00","route_name":"DEMO-ROUTE","route_id":12345,"route_date":"2025-03-04","orders":[{"package_id":1000001,"order_id":900001,"inventory_ref":"DEMO-001","grid_code":"A-01-1","postcode":"XY1 1XY","name":"Emma Johnson","address_1":"10 Demo Street","address_2":"Apt 5","city":"Sampletown","province":"Demo County","country":"GB","telephone":null,"email":"emma.johnson@example.com","tracking_number":"DEMO123456789","external_tracking_number":"DEMO987654321","stop_number":"DEMO-1","weight":"5.000","length":50,"width":40,"height":30,"weight_unit":"kg","dimension_unit":"cm"},{"package_id":1000002,"order_id":900002,"inventory_ref":"DEMO-002","grid_code":"B-02-2","postcode":"XY2 2XY","name":"Liam Smith","address_1":"25 Example Avenue","address_2":"Suite 200","city":"Mocksville","province":"Demo State","country":"GB","telephone":null,"email":"liam.smith@example.com","tracking_number":"DEMO223344556","external_tracking_number":"DEMO667788990","stop_number":"DEMO-2","weight":"10.500","length":60,"width":50,"height":40,"weight_unit":"kg","dimension_unit":"cm"},{"package_id":1000003,"order_id":900003,"inventory_ref":"DEMO-003","grid_code":"C-03-3","postcode":"XY3 3XY","name":"Sophia Williams","address_1":"99 Placeholder Road","address_2":"Unit 8","city":"Testville","province":"Sample Region","country":"GB","telephone":null,"email":"sophia.williams@example.com","tracking_number":"DEMO998877665","external_tracking_number":"DEMO554433221","stop_number":"DEMO-3","weight":"7.800","length":55,"width":45,"height":35,"weight_unit":"kg","dimension_unit":"cm"}]}}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/inventories/stock-levels":{"get":{"operationId":"getInventoryStockLevels","tags":["Inventories"],"summary":"Stock levels per product / variant","description":"Lists every catalogue product / variant for the business (a product with no stock returns zeros). Quantities come from real physical WMS inventory in the inventories table. Without warehouse_id they are summed across all warehouses; with warehouse_id they reflect that warehouse only. Scoped to the authenticated business.","parameters":[{"in":"query","name":"warehouse_id","schema":{"type":"integer","description":"Filter to one warehouse (addressbook id, must belong to the business). Omit to sum across all warehouses.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Filter to one warehouse (addressbook id, must belong to the business). Omit to sum across all warehouses.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"product_id","schema":{"type":"integer","description":"Filter by product id\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Filter by product id\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"product_variant_id","schema":{"type":"integer","description":"Filter by product variant id\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Filter by product variant id\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"sku","schema":{"type":"string","description":"Filter by SKU (resolved to catalogue ids)\n\nStock keeping unit / product code.\n\n**Details:** Optional · Type `string`."},"required":false,"description":"Filter by SKU (resolved to catalogue ids)\n\nStock keeping unit / product code.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"search","schema":{"type":"string","description":"Search by SKU or product name\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Optional · Type `string`."},"required":false,"description":"Search by SKU or product name\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"in_stock_only","schema":{"type":"boolean","description":"Only rows with available quantity > 0\n\n**Details:** Optional · Type `boolean`."},"required":false,"description":"Only rows with available quantity > 0\n\n**Details:** Optional · Type `boolean`."},{"in":"query","name":"per_page","schema":{"type":"integer","description":"Page size (1-200, default 50)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Page size (1-200, default 50)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"page","schema":{"type":"integer","description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"required":false,"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"warehouse_id":{"type":["integer","null"],"description":"Echoes the requested warehouse filter; null when totals span all warehouses.\n\n**Details:** Type `integer` · Nullable."},"data":{"type":"array","items":{"type":"object","properties":{"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"product_id":{"type":["integer","null"],"description":"Product id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"product_variant_id":{"type":["integer","null"],"description":"Product variant id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"sku":{"type":["string","null"],"description":"Stock keeping unit / product code.\n\n**Details:** Type `string` · Nullable."},"product_name":{"type":["string","null"],"description":"Product name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"unique_code":{"type":["string","null"],"description":"Central UniqueCode for the product / variant.\n\n**Details:** Type `string` · Nullable."},"manage_stock":{"type":"boolean","description":"Manage stock. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"total_quantity":{"type":"integer","description":"Total quantity. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"reserved_quantity":{"type":"integer","description":"Reserved quantity. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"available_quantity":{"type":"integer","description":"Available quantity. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"warehouse_count":{"type":"integer","description":"Warehouse count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`."},"current_page":{"type":"integer","description":"Current page. Field in the JSON request body.\n\n**Details:** Type `integer`."},"last_page":{"type":"integer","description":"Last page. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Pagination. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/inventories/findroutebypackage":{"post":{"tags":["Inventories"],"summary":"find route by given order id/ref/tracking/externalTracking/Inventory Ref","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Required. Search keyword to find route by package (order ID, ref, tracking number, external tracking number, or inventory ref).\n\n**Details:** Type `string`."}},"required":["search"]},"example":{"search":"demo"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"route_id":{"type":"string","description":"Route id (`routes.id`).\n\n**Details:** Type `string`."},"route_name":{"type":"string","description":"Route name. Human-readable label.\n\n**Details:** Type `string`."},"route_date":{"type":"string","description":"Route date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`."},"territory_id":{"type":"string","description":"Territory id.\n\n**Details:** Type `string`."},"territory_name":{"type":"string","description":"Territory name. Human-readable label.\n\n**Details:** Type `string`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"need_stock_out":{"type":"integer","description":"Need stock out. Field in the JSON request body.\n\n**Details:** Type `integer`."},"already_stock_out":{"type":"integer","description":"Already stock out. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"message":"Successful","data":{"route_id":"Demo","route_name":"Demo","route_date":"Demo","territory_id":"Demo","territory_name":"Demo","total":12,"need_stock_out":3,"already_stock_out":9}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Route not found"}}}},"401":{"description":"Not Auth","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":""}}}}},"security":[{"bearerAuth":[]}]}},"/v1/package-activity":{"get":{"tags":["Inventories"],"summary":"Unified package activity log","description":"Operation events and message-sending records across carrier-upload and partner-locker packages. Internal accounts (client/admin/employee) see all packages of their business; partner accounts see only their providers; customer accounts see only their own packages. Recipient contact appears only as a mask.","parameters":[{"name":"reference","in":"query","required":false,"schema":{"type":"string","description":"Search by reference (delivery_no / inventory code / pickup code).\n\nExternal or internal reference string for correlation.\n\n**Details:** Optional · Type `string`."},"description":"Search by reference (delivery_no / inventory code / pickup code).\n\nExternal or internal reference string for correlation.\n\n**Details:** Optional · Type `string`."},{"name":"source","in":"query","required":false,"schema":{"type":"integer","description":"1=carrier upload, 2=partner locker.\n\nDocument or data source selector for this developer-center export.\n\n**Details:** Optional · Type `integer`."},"description":"1=carrier upload, 2=partner locker.\n\nDocument or data source selector for this developer-center export.\n\n**Details:** Optional · Type `integer`."},{"name":"subject_type","in":"query","required":false,"schema":{"type":"integer","description":"1=carrier package (inventory), 2=partner delivery.\n\n**Details:** Optional · Type `integer`."},"description":"1=carrier package (inventory), 2=partner delivery.\n\n**Details:** Optional · Type `integer`."},{"name":"subject_id","in":"query","required":false,"schema":{"type":"integer","description":"Inventory id or partner delivery id.\n\n**Details:** Optional · Type `integer`."},"description":"Inventory id or partner delivery id.\n\n**Details:** Optional · Type `integer`."},{"name":"event_type","in":"query","required":false,"schema":{"type":"string","description":"Filter events by type (e.g. stocked_in, notified, delivered).\n\n**Details:** Optional · Type `string`."},"description":"Filter events by type (e.g. stocked_in, notified, delivered).\n\n**Details:** Optional · Type `string`."},{"name":"channel","in":"query","required":false,"schema":{"type":"string","description":"Filter messages by channel (in_app / sms / email / webhook).\n\n**Details:** Optional · Type `string`."},"description":"Filter messages by channel (in_app / sms / email / webhook).\n\n**Details:** Optional · Type `string`."},{"name":"status","in":"query","required":false,"schema":{"type":"integer","description":"Filter messages by status (1=pending,2=sent,3=failed,4=skipped).\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `integer`."},"description":"Filter messages by status (1=pending,2=sent,3=failed,4=skipped).\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `integer`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","description":"Page size for each list (1-100, default 50).\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"Page size for each list (1-100, default 50).\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"events":{"type":"array","description":"Operation events.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"source":{"type":"integer","description":"Document or data source selector for this developer-center export.\n\n**Details:** Type `integer`."},"source_label":{"type":"string","description":"Source label. Human-readable label.\n\n**Details:** Type `string`."},"subject_type":{"type":"integer","description":"Subject type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"subject_label":{"type":"string","description":"Subject label. Human-readable label.\n\n**Details:** Type `string`."},"subject_id":{"type":"integer","description":"Subject id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"reference":{"type":["string","null"],"description":"External or internal reference string for correlation.\n\n**Details:** Type `string` · Nullable."},"event_type":{"type":"string","description":"Event type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"payload":{"type":["object","null"],"description":"Payload. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"occurred_at":{"type":["string","null"],"description":"When the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string` · Nullable."}}}},"messages":{"type":"array","description":"Message-sending records.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"source":{"type":"integer","description":"Document or data source selector for this developer-center export.\n\n**Details:** Type `integer`."},"source_label":{"type":"string","description":"Source label. Human-readable label.\n\n**Details:** Type `string`."},"subject_type":{"type":"integer","description":"Subject type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"subject_label":{"type":"string","description":"Subject label. Human-readable label.\n\n**Details:** Type `string`."},"subject_id":{"type":"integer","description":"Subject id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"reference":{"type":["string","null"],"description":"External or internal reference string for correlation.\n\n**Details:** Type `string` · Nullable."},"channel":{"type":"string","description":"Channel. Field in the JSON request body.\n\n**Details:** Type `string`."},"recipient_mask":{"type":["string","null"],"description":"Recipient mask. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"status_label":{"type":"string","description":"Status label. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`."},"provider_message_id":{"type":["string","null"],"description":"Provider message id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"error":{"type":["string","null"],"description":"Error. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"sent_at":{"type":["string","null"],"description":"Sent at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}}}}}}}}}}}},"/v1/inventories/carrier-staging-stockin":{"post":{"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first HTTP 200 answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-200 outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."},"description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first HTTP 200 answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-200 outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."}],"tags":["Inventories"],"summary":"Batch stock-in carrier packages to staging area","description":"Batch import carrier packages into the staging area (or directly to a grid if grid_code is provided). Declared size and weight (optional): a row may carry length / width / height / dimension_unit and weight / weight_unit. They are stored with the package and compared against the compartment limits twice — at upload against every locker compartment the site could shelve into, and again at the cabinet against the compartment the operator chose, which refuses to open for a parcel it cannot hold. A row no compartment at the site could ever hold fails on its own with code LOCKER_CAPACITY_SIZE_EXCEEDED, LOCKER_CAPACITY_WEIGHT_EXCEEDED or LOCKER_CAPACITY_SIZE_AND_WEIGHT_EXCEEDED; a malformed measurement fails with LOCKER_DECLARED_MEASUREMENT_INVALID. Sites with no locker shelving, compartments with no limit recorded, an incomplete set of edges and a weight without its unit all simply switch the matching check off. Accessible by client, admin, employee, partner, and customer users. Customer users require a carrier upload authorization (per carrier + warehouse) and warehouse_id is required. For customer users, grid_code is ignored and all items are placed in the staging area. The warehouse_id must be within the user's authorized scope. Maximum 1000 items per request. Multi-package orders (optional): set group_by_order=true and rows of the same request that share a non-empty carrier_order_id are tied into one pickup group with a shared group pickup code; each package keeps its own pickup code as well. Grouping is scoped to the request — the same carrier_order_id in a later request starts a new group. The group code opens/collects every package of the order that has been shelved at the receiving warehouse, and it is the code the recipient receives in the pickup notification.\n\n**carrier_id is the provider id** (the number on the partner portal's carrier directory and in X-Third-Party-Provider-Id), not the carrier setting's row id.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["carrier_id","data"],"properties":{"carrier_id":{"type":"integer","description":"Required. The carrier's **provider id** — the one shown on the partner portal's carrier directory, and the same value sent in X-Third-Party-Provider-Id. Not the carrier setting's own row id, which no request takes. An id that names no active carrier of this business answers 400 'Carrier not found or inactive.'\n\n**Details:** Type `integer`.\n\n**Example:** `4611`.","examples":[4611]},"warehouse_id":{"type":["integer","null"],"description":"Optional. The warehouse ID to stock into. Must be within the user's authorized scope. If not provided, defaults to the user's primary warehouse.\n\n**Details:** Type `integer` · Nullable."},"group_by_order":{"type":"boolean","default":false,"description":"Optional (default false). When true, rows of this request sharing a non-empty carrier_order_id (matched case-insensitively) are tied into one pickup group: the response adds group_id / group_pickup_code / group_sequence to each grouped row and a top-level groups[] summary. Rows without a carrier_order_id are never grouped. Rows that fail are simply not part of the group. Existing behaviour is unchanged when omitted.\n\n**Details:** Type `boolean` · Default: `false`."},"data":{"type":"array","description":"Required. Array of items to import (1-1000 items).\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"member_number":{"type":"string","maxLength":255,"description":"Conditionally required. Required if the carrier has member number enabled (has_member_number=true). If the carrier has both member number and tracking number enabled, at least one of member_number or carrier_reference_number must be provided.\n\n**Details:** Type `string` · maxLength `255`."},"carrier_reference_number":{"type":"string","maxLength":255,"description":"Conditionally required. Required if the carrier has tracking number enabled (has_tracking_number=true). If the carrier has both member number and tracking number enabled, at least one of member_number or carrier_reference_number must be provided.\n\n**Details:** Type `string` · maxLength `255`."},"carrier_order_id":{"type":"string","maxLength":255,"description":"Optional. Carrier order ID. With group_by_order=true, rows sharing this value are tied into one pickup group.\n\n**Details:** Type `string` · maxLength `255`."},"batch":{"type":"string","maxLength":255,"description":"Optional. Batch identifier.\n\n**Details:** Type `string` · maxLength `255`."},"ref":{"type":"string","maxLength":255,"description":"Optional. Reference code. Must be unique within the warehouse. Duplicate refs will be rejected.\n\n**Details:** Type `string` · maxLength `255`."},"grid_code":{"type":"string","maxLength":255,"description":"Optional. Grid code to assign the item to. If empty or not provided, the item will be placed in the staging area. If provided, the item will be assigned to the grid (auto-created if grid does not exist).\n\n**Details:** Type `string` · maxLength `255`."},"recipient_phone":{"type":"string","maxLength":32,"description":"Optional. Recipient phone for the pickup notification. Stored encrypted. When no member_number is bound to a registered customer, this (or recipient_email) is used to notify the recipient once the package is placed in a locker.\n\n**Details:** Type `string` · maxLength `32`."},"recipient_email":{"type":"string","maxLength":191,"description":"Optional. Recipient email for the pickup notification. Stored encrypted. When both recipient_phone and recipient_email are provided, both channels are sent.\n\n**Details:** Type `string` · maxLength `191`."},"length":{"type":"number","exclusiveMinimum":0,"description":"Optional. Declared length, in dimension_unit. The size check runs only when length, width, height and dimension_unit are all given; anything short of the four is stored as unmeasured and never refuses the parcel.\n\n**Details:** Type `number` · exclusiveMin `0`."},"width":{"type":"number","exclusiveMinimum":0,"description":"Optional. Declared width, in dimension_unit.\n\n**Details:** Type `number` · exclusiveMin `0`."},"height":{"type":"number","exclusiveMinimum":0,"description":"Optional. Declared height, in dimension_unit.\n\n**Details:** Type `number` · exclusiveMin `0`."},"dimension_unit":{"type":"string","enum":["mm","cm","m","ft","inch"],"description":"Optional. Unit of the three edges.\n\nEnum values:\n- `mm` — Millimetres\n- `cm` — Centimetres\n- `m` — Metres\n- `ft` — Feet\n- `inch` — Inches\n\n**Details:** Type `string`.","x-enumDescriptions":["Millimetres","Centimetres","Metres","Feet","Inches"]},"weight":{"type":"number","exclusiveMinimum":0,"description":"Optional. Declared weight, compared against each compartment's load limit. Needs weight_unit; a compartment with no limit of its own never refuses on weight.\n\n**Details:** Type `number` · exclusiveMin `0`."},"weight_unit":{"type":"string","enum":["kg","g","lb","oz"],"description":"Optional. Required when weight is given, and vice versa.\n\nAllowed values: `kg` · `g` · `lb` · `oz`.\n\n**Details:** Type `string`."}}}}}},"example":{"carrier_id":1,"warehouse_id":10,"data":[{"member_number":"MEM001","carrier_reference_number":"CRN001","carrier_order_id":"COD001","batch":"BATCH001","ref":"REF001","grid_code":"","recipient_phone":"+14165550123","recipient_email":"recipient@example.com","length":30,"width":20,"height":15,"dimension_unit":"cm","weight":2.5,"weight_unit":"kg"},{"member_number":"MEM002","carrier_reference_number":"CRN002","carrier_order_id":"","batch":"","ref":"REF002","grid_code":"A-01-01"}]}}},"required":true},"responses":{"409":{"description":"Idempotency conflict: the key was already used with a different body (IDEMPOTENCY_CONFLICT), or the original request is still processing (IDEMPOTENCY_IN_PROGRESS, with Retry-After: 1).","headers":{"Retry-After":{"description":"Present only on the IDEMPOTENCY_IN_PROGRESS answer: retry after this many seconds.","schema":{"type":"string","examples":[1]}}}},"200":{"headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome. The body also carries replayed: true.","schema":{"type":"string","enum":["true"]}}},"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Always true when request is processed.\n\n**Details:** Type `boolean`."},"total":{"type":"integer","description":"Total number of items submitted.\n\n**Details:** Type `integer`."},"success":{"type":"integer","description":"Number of successfully imported items.\n\n**Details:** Type `integer`."},"failed":{"type":"integer","description":"Number of failed items.\n\n**Details:** Type `integer`."},"data":{"type":"array","description":"Per-row results.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"row":{"type":"integer","description":"Row number (1-based).\n\n**Details:** Type `integer`."},"result":{"type":"boolean","description":"Whether this row succeeded.\n\n**Details:** Type `boolean`."},"inventory_id":{"type":"integer","description":"Created inventory ID (on success).\n\n**Details:** Type `integer`."},"inventory_code":{"type":"integer","description":"Auto-assigned inventory code (on success).\n\n**Details:** Type `integer`."},"pickup_code":{"type":"string","description":"Pickup code generated for the package (on success). The same code is later delivered to the recipient in the pickup notification.\n\n**Details:** Type `string`."},"grid_code":{"type":["string","null"],"description":"Grid code if assigned, null if in staging area (on success).\n\n**Details:** Type `string` · Nullable."},"location":{"type":"string","enum":["grid","staging_area"],"description":"Where the item was placed (on success).\n\nAllowed values: `grid` · `staging_area`.\n\n**Details:** Type `string`."},"message":{"type":"string","description":"Error message (on failure).\n\n**Details:** Type `string`."},"code":{"type":"string","enum":["LOCKER_DECLARED_MEASUREMENT_INVALID","LOCKER_CAPACITY_SIZE_EXCEEDED","LOCKER_CAPACITY_WEIGHT_EXCEEDED","LOCKER_CAPACITY_SIZE_AND_WEIGHT_EXCEEDED"],"description":"Present only on a row refused over its declared size or weight; every other failure carries message alone, exactly as before.\n\nAllowed values: `LOCKER_DECLARED_MEASUREMENT_INVALID` · `LOCKER_CAPACITY_SIZE_EXCEEDED` · `LOCKER_CAPACITY_WEIGHT_EXCEEDED` · `LOCKER_CAPACITY_SIZE_AND_WEIGHT_EXCEEDED`.\n\n**Details:** Type `string`."},"group_id":{"type":"integer","description":"Pickup group ID (only present when group_by_order=true and the row carried a carrier_order_id).\n\n**Details:** Type `integer`."},"group_pickup_code":{"type":"string","description":"Shared pickup code of the order group (only present when grouped). One code collects every package of the order; the per-package pickup_code stays valid too.\n\n**Details:** Type `string`."},"group_sequence":{"type":"integer","description":"1-based position of this package within its order group (only present when grouped).\n\n**Details:** Type `integer`."}}}},"groups":{"type":"array","description":"Only present when group_by_order=true. One entry per order that produced at least one successful row.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"carrier_order_id":{"type":"string","description":"The carrier_order_id as first submitted.\n\n**Details:** Type `string`."},"group_id":{"type":"integer","description":"Pickup group ID.\n\n**Details:** Type `integer`."},"pickup_code":{"type":"string","description":"Shared pickup code of the group.\n\n**Details:** Type `string`."},"submitted_count":{"type":"integer","description":"Rows of this request that named the order.\n\n**Details:** Type `integer`."},"package_count":{"type":"integer","description":"Rows that succeeded and joined the group (the group expects exactly these).\n\n**Details:** Type `integer`."},"inventory_ids":{"type":"array","items":{"type":"integer","description":"Inventory ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Inventory IDs in group sequence order.\n\n**Details:** Type `array`, items `integer`."}}}}}},"example":{"result":true,"total":2,"success":1,"failed":1,"data":[{"row":1,"result":true,"inventory_id":123,"inventory_code":1001,"pickup_code":482913,"grid_code":null,"location":"staging_area"},{"row":2,"result":false,"message":"Duplicate ref: REF002"}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Carrier not found or inactive."}}}},"401":{"description":"Not Auth","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Customer user not authorized for this carrier/warehouse combination","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"You are not authorized for this carrier/warehouse combination."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"errors":{"type":"object","properties":{"carrier_id":{"type":"array","items":{"type":"string","description":"Carrier id. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Carrier id. Identifier referencing the related record.\n\n**Details:** Type `array`, items `string`."}},"description":"Errors. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"message":"The carrier id field is required.","errors":{"carrier_id":["The carrier id field is required."]}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/tracking/{trackingNumber}":{"get":{"tags":["Tracking"],"summary":"Get public tracking info","description":"Get tracking events and delivery status for a package by its tracking number. Accepts tracking_number, external_tracking_number, or third_party_tracking_number. This is a public endpoint — no authentication required. Return reasons on failed stops are only included when the business marked them visible to the public.","security":[],"operationId":"getPublicTracking","parameters":[{"name":"trackingNumber","in":"path","required":true,"schema":{"type":"string","description":"Tracking number (internal, external, or third-party)\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR904766214130`."},"description":"Tracking number (internal, external, or third-party)\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR904766214130`.","example":"SR904766214130"}],"responses":{"200":{"description":"Tracking information found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Success`.","examples":["Success"]},"is_third_party_tracking":{"type":"boolean","description":"Whether this tracking uses a third-party carrier\n\n**Details:** Type `boolean`.","examples":[false]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `M5V 2T6`.","examples":["M5V 2T6"]},"deliveried":{"type":"boolean","description":"Whether the package has been delivered\n\n**Details:** Type `boolean`.","examples":[false]},"returntosender":{"type":"boolean","description":"Returntosender. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"rejectedbyrecipient":{"type":"boolean","description":"Rejectedbyrecipient. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"data":{"type":"array","description":"Tracking events in chronological order\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"tracking_event_status_id":{"type":"integer","description":"Tracking event status id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","examples":[3]},"updated_at":{"type":"string","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`.\n\n**Example:** `2026-03-10 14:30:00`.","examples":["2026-03-10 14:30:00"]},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`.\n\n**Example:** `Package picked up`.","examples":["Package picked up"]},"location_name":{"type":["string","null"],"description":"Location name. Human-readable label.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Toronto Warehouse`.","examples":["Toronto Warehouse"]},"location_city":{"type":["string","null"],"description":"Location city. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Toronto`.","examples":["Toronto"]},"location_province":{"type":["string","null"],"description":"Location province. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable.","examples":["ON"]},"location_country":{"type":["string","null"],"description":"Location country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string` · Nullable.","examples":["CA"]},"location_postcode":{"type":["string","null"],"description":"Location postcode. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `M5V 2T6`.","examples":["M5V 2T6"]},"reason":{"type":["string","null"],"description":"Return reason recorded on a failed delivery/pickup stop. The public surface only includes reasons the business marked as visible to the public; a non-public reason is returned as null (the authenticated client tracking endpoint returns every reason).\n\n**Details:** Type `string` · Nullable."},"time_zone":{"type":"string","description":"Time zone. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `America/Toronto`.","examples":["America/Toronto"]},"gmt_offset":{"type":"string","description":"Gmt offset. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `-05:00`.","examples":["-05:00"]},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `12345`.","examples":[12345]},"timestamp":{"type":"integer","description":"Timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`.\n\n**Example:** `1741614600`.","examples":[1741614600]},"updated_at_localized":{"type":"string","description":"Updated at localized. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `2026-03-10 14:30:00`.","examples":["2026-03-10 14:30:00"]}}}},"proofs":{"type":"array","description":"Delivery proof photos. type: 1=signature, 2=photo. file_id is a stable id usable for consumer-side dedup and incremental sync. signed_url is an expiring alternative to the permanent public link (re-query tracking for a fresh one after signed_url_expires_at).\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"url":{"type":"string","description":"Url. Absolute or relative URL.\n\n**Details:** Type `string`.\n\n**Example:** `/storage/proof/photo.jpg`.","examples":["/storage/proof/photo.jpg"]},"full_url":{"type":"string","description":"Full url. Absolute or relative URL.\n\n**Details:** Type `string`.\n\n**Example:** `https://api.example.com/storage/proof/photo.jpg`.","examples":["https://api.example.com/storage/proof/photo.jpg"]},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`.\n\n**Example:** `image/jpeg`.","examples":["image/jpeg"]},"file_id":{"type":"integer","description":"File id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `234567`.","examples":[234567]},"uploaded_at":{"type":"string","description":"Uploaded at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`.\n\n**Example:** `2026-03-10 14:30:00`.","examples":["2026-03-10 14:30:00"]},"uploaded_timestamp":{"type":"integer","description":"Uploaded timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`.\n\n**Example:** `1773171000`.","examples":[1773171000]},"signed_url":{"type":"string","description":"Signed url. Absolute or relative URL.\n\n**Details:** Type `string`.\n\n**Example:** `https://api.example.com/files/pod/234567?expires=1773775800&signature=...`.","examples":["https://api.example.com/files/pod/234567?expires=1773775800&signature=..."]},"signed_url_expires_at":{"type":"integer","description":"Signed url expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`.\n\n**Example:** `1773775800`.","examples":[1773775800]},"tracking_event_id":{"type":["integer","null"],"description":"Tracking event the proof was captured for. A file uploaded on its own, with no event recorded, is read off the order's timeline: the outcome it was uploaded right before (what the driver went on to report) or right after (what the driver had already reported). null only when the order has no such outcome.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_status_id":{"type":["integer","null"],"description":"Status code of that event (500 delivered, 504 partially delivered, 510 picked up, 501/502/503 failed delivery, 512/513 failed pickup, …). null without an event.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_key":{"type":["string","null"],"description":"Stable key of that event status (deliver_success, pickuped, not_delivered, …). null without an event.\n\n**Details:** Type `string` · Nullable."},"service_type":{"type":["integer","null"],"enum":[1,2,null],"description":"Code of the service the proof belongs to, derived from the event's leg type: 1 = delivery, 2 = pickup. null without an event.\n\nAllowed values: `1` · `2` · `null`.\n\n**Details:** Type `integer` · Nullable."},"service_status":{"type":["integer","null"],"enum":[1,2,null],"description":"Code of the outcome the proof documents, derived from the event status: 1 = success (500, 504, 510), 2 = failed (501, 502, 503, 512, 513). null without an event or for other statuses.\n\nAllowed values: `1` · `2` · `null`.\n\n**Details:** Type `integer` · Nullable."}}}},"third_party_info":{"type":["object","null"],"description":"Present when is_third_party_tracking is true\n\n**Details:** Type `object` · Nullable.","properties":{"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`.\n\n**Example:** `1Z999AA10123456784`.","examples":["1Z999AA10123456784"]},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`.\n\n**Example:** `In Transit`.","examples":["In Transit"]},"shipping_service":{"type":"string","description":"Shipping service. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `UPS Ground`.","examples":["UPS Ground"]},"carrier_tracking_link":{"type":"string","description":"Carrier tracking link. Absolute or relative URL.\n\n**Details:** Type `string`.\n\n**Example:** `https://www.ups.com/track?tracknum=1Z999AA10123456784`.","examples":["https://www.ups.com/track?tracknum=1Z999AA10123456784"]}}}}}}}},"404":{"description":"Tracking number not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Tracking number not found`.","examples":["Tracking number not found"]}}}}}}}}},"/v1/tracking/generateTrackingNumber":{"post":{"tags":["Tracking"],"summary":"Generate tracking numbers","description":"Generate one or more tracking numbers with optional prefix, suffix, and length. Authentication required.","operationId":"generateTrackingNumber","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"integer","default":1,"description":"Number of tracking numbers to generate\n\n**Details:** Type `integer` · Default: `1`.\n\n**Example:** `5`.","examples":[5]},"prefix":{"type":"string","description":"Optional prefix for tracking number\n\n**Details:** Type `string`.\n\n**Example:** `ABC`.","examples":["ABC"]},"suffix":{"type":"string","description":"Optional suffix for tracking number\n\n**Details:** Type `string`.\n\n**Example:** `XYZ`.","examples":["XYZ"]},"length":{"type":"integer","description":"Length of the tracking number (excluding prefix and suffix)\n\n**Details:** Type `integer`.\n\n**Example:** `12`.","examples":[12]}}}}}},"responses":{"200":{"description":"Successful generation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"array","items":{"type":"string","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`.\n\n**Example:** `ABC123456789XYZ`.","examples":["ABC123456789XYZ"]},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."}}}}}},"401":{"description":"Unauthorized - user not authenticated","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `You are not authenticated to receive package`.","examples":["You are not authenticated to receive package"]}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `An unexpected error occurred.`.","examples":["An unexpected error occurred."]}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/tracking/lookupPackageInfo":{"post":{"tags":["Tracking"],"summary":"Lookup package info by search","description":"Search package by any identifier (package_id, tracking_number, external_tracking_number, third_party_tracking_number). Returns all tracking numbers for the package. Client/Employee can query own business and alliance partners. Customer can only query own orders.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["search"],"properties":{"search":{"type":"string","description":"**Required.**\n\nAny tracking number or package ID\n\n**Details:** Type `string`.\n\n**Example:** `SR904766214130`.","examples":["SR904766214130"]}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"result":true,"message":"Success","data":{"package_id":12345,"order_id":67890,"tracking_number":"SR904766214130","external_tracking_number":"EXT123456789","third_party_tracking_number":"1Z999AA10123456784","is_alliance_data":false}}}}},"404":{"description":"Package not found"}},"security":[{"bearerAuth":[]}]}},"/v1/tracking/operationevents":{"post":{"tags":["Tracking"],"summary":"get operation events","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetShippingLabel"},"examples":{"ORDER_ID":{"value":{"type":"ORDER_ID","id":[1,2,3]}},"TRACKING_NUMBER":{"value":{"type":"TRACKING_NUMBER","id":["X11XXX","X22XXX","X33XXX"]}},"EXTERNAL_TRACKING_NUMBER":{"value":{"type":"EXTERNAL_TRACKING_NUMBER","id":["X11XXX","X22XXX","X33XXX"]}}}}},"required":true},"responses":{"200":{"description":"Successful operation - returns an array of operation events expanded per package belonging to each matched order","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Operation event ID\n\n**Details:** Type `integer`.\n\n**Example:** `18458`.","examples":[18458]},"user_id":{"type":["integer","null"],"description":"ID of the user who triggered the event\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `123`.","examples":[123]},"ip_address":{"type":["string","null"],"description":"IP address that produced the event\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `192.168.1.10`.","examples":["192.168.1.10"]},"operation_category":{"type":"integer","description":"Operation category code\n\n**Details:** Type `integer`.\n\n**Example:** `2`.","examples":[2]},"operation_type":{"type":"integer","description":"Operation type code\n\n**Details:** Type `integer`.\n\n**Example:** `100`.","examples":[100]},"operation_description":{"type":["string","null"],"description":"Free text description of the operation\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Picked up at warehouse`.","examples":["Picked up at warehouse"]},"route_id":{"type":["integer","null"],"description":"Route id (`routes.id`).\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `5678`.","examples":[5678]},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `17341`.","examples":[17341]},"before_status":{"type":["integer","null"],"description":"Order status before the event\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `100`.","examples":[100]},"after_status":{"type":["integer","null"],"description":"Order status after the event\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `300`.","examples":[300]},"tracking_event_id":{"type":["integer","null"],"description":"Tracking event id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `25`.","examples":[25]},"location_id":{"type":["integer","null"],"description":"Address book ID where the event happened\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `88`.","examples":[88]},"location_information":{"type":["object","null"],"description":"Resolved location details for location_id\n\n**Details:** Type `object` · Nullable.","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Main Warehouse`.","examples":["Main Warehouse"]},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`.\n\n**Example:** `123 Main St`.","examples":["123 Main St"]},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`.\n\n**Example:** `Unit 4`.","examples":["Unit 4"]},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`.\n\n**Example:** `Toronto`.","examples":["Toronto"]},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`.","examples":["ON"]},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `M5V2T6`.","examples":["M5V2T6"]},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `12`.","examples":[12]},"territory_name":{"type":["string","null"],"description":"Territory name. Human-readable label.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Downtown`.","examples":["Downtown"]}}},"gps_tracking_id":{"type":["integer","null"],"description":"Gps tracking id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `9001`.","examples":[9001]},"latitude":{"type":["number","null"],"format":"float","description":"Latitude resolved from gps_tracking_id (null when no GPS record)\n\n**Details:** Type `number`, format `float` · Nullable.\n\n**Example:** `43.65107`.","examples":[43.65107]},"longitude":{"type":["number","null"],"format":"float","description":"Longitude resolved from gps_tracking_id (null when no GPS record)\n\n**Details:** Type `number`, format `float` · Nullable.\n\n**Example:** `-79.347015`.","examples":[-79.347015]},"created_at":{"type":"string","format":"date-time","description":"UTC creation timestamp\n\n**Details:** Type `string`, format `date-time`.\n\n**Example:** `2026-04-27T12:34:56.000000Z`.","examples":["2026-04-27T12:34:56.000000Z"]},"updated_at":{"type":"string","format":"date-time","description":"UTC update timestamp\n\n**Details:** Type `string`, format `date-time`.\n\n**Example:** `2026-04-27T12:34:56.000000Z`.","examples":["2026-04-27T12:34:56.000000Z"]},"time_zone":{"type":["string","null"],"description":"Time zone of the order's business owner\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `America/Toronto`.","examples":["America/Toronto"]},"created_at_localized":{"type":"string","description":"created_at converted to time_zone\n\n**Details:** Type `string`.\n\n**Example:** `2026-04-27 08:34:56`.","examples":["2026-04-27 08:34:56"]},"updated_at_localized":{"type":"string","description":"updated_at converted to time_zone\n\n**Details:** Type `string`.\n\n**Example:** `2026-04-27 08:34:56`.","examples":["2026-04-27 08:34:56"]},"tracking_event_status_id":{"description":"Tracking event status code (empty string when no tracking event linked)\n\n**Example:** `300`.","oneOf":[{"type":"integer","description":"Tracking event status id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},{"type":"string","description":"Tracking event status id. Identifier referencing the related record.\n\n**Details:** Type `string`."}],"examples":[300]},"tracking_event_descrption":{"type":"object","description":"Localized tracking event description keyed by language code (en, chs, cht, de, es, fr, it, nl, pt, sr, hu, pl, sk, cs). Empty array when no tracking event is linked.\n\n**Details:** Type `object`.","additionalProperties":{"type":"string","description":"Tracking event descrption. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"examples":[{"en":"Picked up","chs":"已揽收","fr":"Ramassé"}]},"order_ref":{"type":"string","description":"Order reference number\n\n**Details:** Type `string`.\n\n**Example:** `ORD-1001`.","examples":["ORD-1001"]},"package_id":{"type":"integer","description":"Package ID associated with this row\n\n**Details:** Type `integer`.\n\n**Example:** `50231`.","examples":[50231]},"tracking_number":{"type":"string","description":"Internal tracking number\n\n**Details:** Type `string`.\n\n**Example:** `SR123456789`.","examples":["SR123456789"]},"external_tracking_number":{"type":["string","null"],"description":"External carrier tracking number\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `1Z999AA10123456784`.","examples":["1Z999AA10123456784"]},"type":{"type":"string","description":"Order type (e.g. D = delivery, P = pickup)\n\n**Details:** Type `string`.","examples":["D"]},"return_reason":{"type":"string","description":"Return reason text. Auto-filled to 'Unable To Delivery' or 'Delivery Cancelled' for the corresponding operation types.\n\n**Details:** Type `string`.","examples":[""]},"shipping_to":{"type":"object","description":"Recipient address. Empty object when order type is P (pickup).\n\n**Details:** Type `object`.","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `John Doe`.","examples":["John Doe"]},"company_name":{"type":"string","description":"Contact company name at the stop.\n\n**Details:** Type `string`.\n\n**Example:** `Acme Inc.`.","examples":["Acme Inc."]},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`.\n\n**Example:** `+1-416-555-0100`.","examples":["+1-416-555-0100"]},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`.\n\n**Example:** `john@example.com`.","examples":["john@example.com"]},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`.\n\n**Example:** `456 King St W`.","examples":["456 King St W"]},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`.\n\n**Example:** `Suite 200`.","examples":["Suite 200"]},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`.\n\n**Example:** `Toronto`.","examples":["Toronto"]},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`.","examples":["ON"]},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`.","examples":[""]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `M5V1K4`.","examples":["M5V1K4"]}}},"shipping_from":{"type":"object","description":"Sender address. For pickup orders this carries the pickup address; for delivery orders it is decoded from orders.shipping_from JSON when present.\n\n**Details:** Type `object`.","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"company_name":{"type":"string","description":"Contact company name at the stop.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."}}},"has_proof":{"type":"boolean","description":"Whether any proof file is attached to this event\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"proofs":{"type":"array","description":"Attached proof files (photos, signatures, etc.)\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"url":{"type":"string","description":"Relative storage URL\n\n**Details:** Type `string`.\n\n**Example:** `/storage/proofs/2026/04/abc123.jpg`.","examples":["/storage/proofs/2026/04/abc123.jpg"]},"full_url":{"type":"string","description":"Absolute URL on the order owner's API domain\n\n**Details:** Type `string`.\n\n**Example:** `https://api.superroute.ca/storage/proofs/2026/04/abc123.jpg`.","examples":["https://api.superroute.ca/storage/proofs/2026/04/abc123.jpg"]},"type":{"type":"string","description":"File type (e.g. image, signature)\n\n**Details:** Type `string`.","examples":["image"]},"tracking_event_id":{"type":["integer","null"],"description":"Tracking event the proof was captured for. A file uploaded on its own, with no event recorded, is read off the order's timeline: the outcome it was uploaded right before (what the driver went on to report) or right after (what the driver had already reported). null only when the order has no such outcome.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_status_id":{"type":["integer","null"],"description":"Status code of that event (500 delivered, 504 partially delivered, 510 picked up, 501/502/503 failed delivery, 512/513 failed pickup, …). null without an event.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_key":{"type":["string","null"],"description":"Stable key of that event status (deliver_success, pickuped, not_delivered, …). null without an event.\n\n**Details:** Type `string` · Nullable."},"service_type":{"type":["integer","null"],"enum":[1,2,null],"description":"Code of the service the proof belongs to, derived from the event's leg type: 1 = delivery, 2 = pickup. null without an event.\n\nAllowed values: `1` · `2` · `null`.\n\n**Details:** Type `integer` · Nullable."},"service_status":{"type":["integer","null"],"enum":[1,2,null],"description":"Code of the outcome the proof documents, derived from the event status: 1 = success (500, 504, 510), 2 = failed (501, 502, 503, 512, 513). null without an event or for other statuses.\n\nAllowed values: `1` · `2` · `null`.\n\n**Details:** Type `integer` · Nullable."}}}}}}},"examples":{"Sample":{"value":[{"id":18458,"user_id":123,"ip_address":"192.168.1.10","operation_category":2,"operation_type":100,"operation_description":"Picked up at warehouse","route_id":5678,"order_id":17341,"before_status":100,"after_status":300,"tracking_event_id":25,"location_id":88,"location_information":{"name":"Main Warehouse","address_1":"123 Main St","address_2":"Unit 4","city":"Toronto","province":"ON","country":"CA","postcode":"M5V2T6","territory_id":12,"territory_name":"Downtown"},"gps_tracking_id":9001,"latitude":43.65107,"longitude":-79.347015,"created_at":"2026-04-27T12:34:56.000000Z","updated_at":"2026-04-27T12:34:56.000000Z","time_zone":"America/Toronto","created_at_localized":"2026-04-27 08:34:56","updated_at_localized":"2026-04-27 08:34:56","tracking_event_status_id":300,"tracking_event_descrption":{"en":"Picked up","chs":"已揽收","fr":"Ramassé"},"order_ref":"ORD-1001","package_id":50231,"tracking_number":"SR123456789","external_tracking_number":"1Z999AA10123456784","type":"D","return_reason":"","shipping_to":{"name":"John Doe","company_name":"Acme Inc.","telephone":"+1-416-555-0100","email":"john@example.com","address_1":"456 King St W","address_2":"Suite 200","city":"Toronto","province":"ON","country":"CA","code":"","postcode":"M5V1K4"},"shipping_from":[],"has_proof":true,"proofs":[{"url":"/storage/proofs/2026/04/abc123.jpg","full_url":"https://api.superroute.ca/storage/proofs/2026/04/abc123.jpg","type":"image","tracking_event_id":8261082,"tracking_event_status_id":500,"tracking_event_key":"deliver_success","service_type":1,"service_status":1}]}]}}}}},"400":{"description":"Bad Request - ID must be provided","content":{"application/json":{"schema":{"type":"string","examples":["ID must be provider"]}}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/tracking/submitExternalTrackingEvent":{"post":{"summary":"Submit external tracking event","operationId":"submitExternalTrackingEvent","tags":["Tracking"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","tracking_number","events"],"properties":{"type":{"type":"string","enum":["A","R"],"description":"**Required.**\n\nA = append, R = replace\n\nAllowed values: `A` · `R`.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"**Required.**\n\nInternal tracking number\n\n**Details:** Type `string`."},"external_tracking_number":{"type":"string","description":"External tracking number (optional)\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"events":{"type":"array","items":{"type":"object","required":["tracking_event_type","tracking_event_status_id"],"properties":{"tracking_event_type":{"type":"string","enum":["D","P"],"description":"**Required.**\n\nAllowed values: `D` · `P`.\n\n**Details:** Type `string`."},"tracking_event_status_id":{"type":"integer","enum":[100,300,301,400,401,402,403,450,500,501,502,503,460,510,512,513,600],"description":"**Required.**\n\nAllowed values: `100` · `300` · `301` · `400` · `401` · `402` · `403` · `450` · `500` · `501` · `502` · `503` · `460` · `510` · `512` · `513` · `600`.\n\n**Details:** Type `integer`."},"tracking_event_descrption":{"type":"string","description":"Tracking event descrption. Field in the JSON request body.\n\n**Details:** Type `string`."},"tracking_event_location":{"type":"string","description":"Tracking event location. Field in the JSON request body.\n\n**Details:** Type `string`."},"updated_at":{"type":"string","format":"date-time","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`.\n\n**Example:** `2024-04-30T15:00:00-04:00`.","examples":["2024-04-30T15:00:00-04:00"]}}},"description":"**Required.**\n\nEvents. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"responses":{"200":{"description":"Submission successful","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Tracking event submitted`.","examples":["Tracking event submitted"]},"data":{"type":"object","properties":{"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`.\n\n**Example:** `SR123456789`.","examples":["SR123456789"]}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Unauthorized"},"422":{"description":"Validation failed"}}}},"/v1/ocr/label":{"post":{"tags":["OCR"],"summary":"Parse shipping label via OCR","description":"Accepts an uploaded file (image, PDF, HEIC, WebP, or archive) and extracts shipping label fields.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"**Required.**\n\nFile. Field in the JSON request body.\n\n**Details:** Type `string`, format `binary`."}},"required":["file"]}}}},"responses":{"200":{"description":"OK - Parsed shipping label fields","content":{"application/json":{"schema":{"type":"object","properties":{"Shipping Company":{"type":"string","description":"Shipping company. Field in the JSON request body.\n\n**Details:** Type `string`."},"Recipient Name":{"type":"string","description":"Recipient name. Human-readable label.\n\n**Details:** Type `string`."},"Recipient Address":{"type":"string","description":"Recipient address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"Recipient Postal Code":{"type":"string","description":"Recipient postal code. Stable machine-readable code.\n\n**Details:** Type `string`."},"Tracking Number":{"type":"string","description":"Tracking number. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"result":true,"hasError":true,"data":[[{"shipping_company":"DEMO","recipient_name":"DEMO","full_address":"DEMO,DEMO,DEMO,ON,Canada,L8R0A5","address":{"address_1":"DEMO","address_2":"DEMO","city":"DEMO","province":"ON","country":"CA","postcode":"L8R0A5"},"tracking_number":""}]],"error":[{"tracking_number":"Not Visable"}]}}}},"422":{"description":"Unprocessable Entity - Invalid or unsupported file","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"error":"Unsupported file format."}}}},"500":{"description":"Internal Server Error - Unexpected system error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"error":"An unexpected error occurred."}}}}},"security":[{"bearerAuth":[]}]}},"/v1/poi/types":{"get":{"tags":["POI"],"summary":"Get available POI types for users (Driver/Client/Customer)","description":"Returns POI types available to the authenticated user, including their own business POI types and shared POI types. Returns field definitions, types, options, layout and multilingual names. Optional ID parameter to get specific POI type.","parameters":[{"name":"id","in":"query","required":false,"description":"Optional POI type ID to get specific POI type\n\nResource identifier.\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Optional POI type ID to get specific POI type\n\nResource identifier.\n\n**Details:** Optional · Type `integer`."}}],"responses":{"200":{"description":"OK - List of available POI types","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"poi_type_code":{"type":"string","description":"Poi type code. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"display_name":{"type":"object","properties":{"en":{"type":"string","description":"En. Field in the JSON request body.\n\n**Details:** Type `string`."},"chs":{"type":"string","description":"Chs. Field in the JSON request body.\n\n**Details:** Type `string`."},"cht":{"type":"string","description":"Cht. Field in the JSON request body.\n\n**Details:** Type `string`."},"de":{"type":"string","description":"De. Field in the JSON request body.\n\n**Details:** Type `string`."},"es":{"type":"string","description":"Es. Field in the JSON request body.\n\n**Details:** Type `string`."},"fr":{"type":"string","description":"Fr. Field in the JSON request body.\n\n**Details:** Type `string`."},"it":{"type":"string","description":"It. Field in the JSON request body.\n\n**Details:** Type `string`."},"nl":{"type":"string","description":"Nl. Field in the JSON request body.\n\n**Details:** Type `string`."},"pt":{"type":"string","description":"Pt. Field in the JSON request body.\n\n**Details:** Type `string`."}},"description":"Display name. Human-readable label.\n\n**Details:** Type `object`."},"color":{"type":["string","null"],"description":"Color. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"is_share":{"type":"boolean","description":"Is share. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"business_id":{"type":["integer","null"],"description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"form":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"layout":{"type":"string","enum":["single","multi"],"default":"single","description":"Allowed values: `single` · `multi`.\n\n**Details:** Type `string` · Default: `single`."},"fields":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Unique field code identifier\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"type":{"type":"string","enum":["text","textarea","number","email","tel","date","datetime-local","select","checkbox","radio","file"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `text` · `textarea` · `number` · `email` · `tel` · `date` · `datetime-local` · `select` · `checkbox` · `radio` · `file`.\n\n**Details:** Type `string`."},"display_name":{"type":"object","properties":{"en":{"type":"string","description":"En. Field in the JSON request body.\n\n**Details:** Type `string`."},"chs":{"type":"string","description":"Chs. Field in the JSON request body.\n\n**Details:** Type `string`."},"cht":{"type":"string","description":"Cht. Field in the JSON request body.\n\n**Details:** Type `string`."},"de":{"type":"string","description":"De. Field in the JSON request body.\n\n**Details:** Type `string`."},"es":{"type":"string","description":"Es. Field in the JSON request body.\n\n**Details:** Type `string`."},"fr":{"type":"string","description":"Fr. Field in the JSON request body.\n\n**Details:** Type `string`."},"it":{"type":"string","description":"It. Field in the JSON request body.\n\n**Details:** Type `string`."},"nl":{"type":"string","description":"Nl. Field in the JSON request body.\n\n**Details:** Type `string`."},"pt":{"type":"string","description":"Pt. Field in the JSON request body.\n\n**Details:** Type `string`."}},"description":"Display name. Human-readable label.\n\n**Details:** Type `object`."},"required":{"type":"boolean","description":"Required. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"placeholder":{"type":"string","description":"Placeholder. Field in the JSON request body.\n\n**Details:** Type `string`."},"validation":{"type":"array","items":{"type":"string","description":"Validation. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Validation. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"default_value":{"type":"string","description":"Default value. Field in the JSON request body.\n\n**Details:** Type `string`."},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","description":"Value. Field in the JSON request body.\n\n**Details:** Type `string`."},"label":{"type":"string","description":"Label. Human-readable label.\n\n**Details:** Type `string`."}}},"description":"Options. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"min":{"type":"number","description":"Min. Field in the JSON request body.\n\n**Details:** Type `number`."},"max":{"type":"number","description":"Max. Field in the JSON request body.\n\n**Details:** Type `number`."},"step":{"type":"number","description":"Step. Field in the JSON request body.\n\n**Details:** Type `number`."},"rows":{"type":"integer","description":"Rows. Field in the JSON request body.\n\n**Details:** Type `integer`."},"accept":{"type":"string","description":"Accept. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"description":"Fields. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Form. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"success":true,"data":[{"id":1,"poi_type_code":"RESTAURANT","name":"Restaurant","display_name":{"en":"Restaurant","chs":"餐厅","cht":"餐廳","fr":"Restaurant"},"color":"#FF6B6B","is_share":true,"business_id":null,"form":{"id":10,"name":"Restaurant Form","layout":"single","fields":[{"code":"cuisine_type","name":"cuisine_type","type":"select","display_name":{"en":"Cuisine Type","chs":"菜系类型","cht":"菜系類型"},"required":true,"placeholder":"Select cuisine type","validation":["required"],"default_value":"","options":[{"value":"chinese","label":"Chinese"},{"value":"italian","label":"Italian"},{"value":"french","label":"French"}]},{"code":"opening_hours","name":"opening_hours","type":"text","display_name":{"en":"Opening Hours","chs":"营业时间","cht":"營業時間"},"required":false,"placeholder":"e.g., 9:00 AM - 10:00 PM","validation":[],"default_value":""}]}}]}}}},"401":{"description":"Unauthorized - Invalid or missing authentication token, or no permission to access the specified POI type","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"examples":{"unauthenticated":{"value":{"success":false,"message":"Unauthenticated."}},"no_permission":{"value":{"success":false,"message":"No permission to access this POI type"}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/poi/list":{"post":{"tags":["POI"],"summary":"Get POIs with filtering options","description":"Retrieves POIs based on various filtering criteria including POI types, shared POIs, and distance from a center point. If no center point is provided, uses the user's work location.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"poi_types":{"type":["array","null"],"items":{"type":"string","description":"Poi types. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"description":"Array of POI type codes to filter by. If not provided, returns all POI types.\n\n**Details:** Type `array`, items `string` · Nullable."},"include_shared":{"type":["boolean","null"],"default":false,"description":"Whether to include shared POIs from other businesses\n\n**Details:** Type `boolean` · Default: `false` · Nullable."},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude of center point. If not provided, uses user's work location.\n\n**Details:** Type `number` · Nullable · min `-90` · max `90`."},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude of center point. If not provided, uses user's work location.\n\n**Details:** Type `number` · Nullable · min `-180` · max `180`."},"range_limit":{"type":["number","null"],"minimum":0,"default":0,"description":"Distance limit in meters from center point. 0 means no limit. Requires explicit center coordinates if > 0.\n\n**Details:** Type `number` · Default: `0` · Nullable · min `0`."}}},"example":{"poi_types":["restaurant","gas_station"],"include_shared":true,"latitude":45.5016889,"longitude":-73.567256,"range_limit":500}}}},"responses":{"200":{"description":"OK - POIs retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"pois":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"latitude":{"type":"number","description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`."},"longitude":{"type":"number","description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`."},"address":{"type":["string","null"],"description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"address_1":{"type":["string","null"],"description":"Primary street address line for the stop.\n\n**Details:** Type `string` · Nullable."},"address_2":{"type":["string","null"],"description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string` · Nullable."},"city":{"type":["string","null"],"description":"City / locality.\n\n**Details:** Type `string` · Nullable."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"country":{"type":["string","null"],"description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string` · Nullable."},"postal_code":{"type":["string","null"],"description":"Postal code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"distance":{"type":"number","description":"Distance in meters from the center point\n\n**Details:** Type `number`."},"poi_type":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"poi_type_code":{"type":"string","description":"Poi type code. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"display_name":{"type":"object","description":"Display name. Human-readable label.\n\n**Details:** Type `object`."},"color":{"type":["string","null"],"description":"Color. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}},"description":"Poi type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `object`."}}},"description":"Pois. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"center":{"type":"object","properties":{"lat":{"type":"number","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`."},"lng":{"type":"number","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`."}},"description":"Center. Field in the JSON request body.\n\n**Details:** Type `object`."},"total":{"type":"integer","description":"Total number of POIs returned\n\n**Details:** Type `integer`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"success":true,"data":{"pois":[{"id":1,"name":"McDonald's - Downtown","latitude":45.5016889,"longitude":-73.567256,"address":"123 Main Street","city":"Montreal","province":"QC","country":"CA","postal_code":"H2X 1Y8","distance":150,"poi_type":{"id":1,"poi_type_code":"restaurant","name":"Restaurant","display_name":{"en":"Restaurant","fr":"Restaurant"},"color":"#FF5733"}}],"center":{"lat":45.5,"lng":-73.567},"total":1}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"examples":{"no_work_location":{"value":{"success":false,"message":"No work location set for current user"}},"invalid_poi_types":{"value":{"success":false,"message":"Invalid POI types: invalid_type1, invalid_type2"}},"range_requires_center":{"value":{"success":false,"message":"Range limit requires explicit center coordinates"}}}}}},"422":{"description":"Unprocessable Entity - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"errors":{"type":"object","description":"Errors. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"success":false,"errors":{"latitude":["The latitude must be between -90 and 90."],"range_limit":["The range limit must be at least 0."]}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/poi":{"post":{"tags":["POI"],"summary":"Submit a new POI","description":"Unified endpoint under /v1/poi. Submit a new POI (Point of Interest) with optional field values based on the POI type's form definition.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["poi_type_id","name","latitude","longitude"],"properties":{"poi_type_id":{"type":"integer","description":"**Required.**\n\nID of the POI type\n\n**Details:** Type `integer`."},"name":{"type":"string","maxLength":255,"description":"**Required.**\n\nName of the POI\n\n**Details:** Type `string` · maxLength `255`."},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"**Required.**\n\nLatitude coordinate\n\n**Details:** Type `number` · min `-90` · max `90`."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"**Required.**\n\nLongitude coordinate\n\n**Details:** Type `number` · min `-180` · max `180`."},"address":{"type":["string","null"],"maxLength":500,"description":"Full address\n\n**Details:** Type `string` · Nullable · maxLength `500`."},"address_1":{"type":["string","null"],"maxLength":255,"description":"Address line 1\n\n**Details:** Type `string` · Nullable · maxLength `255`."},"address_2":{"type":["string","null"],"maxLength":255,"description":"Address line 2\n\n**Details:** Type `string` · Nullable · maxLength `255`."},"city":{"type":["string","null"],"maxLength":100,"description":"City\n\n**Details:** Type `string` · Nullable · maxLength `100`."},"province":{"type":["string","null"],"maxLength":100,"description":"Province/State\n\n**Details:** Type `string` · Nullable · maxLength `100`."},"country":{"type":["string","null"],"maxLength":2,"description":"Country code (2 letters)\n\n**Details:** Type `string` · Nullable · maxLength `2`."},"postal_code":{"type":["string","null"],"maxLength":20,"description":"Postal/ZIP code\n\n**Details:** Type `string` · Nullable · maxLength `20`."},"field_values":{"type":["object","null"],"description":"Dynamic field values based on POI type form definition. Keys can be field codes or field names.\n\n**Details:** Type `object` · Nullable.","additionalProperties":true}}},"example":{"poi_type_id":1,"name":"McDonald's - Downtown","latitude":45.5016889,"longitude":-73.567256,"address":"123 Main Street","address_1":"123 Main Street","address_2":"Suite 100","city":"Montreal","province":"QC","country":"CA","postal_code":"H2X 1Y8","field_values":{"opening_hours":"24/7","phone":"+1-514-555-0123","parking_available":true}}}}},"responses":{"200":{"description":"OK - POI created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"The ID of the newly created POI\n\n**Details:** Type `integer`."},"poi_type_id":{"type":"integer","description":"Poi type id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"latitude":{"type":"number","description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`."},"longitude":{"type":"number","description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`."},"address":{"type":["string","null"],"description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"created_at":{"type":"string","format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"success":true,"data":{"id":123,"poi_type_id":1,"name":"McDonald's - Downtown","latitude":45.5016889,"longitude":-73.567256,"address":"123 Main Street, Montreal, QC H2X 1Y8","created_at":"2024-01-15T10:30:00Z"},"message":"POI created successfully"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"success":false,"message":"Invalid POI type or no permission to use this POI type"}}}},"422":{"description":"Unprocessable Entity - Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","description":"Errors. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Errors. Element of a list or map in the request/response payload.\n\n**Details:** Type `array`, items `string`."},"description":"Errors. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"success":false,"errors":{"name":["The name field is required."],"latitude":["The latitude must be between -90 and 90."]}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/datasets":{"get":{"tags":["Dataset"],"summary":"List all datasets","description":"Get a paginated list of all datasets for the authenticated business","parameters":[{"name":"search","in":"query","description":"Search by name or description\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string`.","schema":{"type":"string","description":"Search by name or description\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string`."}},{"name":"per_page","in":"query","description":"Items per page (max 100)\n\nNumber of items returned per page.\n\n**Details:** Type `integer` · Default: `15`.","schema":{"type":"integer","default":15,"description":"Items per page (max 100)\n\nNumber of items returned per page.\n\n**Details:** Type `integer` · Default: `15`."}},{"name":"page","in":"query","description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`.","schema":{"type":"integer","default":1,"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"$ref":"#/components/schemas/Dataset","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `Dataset`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`."},"meta":{"$ref":"#/components/schemas/PaginationMeta","description":"Meta. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `PaginationMeta`."}}}}}},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Dataset"],"summary":"Create a new dataset","description":"Create a new dataset with column definitions","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetCreate"}}}},"responses":{"201":{"description":"Dataset created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"$ref":"#/components/schemas/Dataset","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `Dataset`."}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{id}":{"get":{"tags":["Dataset"],"summary":"Get a dataset","description":"Get a single dataset with its columns and groups","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"$ref":"#/components/schemas/Dataset","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `Dataset`."}}}}}},"404":{"description":"Dataset not found"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Dataset"],"summary":"Update a dataset","description":"Update dataset name, description, or status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["active","inactive"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `inactive`.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"Dataset updated"},"404":{"description":"Dataset not found"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Dataset"],"summary":"Delete a dataset","description":"Delete a dataset and all its groups and records","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Dataset deleted"},"404":{"description":"Dataset not found"}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{id}/webhooks":{"post":{"tags":["Dataset"],"summary":"Create a dataset webhook","description":"event_format (native | ce_binary | ce_structured) and standard_signature (boolean) are optional: ce_binary adds CloudEvents 1.0 ce-* headers, ce_structured sends the body as a CloudEvent (Content-Type application/cloudevents+json, native body in data), standard_signature adds webhook-id / webhook-timestamp / webhook-signature keyed with the secret and needs one. The native headers and signature are always sent; omitted or native keeps the webhook exactly as before. The url must be a public HTTPS address (checked on save and on every send).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url","events"],"properties":{"name":{"type":"string","maxLength":255,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `255`."},"url":{"type":"string","format":"uri","description":"**Required.**\n\nPublic HTTPS address.\n\n**Details:** Type `string`, format `uri`."},"secret":{"type":"string","maxLength":255,"writeOnly":true,"description":"Secret. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string` · Write-only · maxLength `255`."},"events":{"type":"array","items":{"type":"string","enum":["import_completed","geocode_completed","record_created","record_updated","record_deleted","validation_failed","duplicate_found"],"description":"Allowed values: `import_completed` · `geocode_completed` · `record_created` · `record_updated` · `record_deleted` · `validation_failed` · `duplicate_found`.\n\n**Details:** Type `string`."},"description":"**Required.**\n\nEvents. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"headers":{"type":"object","additionalProperties":{"type":"string","description":"Headers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Headers. Field in the JSON request body.\n\n**Details:** Type `object`."},"retry_count":{"type":"integer","minimum":0,"maximum":10,"description":"Retry count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · min `0` · max `10`."},"timeout":{"type":"integer","minimum":5,"maximum":120,"description":"Timeout. Field in the JSON request body.\n\n**Details:** Type `integer` · min `5` · max `120`."},"event_format":{"type":"string","enum":["native","ce_binary","ce_structured"],"default":"native","description":"Allowed values: `native` · `ce_binary` · `ce_structured`.\n\n**Details:** Type `string` · Default: `native`."},"standard_signature":{"type":"boolean","default":false,"description":"Standard signature. Field in the JSON request body.\n\n**Details:** Type `boolean` · Default: `false`."}}},"example":{"name":"Stores feed","url":"https://hooks.example.com/datasets","secret":"replace-with-a-secret","events":["record_created"],"event_format":"ce_binary","standard_signature":true}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"example":{"success":true,"message":"Webhook created","data":{"id":12,"dataset_id":5,"name":"Stores feed","url":"https://hooks.example.com/datasets","events":["record_created"],"event_format":"ce_binary","standard_signature":true}}}}},"400":{"description":"Validation failed (including an unsafe url, or standard_signature without a secret)","content":{"application/json":{"example":{"success":false,"errors":{"url":["The webhook URL must be a public HTTPS endpoint."]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Dataset not found"}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{datasetId}/webhooks/{webhookId}":{"put":{"tags":["Dataset"],"summary":"Update a dataset webhook","description":"Updates only the fields sent. event_format (native | ce_binary | ce_structured) and standard_signature (boolean) are optional: ce_binary adds CloudEvents 1.0 ce-* headers, ce_structured sends the body as a CloudEvent (Content-Type application/cloudevents+json, native body in data), standard_signature adds webhook-id / webhook-timestamp / webhook-signature keyed with the secret and needs one. The native headers and signature are always sent; omitted or native keeps the webhook exactly as before. The url must be a public HTTPS address (checked on save and on every send).","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"webhookId","in":"path","required":true,"schema":{"type":"integer","description":"Webhook id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Webhook id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"description":"Human-readable name.\n\n**Details:** Type `string` · maxLength `255`."},"url":{"type":"string","format":"uri","description":"Public HTTPS address.\n\n**Details:** Type `string`, format `uri`."},"secret":{"type":"string","maxLength":255,"writeOnly":true,"description":"Secret. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string` · Write-only · maxLength `255`."},"events":{"type":"array","items":{"type":"string","enum":["import_completed","geocode_completed","record_created","record_updated","record_deleted","validation_failed","duplicate_found"],"description":"Allowed values: `import_completed` · `geocode_completed` · `record_created` · `record_updated` · `record_deleted` · `validation_failed` · `duplicate_found`.\n\n**Details:** Type `string`."},"description":"Events. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"headers":{"type":"object","additionalProperties":{"type":"string","description":"Headers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Headers. Field in the JSON request body.\n\n**Details:** Type `object`."},"retry_count":{"type":"integer","minimum":0,"maximum":10,"description":"Retry count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · min `0` · max `10`."},"timeout":{"type":"integer","minimum":5,"maximum":120,"description":"Timeout. Field in the JSON request body.\n\n**Details:** Type `integer` · min `5` · max `120`."},"event_format":{"type":"string","enum":["native","ce_binary","ce_structured"],"default":"native","description":"Allowed values: `native` · `ce_binary` · `ce_structured`.\n\n**Details:** Type `string` · Default: `native`."},"standard_signature":{"type":"boolean","default":false,"description":"Standard signature. Field in the JSON request body.\n\n**Details:** Type `boolean` · Default: `false`."},"is_active":{"type":"boolean","description":"Is active. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."}}},"example":{"event_format":"ce_structured"}}}},"responses":{"200":{"description":"Webhook updated","content":{"application/json":{"example":{"success":true,"message":"Webhook updated","data":{"id":12,"dataset_id":5,"event_format":"ce_structured","standard_signature":true}}}}},"400":{"description":"Validation failed (including an unsafe url, or standard_signature without a secret)","content":{"application/json":{"example":{"success":false,"errors":{"url":["The webhook URL must be a public HTTPS endpoint."]}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Dataset or webhook not found"}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{id}/search":{"post":{"tags":["Dataset"],"summary":"Search records","description":"Search records across all groups in a dataset with advanced filtering","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["search"],"properties":{"search":{"type":"array","items":{"$ref":"#/components/schemas/SearchCriteria","description":"Search. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `SearchCriteria`."},"description":"**Required.**\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `array`."},"group_ids":{"type":"array","items":{"type":"integer","description":"Group ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Filter by specific group IDs\n\n**Details:** Type `array`, items `integer`."},"per_page":{"type":"integer","default":50,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `50`."}}}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"$ref":"#/components/schemas/DatasetRecord","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `DatasetRecord`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`."},"meta":{"$ref":"#/components/schemas/PaginationMeta","description":"Meta. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `PaginationMeta`."}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{datasetId}/groups":{"get":{"tags":["Dataset"],"summary":"List groups","description":"Get all groups for a dataset","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"$ref":"#/components/schemas/DatasetGroup","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `DatasetGroup`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Dataset"],"summary":"Create a group","description":"Create a new group with optional records","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`."},"records":{"type":"array","items":{"type":"object","description":"Records. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Array of record data objects\n\n**Details:** Type `array`, items `object`."}}}}}},"responses":{"201":{"description":"Group created"}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{datasetId}/groups/{groupId}":{"get":{"tags":["Dataset"],"summary":"Get a group","description":"Get group details with geocoding statistics","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"$ref":"#/components/schemas/DatasetGroup","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `DatasetGroup`."}}}}}}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Dataset"],"summary":"Update a group","description":"Update group name","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"Group updated"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Dataset"],"summary":"Delete a group","description":"Delete a group and all its records","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Group deleted"}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{datasetId}/groups/{groupId}/regeocode":{"post":{"tags":["Dataset"],"summary":"Re-geocode group","description":"Trigger re-geocoding for records in a group","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["failed","pending","all"],"default":"failed","description":"Which records to re-geocode\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `failed` · `pending` · `all`.\n\n**Details:** Type `string` · Default: `failed`."}}}}}},"responses":{"200":{"description":"Re-geocoding triggered"}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{datasetId}/groups/{groupId}/records":{"get":{"tags":["Dataset"],"summary":"List records","description":"Get paginated records for a group with optional filtering","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},{"name":"per_page","in":"query","schema":{"type":"integer","default":50,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `50`."},"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `50`."},{"name":"page","in":"query","schema":{"type":"integer","default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."},{"name":"geocode_status","in":"query","schema":{"type":"string","enum":["pending","success","failed","skipped"],"description":"Allowed values: `pending` · `success` · `failed` · `skipped`.\n\n**Details:** Type `string`."},"description":"Allowed values: `pending` · `success` · `failed` · `skipped`.\n\n**Details:** Type `string`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"$ref":"#/components/schemas/DatasetRecord","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `DatasetRecord`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`."},"meta":{"$ref":"#/components/schemas/PaginationMeta","description":"Meta. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `PaginationMeta`."}}}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Dataset"],"summary":"Create a record","description":"Create a single record and geocode if address columns are configured","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","description":"**Required.**\n\nRecord data with column codes as keys\n\n**Details:** Type `object`.","examples":[{"name":"John Doe","address":"123 Main St","city":"Toronto"}]}}}}}},"responses":{"201":{"description":"Record created"}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{datasetId}/groups/{groupId}/records/{recordId}":{"get":{"tags":["Dataset"],"summary":"Get a record","description":"Get a single record by ID","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},{"name":"recordId","in":"path","required":true,"schema":{"type":"integer","description":"Record id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Record id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"$ref":"#/components/schemas/DatasetRecord","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `DatasetRecord`."}}}}}}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Dataset"],"summary":"Update a record","description":"Update record data. Re-geocodes if address changed.","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},{"name":"recordId","in":"path","required":true,"schema":{"type":"integer","description":"Record id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Record id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","description":"**Required.**\n\nData. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"Record updated"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Dataset"],"summary":"Delete a record","description":"Delete a single record","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},{"name":"recordId","in":"path","required":true,"schema":{"type":"integer","description":"Record id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Record id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Record deleted"}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{datasetId}/groups/{groupId}/records/bulk":{"post":{"tags":["Dataset"],"summary":"Bulk create records","description":"Create multiple records at once (max 1000)","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"type":"object","description":"Records. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"maxItems":1000,"description":"**Required.**\n\nArray of record data objects\n\n**Details:** Type `array`, items `object` · maxItems `1000`."}}}}}},"responses":{"201":{"description":"Records created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"created_count":{"type":"integer","description":"Created count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}}}}}}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Dataset"],"summary":"Bulk delete records","description":"Delete multiple records by IDs","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["record_ids"],"properties":{"record_ids":{"type":"array","items":{"type":"integer","description":"Record ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nRecord ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."}}}}}},"responses":{"200":{"description":"Records deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"deleted_count":{"type":"integer","description":"Deleted count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/datasets/{datasetId}/groups/{groupId}/records/{recordId}/regeocode":{"post":{"tags":["Dataset"],"summary":"Re-geocode a record","description":"Re-geocode a single record","parameters":[{"name":"datasetId","in":"path","required":true,"schema":{"type":"integer","description":"Dataset id.\n\n**Details:** Required · Type `integer`."},"description":"Dataset id.\n\n**Details:** Required · Type `integer`."},{"name":"groupId","in":"path","required":true,"schema":{"type":"integer","description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},"description":"Group id for a dataset or packaging group.\n\n**Details:** Required · Type `integer`."},{"name":"recordId","in":"path","required":true,"schema":{"type":"integer","description":"Record id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Record id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Record re-geocoded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"$ref":"#/components/schemas/DatasetRecord","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `DatasetRecord`."}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/alliance":{"get":{"tags":["Alliance"],"summary":"Get my alliances","description":"Returns a list of alliances that the authenticated client has joined or created.","responses":{"200":{"description":"List of alliances","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AllianceMembership","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AllianceMembership`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Alliance"],"summary":"Create a new alliance","description":"Creates a new delivery alliance. The authenticated user becomes the owner.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllianceCreate"}}}},"responses":{"201":{"description":"Alliance created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Alliance created successfully`.","examples":["Alliance created successfully"]},"alliance":{"$ref":"#/components/schemas/Alliance","description":"Alliance. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `Alliance`."}}}}}},"400":{"description":"Bad Request"},"422":{"description":"Validation Error"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/join":{"post":{"tags":["Alliance"],"summary":"Request to join an alliance","description":"Request to join an alliance by providing the 8-character alliance code. For open alliances, the user is immediately added. For approval-required alliances, a pending request is created.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["alliance_code"],"properties":{"alliance_code":{"type":"string","minLength":8,"maxLength":8,"description":"**Required.**\n\n8-character alliance code\n\n**Details:** Type `string` · minLength `8` · maxLength `8`.\n\n**Example:** `AB12CD34`.","examples":["AB12CD34"]}}}}}},"responses":{"200":{"description":"Join request processed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successfully joined the alliance`.","examples":["Successfully joined the alliance"]},"status":{"type":"string","enum":["active","pending"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `pending`.\n\n**Details:** Type `string`.","examples":["active"]},"member":{"$ref":"#/components/schemas/AllianceMember","description":"Member. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `AllianceMember`."}}}}}},"400":{"description":"Bad Request - Already a member or invalid code"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/accessible-clients":{"get":{"tags":["Alliance"],"summary":"Get accessible client IDs for tracking","description":"Returns a list of client IDs whose data can be accessed through alliance permissions. Useful for tracking queries.","parameters":[{"name":"permission_type","in":"query","required":false,"schema":{"type":"string","default":"tracking_view","description":"Permission type to check (default: tracking_view)\n\n**Details:** Optional · Type `string` · Default: `tracking_view`."},"description":"Permission type to check (default: tracking_view)\n\n**Details:** Optional · Type `string` · Default: `tracking_view`."}],"responses":{"200":{"description":"List of accessible clients","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `ABC Logistics`.","examples":["ABC Logistics"]},"business_name":{"type":"string","description":"Business name. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `ABC Logistics Ltd`.","examples":["ABC Logistics Ltd"]},"is_self":{"type":"boolean","description":"Is self. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`.","examples":[false]}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/{id}":{"get":{"tags":["Alliance"],"summary":"Get alliance details","description":"Returns detailed information about an alliance including members and permissions.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Alliance details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"alliance":{"$ref":"#/components/schemas/Alliance","description":"Alliance. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `Alliance`."},"my_membership":{"$ref":"#/components/schemas/AllianceMember","description":"My membership. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `AllianceMember`."},"members":{"type":"array","items":{"$ref":"#/components/schemas/AllianceMember","description":"Members. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AllianceMember`."},"description":"Members. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}},"403":{"description":"Forbidden - Not a member of this alliance"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Alliance"],"summary":"Update alliance info","description":"Updates alliance information. Only owner or admin can perform this action.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllianceUpdate"}}}},"responses":{"200":{"description":"Alliance updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Alliance updated successfully`.","examples":["Alliance updated successfully"]},"alliance":{"$ref":"#/components/schemas/Alliance","description":"Alliance. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `Alliance`."}}}}}},"403":{"description":"Forbidden - No permission to update"}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Alliance"],"summary":"Dissolve alliance","description":"Dissolves the alliance. Only the owner can perform this action. All members will be removed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Alliance dissolved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Alliance dissolved successfully`.","examples":["Alliance dissolved successfully"]}}}}}},"400":{"description":"Bad Request - Not the owner"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/{id}/leave":{"post":{"tags":["Alliance"],"summary":"Leave an alliance","description":"Leave the specified alliance. Owners cannot leave - they must transfer ownership or dissolve.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Successfully left the alliance","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successfully left the alliance`.","examples":["Successfully left the alliance"]}}}}}},"400":{"description":"Bad Request - Owner cannot leave"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/{id}/members":{"get":{"tags":["Alliance"],"summary":"Get alliance members","description":"Returns a list of all members in the alliance.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"List of members","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"members":{"type":"array","items":{"$ref":"#/components/schemas/AllianceMember","description":"Members. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AllianceMember`."},"description":"Members. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}},"403":{"description":"Forbidden - Not a member"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/{id}/invite":{"post":{"tags":["Alliance"],"summary":"Invite a member to alliance","description":"Invites a client to join the alliance. Only owner or admin can invite. The invitee must be a client admin.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_id"],"properties":{"client_id":{"type":"integer","description":"**Required.**\n\nClient ID to invite\n\n**Details:** Type `integer`.\n\n**Example:** `456`.","examples":[456]}}}}}},"responses":{"200":{"description":"Invitation sent","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Invitation sent successfully`.","examples":["Invitation sent successfully"]},"member":{"$ref":"#/components/schemas/AllianceMember","description":"Member. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `AllianceMember`."}}}}}},"400":{"description":"Bad Request - Already a member or invalid client"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/{id}/pending-requests":{"get":{"tags":["Alliance"],"summary":"Get pending join requests","description":"Returns a list of pending join requests for the alliance. Only owner or admin can view.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"List of pending requests","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"requests":{"type":"array","items":{"$ref":"#/components/schemas/AllianceMember","description":"Requests. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AllianceMember`."},"description":"Requests. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}},"403":{"description":"Forbidden - No permission"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/members/{memberId}/approve":{"post":{"tags":["Alliance"],"summary":"Approve a join request","description":"Approves a pending join request. Only owner or admin can approve.","parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"integer","description":"Alliance member ID\n\n**Details:** Required · Type `integer`."},"description":"Alliance member ID\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Member approved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Member approved successfully`.","examples":["Member approved successfully"]},"member":{"$ref":"#/components/schemas/AllianceMember","description":"Member. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `AllianceMember`."}}}}}},"400":{"description":"Bad Request - Invalid request or no permission"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/members/{memberId}/reject":{"post":{"tags":["Alliance"],"summary":"Reject a join request","description":"Rejects a pending join request. Only owner or admin can reject.","parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"integer","description":"Alliance member ID\n\n**Details:** Required · Type `integer`."},"description":"Alliance member ID\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Request rejected`.","examples":["Request rejected"]}}}}}},"400":{"description":"Bad Request - Invalid request or no permission"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/members/{memberId}/remove":{"post":{"tags":["Alliance"],"summary":"Remove a member from alliance","description":"Removes a member from the alliance. Only owner or admin can remove. Cannot remove the owner.","parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"integer","description":"Alliance member ID\n\n**Details:** Required · Type `integer`."},"description":"Alliance member ID\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Member removed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Member removed successfully`.","examples":["Member removed successfully"]}}}}}},"400":{"description":"Bad Request - Cannot remove owner or no permission"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/{id}/permissions":{"get":{"tags":["Alliance"],"summary":"Get alliance permissions","description":"Returns both alliance-level permissions and the current user's member permissions.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Permissions retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"alliance_permissions":{"type":"array","items":{"$ref":"#/components/schemas/AlliancePermission","description":"Alliance permissions. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AlliancePermission`."},"description":"Alliance permissions. Field in the JSON request body.\n\n**Details:** Type `array`."},"my_permissions":{"type":"array","items":{"$ref":"#/components/schemas/AllianceMemberPermission","description":"My permissions. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AllianceMemberPermission`."},"description":"My permissions. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}},"403":{"description":"Forbidden - Not a member"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Alliance"],"summary":"Update alliance-level permissions","description":"Updates the alliance-level permission settings. Only owner or admin can update.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["permissions"],"properties":{"permissions":{"type":"array","items":{"type":"object","required":["permission_type","is_enabled"],"properties":{"permission_type":{"type":"string","description":"**Required.**\n\nPermission type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`.\n\n**Example:** `tracking_view`.","examples":["tracking_view"]},"is_enabled":{"type":"boolean","description":"**Required.**\n\nIs enabled. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`.","examples":[true]},"constraints":{"type":["object","null"],"description":"Constraints. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."}}},"description":"**Required.**\n\nPermissions. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"responses":{"200":{"description":"Permissions updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Alliance permissions updated successfully`.","examples":["Alliance permissions updated successfully"]},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/AlliancePermission","description":"Permissions. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AlliancePermission`."},"description":"Permissions. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}},"400":{"description":"Bad Request - No permission or invalid data"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/my-permissions/{allianceId}":{"put":{"tags":["Alliance"],"summary":"Update my permissions in an alliance","description":"Updates the current user's permission settings (share/receive) in the specified alliance.","parameters":[{"name":"allianceId","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["permissions"],"properties":{"permissions":{"type":"array","items":{"type":"object","required":["permission_type","grant_type","is_enabled"],"properties":{"permission_type":{"type":"string","description":"**Required.**\n\nPermission type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`.\n\n**Example:** `tracking_view`.","examples":["tracking_view"]},"grant_type":{"type":"string","enum":["share","receive"],"description":"**Required.**\n\nAllowed values: `share` · `receive`.\n\n**Details:** Type `string`.","examples":["share"]},"is_enabled":{"type":"boolean","description":"**Required.**\n\nIs enabled. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`.","examples":[true]}}},"description":"**Required.**\n\nPermissions. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"responses":{"200":{"description":"Permissions updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Permissions updated successfully`.","examples":["Permissions updated successfully"]},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/AllianceMemberPermission","description":"Permissions. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AllianceMemberPermission`."},"description":"Permissions. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}},"400":{"description":"Bad Request - Not a member or invalid data"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/{id}/transfer-ownership":{"post":{"tags":["Alliance"],"summary":"Transfer ownership","description":"Transfers alliance ownership to another active member. Only the current owner can perform this action. The previous owner becomes an admin.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["new_owner_client_id"],"properties":{"new_owner_client_id":{"type":"integer","description":"**Required.**\n\nClient ID of the new owner\n\n**Details:** Type `integer`.\n\n**Example:** `789`.","examples":[789]}}}}}},"responses":{"200":{"description":"Ownership transferred","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Ownership transferred successfully`.","examples":["Ownership transferred successfully"]}}}}}},"400":{"description":"Bad Request - Not the owner or new owner not a member"}},"security":[{"bearerAuth":[]}]}},"/v1/alliance/{id}/access-logs":{"get":{"tags":["Alliance"],"summary":"Get access logs","description":"Returns access logs for the alliance. Admin/owner can see all logs, regular members can only see logs related to their own data.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Alliance ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Filter by start date\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Filter by start date\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Filter by end date\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Filter by end date\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"resource_type","in":"query","required":false,"schema":{"type":"string","description":"Filter by resource type\n\n**Details:** Optional · Type `string`."},"description":"Filter by resource type\n\n**Details:** Optional · Type `string`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":50,"description":"Items per page\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `50`."},"description":"Items per page\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `50`."}],"responses":{"200":{"description":"Access logs retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"logs":{"type":"object","description":"Paginated access logs\n\n**Details:** Type `object`."}}}}}},"403":{"description":"Forbidden - Not a member"}},"security":[{"bearerAuth":[]}]}},"/tracking/{trackingNumber}":{"get":{"tags":["Public"],"summary":"Get public tracking information by tracking number","description":"Public endpoint to retrieve tracking information. No authentication required. Returns tracking events and delivery status. Does not include sender/recipient addresses.","operationId":"publicTracking","parameters":[{"in":"path","name":"trackingNumber","schema":{"type":"string","description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`."},"required":true,"description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`.","example":"SR123456789"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Indicates if the request was successful\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Response message\n\n**Details:** Type `string`."},"is_third_party_tracking":{"type":"boolean","description":"Indicates if tracking is from a third-party carrier\n\n**Details:** Type `boolean`."},"postcode":{"type":"string","description":"Delivery postcode (uppercase, no spaces)\n\n**Details:** Type `string`."},"deliveried":{"type":"boolean","description":"Indicates if the parcel has been delivered\n\n**Details:** Type `boolean`."},"returntosender":{"type":"boolean","description":"Indicates if the parcel is being returned to sender\n\n**Details:** Type `boolean`."},"rejectedbyrecipient":{"type":"boolean","description":"Indicates if the parcel was rejected by recipient\n\n**Details:** Type `boolean`."},"data":{"type":"array","description":"List of tracking events\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"tracking_event_status_id":{"type":"integer","description":"Tracking event status identifier\n\n**Details:** Type `integer`."},"updated_at":{"type":"string","format":"date-time","description":"Event timestamp in UTC\n\n**Details:** Type `string`, format `date-time`."},"description":{"type":"string","description":"Human-readable event description\n\n**Details:** Type `string`."},"location_name":{"type":["string","null"],"description":"Location name where the event occurred\n\n**Details:** Type `string` · Nullable."},"location_city":{"type":["string","null"],"description":"City of the event location\n\n**Details:** Type `string` · Nullable."},"location_province":{"type":["string","null"],"description":"Province/state of the event location\n\n**Details:** Type `string` · Nullable."},"location_country":{"type":["string","null"],"description":"Country of the event location\n\n**Details:** Type `string` · Nullable."},"location_postcode":{"type":["string","null"],"description":"Postal/ZIP code of the event location\n\n**Details:** Type `string` · Nullable."},"operation_location":{"type":["string","null"],"description":"Combined location string (for backward compatibility)\n\n**Details:** Type `string` · Nullable."},"reason":{"type":["string","null"],"description":"Return reason recorded on a failed delivery/pickup stop. The public surface only includes reasons the business marked as visible to the public; a non-public reason is returned as null (the authenticated client tracking endpoint returns every reason).\n\n**Details:** Type `string` · Nullable."},"time_zone":{"type":"string","description":"IANA timezone of the event location\n\n**Details:** Type `string`."},"gmt_offset":{"type":"string","description":"GMT offset at the time of event (accounts for DST)\n\n**Details:** Type `string`."},"order_id":{"type":"integer","description":"Associated order ID\n\n**Details:** Type `integer`."},"display_distance_unit":{"type":"integer","description":"Distance unit for display (1: km, 2: miles)\n\n**Details:** Type `integer`."},"orders_status_id":{"type":"integer","description":"Current order status ID\n\nOrder lifecycle status id (`orders.orders_status_id`). Source: `OrdersStatusInput`.\n\nEnum values (from deployed code):\n- `1` — Need Update Address (`need_update_address`)\n- `2` — New Order (`new_order`)\n- `3` — Waiting To Plan (`waiting_to_plan`)\n- `4` — Planning (`planning`)\n- `5` — Already Planned (`already_planned`)\n- `6` — Plan Failed (`plan_failed`)\n- `14` — Already Pickup (`already_pickup`)\n- `8` — Successful (`successful`)\n- `9` — Redelivered Later (`redelivered_later`)\n- `10` — Need Rescheduled (`need_rescheduled`)\n- `11` — Rescheduled (`rescheduled`)\n- `12` — Cancelled (`cancelled`)\n- `16` — Need To Pick Up (`need_to_pick_up`)\n- `7` — Already Pickup (`already_pickup`)\n- `20` — Out For Delivery (`out_for_delivery`)\n- `21` — Out For Pickup (`out_for_pickup`)\n- `17` — Waiting For Self Pickup (`waiting_for_self_pickup`)\n- `19` — Return To Customer (`return_to_customer`)\n- `25` — Hand Off (`hand_off`)\n- `18` — Self Pickup Completed (`self_pickup_completed`)\n- `22` — Partial Received (`partial_received`)\n- `23` — Partial Delivered (`partial_delivered`)\n- `24` — Partial Pickuped (`partial_pickuped`)\n- `26` — Review (`review`)\n- `27` — Destroyed (`destroyed`)\n- `29` — In Transit (`in_transit`)\n- `30` — Package Lost (`package_lost`)\n- `31` — Package Damaged (`package_damaged`)\n- `32` — Waiting Customer Options (`waiting_customer_options`)\n- `33` — Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)\n- `34` — Waiting Batch Pickup (`waiting_batch_pickup`)\n- `28` — Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)\n- `35` — Payment Required (`payment_required`)\n- `36` — Bulk Transshipment Pending (`bulk_transshipment_pending`)\n- `37` — Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)\n- `38` — Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)\n- `39` — Inbound Scan Required (`inbound_scan_required`)\n- `40` — Rejected By Recipient (`rejected_by_recipient`)\n- `41` — Package Outbound (`package_outbound`)\n- `42` — Waiting For Quote (`waiting_for_quote`)\n- `43` — Waiting Third Party Handover (`waiting_third_party_handover`)\n- `44` — Waiting For Assignment (`waiting_for_assignment`)\n- `45` — Start Pickup (`start_pickup`)\n- `46` — Start Delivery (`start_delivery`)\n- `47` — Out Of Delivery Area (`out_of_delivery_area`)\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5,6,14,8,9,10,11,12,16,7,20,21,17,19,25,18,22,23,24,26,27,29,30,31,32,33,34,28,35,36,37,38,39,40,41,42,43,44,45,46,47],"x-enumDescriptions":["Need Update Address (`need_update_address`)","New Order (`new_order`)","Waiting To Plan (`waiting_to_plan`)","Planning (`planning`)","Already Planned (`already_planned`)","Plan Failed (`plan_failed`)","Already Pickup (`already_pickup`)","Successful (`successful`)","Redelivered Later (`redelivered_later`)","Need Rescheduled (`need_rescheduled`)","Rescheduled (`rescheduled`)","Cancelled (`cancelled`)","Need To Pick Up (`need_to_pick_up`)","Already Pickup (`already_pickup`)","Out For Delivery (`out_for_delivery`)","Out For Pickup (`out_for_pickup`)","Waiting For Self Pickup (`waiting_for_self_pickup`)","Return To Customer (`return_to_customer`)","Hand Off (`hand_off`)","Self Pickup Completed (`self_pickup_completed`)","Partial Received (`partial_received`)","Partial Delivered (`partial_delivered`)","Partial Pickuped (`partial_pickuped`)","Review (`review`)","Destroyed (`destroyed`)","In Transit (`in_transit`)","Package Lost (`package_lost`)","Package Damaged (`package_damaged`)","Waiting Customer Options (`waiting_customer_options`)","Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)","Waiting Batch Pickup (`waiting_batch_pickup`)","Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)","Payment Required (`payment_required`)","Bulk Transshipment Pending (`bulk_transshipment_pending`)","Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)","Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)","Inbound Scan Required (`inbound_scan_required`)","Rejected By Recipient (`rejected_by_recipient`)","Package Outbound (`package_outbound`)","Waiting For Quote (`waiting_for_quote`)","Waiting Third Party Handover (`waiting_third_party_handover`)","Waiting For Assignment (`waiting_for_assignment`)","Start Pickup (`start_pickup`)","Start Delivery (`start_delivery`)","Out Of Delivery Area (`out_of_delivery_area`)"]},"timestamp":{"type":"integer","description":"Unix timestamp of the event\n\n**Details:** Type `integer`."},"updated_at_localized":{"type":"string","description":"Event timestamp in local timezone\n\n**Details:** Type `string`."}}}},"proofs":{"type":"array","description":"Delivery proof images/signatures\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"url":{"type":"string","description":"URL to the proof file\n\n**Details:** Type `string`."},"type":{"type":"string","description":"Type of proof file\n\n**Details:** Type `string`."},"full_url":{"type":"string","description":"Absolute public URL of the proof file\n\n**Details:** Type `string`."},"file_id":{"type":"integer","description":"Stable file identifier, usable for consumer-side dedup/incremental sync\n\n**Details:** Type `integer`."},"uploaded_at":{"type":["string","null"],"description":"Upload time (Y-m-d H:i:s)\n\n**Details:** Type `string` · Nullable."},"uploaded_timestamp":{"type":["integer","null"],"description":"Unix timestamp of the upload time\n\n**Details:** Type `integer` · Nullable."},"signed_url":{"type":"string","description":"Expiring signed download URL — re-query tracking for a fresh one after signed_url_expires_at\n\n**Details:** Type `string`."},"signed_url_expires_at":{"type":"integer","description":"Unix timestamp when signed_url expires\n\n**Details:** Type `integer`."},"tracking_event_id":{"type":["integer","null"],"description":"Tracking event the proof was captured for. A file uploaded on its own, with no event recorded, is read off the order's timeline: the outcome it was uploaded right before (what the driver went on to report) or right after (what the driver had already reported). null only when the order has no such outcome.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_status_id":{"type":["integer","null"],"description":"Status code of that event (500 delivered, 504 partially delivered, 510 picked up, 501/502/503 failed delivery, 512/513 failed pickup, …). null without an event.\n\n**Details:** Type `integer` · Nullable."},"tracking_event_key":{"type":["string","null"],"description":"Stable key of that event status (deliver_success, pickuped, not_delivered, …). null without an event.\n\n**Details:** Type `string` · Nullable."},"service_type":{"type":["integer","null"],"enum":[1,2,null],"description":"Code of the service the proof belongs to, derived from the event's leg type: 1 = delivery, 2 = pickup. null without an event.\n\nAllowed values: `1` · `2` · `null`.\n\n**Details:** Type `integer` · Nullable."},"service_status":{"type":["integer","null"],"enum":[1,2,null],"description":"Code of the outcome the proof documents, derived from the event status: 1 = success (500, 504, 510), 2 = failed (501, 502, 503, 512, 513). null without an event or for other statuses.\n\nAllowed values: `1` · `2` · `null`.\n\n**Details:** Type `integer` · Nullable."}}}},"third_party_info":{"type":"object","description":"Third-party carrier information (only present when is_third_party_tracking is true)\n\n**Details:** Type `object`.","properties":{"tracking_number":{"type":"string","description":"Third-party tracking number\n\n**Details:** Type `string`."},"status":{"type":"string","description":"Status from third-party carrier\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"shipping_service":{"type":"string","description":"Shipping service name\n\n**Details:** Type `string`."},"carrier_tracking_link":{"type":"string","description":"URL to carrier's tracking page\n\n**Details:** Type `string`."}}}}}}}},"404":{"description":"Tracking number not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Tracking number not found`.","examples":["Tracking number not found"]}}}}}}}}},"/v1/17track/{trackingNumber}":{"get":{"tags":["Public"],"summary":"Get tracking information in 17Track format","description":"Public endpoint to retrieve tracking information formatted for 17Track integration. No authentication required. The `carrier` field is the client's configured 17Track carrier name, falling back to the client's account name when it is not set. GET /custom-api/api/v3/17track/getTrack?waybillNo={trackingNumber} is an alias of this endpoint and returns an identical payload.","operationId":"tracking17Track","parameters":[{"in":"path","name":"trackingNumber","schema":{"type":"string","description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`."},"required":true,"description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`.","example":"SR123456789"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","description":"Tracking information in 17Track compatible format","properties":{"carrier":{"type":"string","description":"Client's 17Track carrier name; falls back to the client's account name when not configured\n\n**Details:** Type `string`.\n\n**Example:** `Fleet Express`.","examples":["Fleet Express"]},"number":{"type":"string","description":"Number. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `SR123456789`.","examples":["SR123456789"]},"oriNumber":{"type":"string","description":"Ori number. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `1Z999AA10123456784`.","examples":["1Z999AA10123456784"]},"oriChannel":{"type":"string","description":"Ori channel. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `SR`.","examples":["SR"]},"oriCountry":{"type":"string","description":"Ori country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"destCountry":{"type":"string","description":"Dest country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`.\n\n**Example:** `30`.","examples":[30]},"events":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","description":"Time. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `2026-07-28T09:15:00-04:00`.","examples":["2026-07-28T09:15:00-04:00"]},"location":{"type":"string","description":"Location. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `Montreal Warehouse`.","examples":["Montreal Warehouse"]},"content":{"type":"string","description":"Content. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `Out For Delivery`.","examples":["Out For Delivery"]}}},"description":"Events. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"error":{"type":"string","description":"Only present when the tracking number is not found\n\n**Details:** Type `string`.\n\n**Example:** `Tracking number not found`.","examples":["Tracking number not found"]}}}}}}}}},"/v3/17track/getTrack":{"servers":[{"description":"Custom API (Production)","url":"/custom-api/api/"},{"description":"Custom API (Local)","url":"http://127.0.0.1/custom-api/api/"}],"get":{"tags":["Public"],"summary":"Get tracking information in 17Track format (custom-api alias)","description":"Full URL: GET /custom-api/api/v3/17track/getTrack?waybillNo={trackingNumber}. Alias of GET /api/v1/17track/{trackingNumber} — same handler, identical payload; only the way the tracking number is addressed differs (query string instead of path). Provided because a 17Track carrier integration can only be pointed at a single fixed URL. The `carrier` field is the client's configured 17Track carrier name, falling back to the client's account name when it is not set.","operationId":"tracking17TrackGetTrack","parameters":[{"in":"query","name":"waybillNo","schema":{"type":"string","description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`."},"required":true,"description":"The tracking number to look up\n\n**Details:** Required · Type `string`.\n\n**Example:** `SR123456789`.","example":"SR123456789"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","description":"Tracking information in 17Track compatible format","properties":{"carrier":{"type":"string","description":"Client's 17Track carrier name; falls back to the client's account name when not configured\n\n**Details:** Type `string`.\n\n**Example:** `Fleet Express`.","examples":["Fleet Express"]},"number":{"type":"string","description":"Number. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `SR123456789`.","examples":["SR123456789"]},"oriNumber":{"type":"string","description":"Ori number. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `1Z999AA10123456784`.","examples":["1Z999AA10123456784"]},"oriChannel":{"type":"string","description":"Ori channel. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `SR`.","examples":["SR"]},"oriCountry":{"type":"string","description":"Ori country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"destCountry":{"type":"string","description":"Dest country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`.\n\n**Example:** `30`.","examples":[30]},"events":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string","description":"Time. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `2026-07-28T09:15:00-04:00`.","examples":["2026-07-28T09:15:00-04:00"]},"location":{"type":"string","description":"Location. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `Montreal Warehouse`.","examples":["Montreal Warehouse"]},"content":{"type":"string","description":"Content. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `Out For Delivery`.","examples":["Out For Delivery"]}}},"description":"Events. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"error":{"type":"string","description":"Only present when the tracking number is not found\n\n**Details:** Type `string`.\n\n**Example:** `Tracking number not found`.","examples":["Tracking number not found"]}}}}}}}}},"/v1/products":{"get":{"summary":"List products","description":"List products for the authenticated business with filtering and pagination. Supports product class, SKU, name, and status filters.","operationId":"productList","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"product_class","in":"query","required":false,"schema":{"type":"string","description":"Filter by product class (simple, variable, grouped, bundled, virtual, downloadable)\n\n**Details:** Optional · Type `string`.","examples":["simple"]},"description":"Filter by product class (simple, variable, grouped, bundled, virtual, downloadable)\n\n**Details:** Optional · Type `string`."},{"name":"sku","in":"query","required":false,"schema":{"type":"string","description":"Filter by SKU (partial match)\n\nStock keeping unit / product code.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `SKU-001`.","examples":["SKU-001"]},"description":"Filter by SKU (partial match)\n\nStock keeping unit / product code.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `SKU-001`."},{"name":"name","in":"query","required":false,"schema":{"type":"string","description":"Filter by name (partial match)\n\nHuman-readable name.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `Widget`.","examples":["Widget"]},"description":"Filter by name (partial match)\n\nHuman-readable name.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `Widget`."},{"name":"status","in":"query","required":false,"schema":{"type":"integer","description":"Filter by status (1=active, 0=inactive)\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `integer`.","examples":[1]},"description":"Filter by status (1=active, 0=inactive)\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `integer`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","description":"Items per page (max 100)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `50`.","examples":[50]},"description":"Items per page (max 100)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `50`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`.","examples":[1]},"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Products list","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"array","items":{"type":"object","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Product object. Besides the existing columns it carries cost_price, sale_price, sale_starts_at, sale_ends_at, backorder_policy and the computed effective_price (sale_price while the sale window is active, otherwise price). Variants carry the same fields.\n\n**Details:** Type `array`, items `object`."},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`.\n\n**Example:** `100`.","examples":[100]},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`.\n\n**Example:** `50`.","examples":[50]},"current_page":{"type":"integer","description":"Current page. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"last_page":{"type":"integer","description":"Last page. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `2`.","examples":[2]}},"description":"Pagination. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}}}},"post":{"summary":"Create a product","description":"Create a new product. Supports all product classes: simple, variable, grouped, bundled, virtual, downloadable.","operationId":"productCreate","tags":["Products"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","sku"],"properties":{"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Widget Pro`.","examples":["Widget Pro"]},"sku":{"type":"string","description":"Required. Unique within the business across both products and variants. Alphanumeric and hyphens only; stored uppercase.\n\n**Details:** Type `string`.\n\n**Example:** `WDG-PRO-001`.","examples":["WDG-PRO-001"]},"product_class":{"type":"string","description":"simple, variable, grouped, bundled, virtual, downloadable\n\n**Details:** Type `string`.","examples":["simple"]},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `29.99`.","examples":[29.99]},"compare_at_price":{"type":"number","description":"Compare at price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `39.99`.","examples":[39.99]},"status":{"type":"boolean","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"manage_stock":{"type":"boolean","description":"Manage stock. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"stock_status":{"type":"string","enum":["auto","in_stock","out_of_stock"],"description":"Storefront availability: auto (follow real stock), in_stock (default), out_of_stock.\n\nAllowed values: `auto` · `in_stock` · `out_of_stock`.\n\n**Details:** Type `string`.","examples":["in_stock"]},"stock_display":{"type":"string","enum":["show","hide","below_threshold"],"description":"Whether/how the quantity is shown on the storefront.\n\nAllowed values: `show` · `hide` · `below_threshold`.\n\n**Details:** Type `string`.","examples":["show"]},"stock_display_threshold":{"type":["integer","null"],"description":"Show quantity only when below this number (for below_threshold).\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `5`.","examples":[5]},"stock_display_as":{"type":["integer","null"],"description":"Fixed quantity shown on the storefront instead of the real number.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `999`.","examples":[999]},"stock_quantity":{"type":"integer","description":"Stock quantity. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`.\n\n**Example:** `100`.","examples":[100]},"weight":{"type":"number","description":"Weight of the package or shipment.\n\n**Details:** Type `number`.\n\n**Example:** `0.5`.","examples":[0.5]},"is_virtual":{"type":"boolean","description":"Is virtual. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`.","examples":[false]},"is_downloadable":{"type":"boolean","description":"Is downloadable. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`.","examples":[false]},"cost_price":{"type":["number","null"],"description":"Cost / wholesale price for margin analytics. Never exposed to buyers.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `8`.","examples":[8]},"sale_price":{"type":["number","null"],"description":"Scheduled sale price; charged instead of price while the sale window is active.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `19.99`.","examples":[19.99]},"sale_starts_at":{"type":["string","null"],"format":"date-time","description":"Sale window start. Omit or null for an open-ended start.\n\n**Details:** Type `string`, format `date-time` · Nullable.\n\n**Example:** `2026-09-01 00:00:00`.","examples":["2026-09-01 00:00:00"]},"sale_ends_at":{"type":["string","null"],"format":"date-time","description":"Sale window end; must not precede sale_starts_at. Omit or null for an open-ended end.\n\n**Details:** Type `string`, format `date-time` · Nullable.\n\n**Example:** `2026-09-30 23:59:59`.","examples":["2026-09-30 23:59:59"]},"backorder_policy":{"type":"string","enum":["deny","allow","notify"],"description":"What happens when tracked stock runs out: deny (default, cannot be ordered), allow (orders accepted), notify (orders accepted, buyer told it is backordered).\n\nAllowed values: `deny` · `allow` · `notify`.\n\n**Details:** Type `string`.","examples":["deny"]}}}}}},"responses":{"201":{"description":"Product created","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"object","description":"Product object. Besides the existing columns it carries cost_price, sale_price, sale_starts_at, sale_ends_at, backorder_policy and the computed effective_price (sale_price while the sale window is active, otherwise price). Variants carry the same fields.\n\n**Details:** Type `object`."}}}}}}}}},"/v1/products/{id}":{"get":{"summary":"Get product detail","description":"Get a single product with full details including variants, options, platform links, images, and barcodes.","operationId":"productDetail","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Product ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`.","examples":[1]},"description":"Product ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`."}],"responses":{"200":{"description":"Product detail","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"object","description":"Product object. Besides the existing columns it carries cost_price, sale_price, sale_starts_at, sale_ends_at, backorder_policy and the computed effective_price (sale_price while the sale window is active, otherwise price). Variants carry the same fields.\n\n**Details:** Type `object`."}}}}}}}},"put":{"summary":"Update a product","description":"Update an existing product's properties.","operationId":"productUpdate","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Product ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`.","examples":[1]},"description":"Product ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Updated Widget`.","examples":["Updated Widget"]},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `34.99`.","examples":[34.99]},"product_class":{"type":"string","description":"Product class. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `variable`.","examples":["variable"]},"manage_stock":{"type":"boolean","description":"Manage stock. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"stock_status":{"type":"string","enum":["auto","in_stock","out_of_stock"],"description":"Storefront availability: auto (follow real stock), in_stock (default), out_of_stock.\n\nAllowed values: `auto` · `in_stock` · `out_of_stock`.\n\n**Details:** Type `string`.","examples":["in_stock"]},"stock_display":{"type":"string","enum":["show","hide","below_threshold"],"description":"Whether/how the quantity is shown on the storefront.\n\nAllowed values: `show` · `hide` · `below_threshold`.\n\n**Details:** Type `string`.","examples":["show"]},"stock_display_threshold":{"type":["integer","null"],"description":"Show quantity only when below this number (for below_threshold).\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `5`.","examples":[5]},"stock_display_as":{"type":["integer","null"],"description":"Fixed quantity shown on the storefront instead of the real number.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `999`.","examples":[999]},"stock_quantity":{"type":"integer","description":"Stock quantity. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`.\n\n**Example:** `50`.","examples":[50]},"cost_price":{"type":["number","null"],"description":"Cost / wholesale price for margin analytics. Never exposed to buyers.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `8`.","examples":[8]},"sale_price":{"type":["number","null"],"description":"Scheduled sale price; charged instead of price while the sale window is active.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `19.99`.","examples":[19.99]},"sale_starts_at":{"type":["string","null"],"format":"date-time","description":"Sale window start. Omit or null for an open-ended start.\n\n**Details:** Type `string`, format `date-time` · Nullable.\n\n**Example:** `2026-09-01 00:00:00`.","examples":["2026-09-01 00:00:00"]},"sale_ends_at":{"type":["string","null"],"format":"date-time","description":"Sale window end; must not precede sale_starts_at. Omit or null for an open-ended end.\n\n**Details:** Type `string`, format `date-time` · Nullable.\n\n**Example:** `2026-09-30 23:59:59`.","examples":["2026-09-30 23:59:59"]},"backorder_policy":{"type":"string","enum":["deny","allow","notify"],"description":"What happens when tracked stock runs out: deny (default, cannot be ordered), allow (orders accepted), notify (orders accepted, buyer told it is backordered).\n\nAllowed values: `deny` · `allow` · `notify`.\n\n**Details:** Type `string`.","examples":["deny"]}}}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"object","description":"Product object. Besides the existing columns it carries cost_price, sale_price, sale_starts_at, sale_ends_at, backorder_policy and the computed effective_price (sale_price while the sale window is active, otherwise price). Variants carry the same fields.\n\n**Details:** Type `object`."}}}}}}}},"delete":{"summary":"Delete a product","description":"Delete a product and its associated variants, options, and platform links.","operationId":"productDelete","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Product ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`.","examples":[1]},"description":"Product ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`."}],"responses":{"200":{"description":"Product deleted","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `Product deleted`.","examples":["Product deleted"]}}}}}}}}},"/v1/products/{productId}/variants":{"get":{"summary":"List product variants","description":"List all variants for a product.","operationId":"productVariantList","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"integer","description":"Product ID\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`.","examples":[1]},"description":"Product ID\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`."}],"responses":{"200":{"description":"Variants list","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"array","items":{"type":"object","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}}}},"post":{"summary":"Create a product variant","description":"Create a new variant for a product with option values, pricing, and stock.","operationId":"productVariantCreate","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"integer","description":"Product ID\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`.","examples":[1]},"description":"Product ID\n\n**Details:** Required · Type `integer`.\n\n**Example:** `1`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sku"],"properties":{"sku":{"type":"string","description":"Required. Unique within the business across both products and variants. Alphanumeric and hyphens only; stored uppercase.\n\n**Details:** Type `string`.\n\n**Example:** `WDG-PRO-L-RED`.","examples":["WDG-PRO-L-RED"]},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`.\n\n**Example:** `29.99`.","examples":[29.99]},"option_values":{"type":"object","description":"Option values. Field in the JSON request body.\n\n**Details:** Type `object`.","examples":[{"Size":"L","Color":"Red"}]},"manage_stock":{"type":"boolean","description":"Manage stock. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"stock_status":{"type":"string","enum":["auto","in_stock","out_of_stock"],"description":"Storefront availability: auto (follow real stock), in_stock (default), out_of_stock.\n\nAllowed values: `auto` · `in_stock` · `out_of_stock`.\n\n**Details:** Type `string`.","examples":["in_stock"]},"stock_display":{"type":"string","enum":["show","hide","below_threshold"],"description":"Whether/how the quantity is shown on the storefront.\n\nAllowed values: `show` · `hide` · `below_threshold`.\n\n**Details:** Type `string`.","examples":["show"]},"stock_display_threshold":{"type":["integer","null"],"description":"Show quantity only when below this number (for below_threshold).\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `5`.","examples":[5]},"stock_display_as":{"type":["integer","null"],"description":"Fixed quantity shown on the storefront instead of the real number.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `999`.","examples":[999]},"stock_quantity":{"type":"integer","description":"Stock quantity. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`.\n\n**Example:** `25`.","examples":[25]},"cost_price":{"type":["number","null"],"description":"Cost / wholesale price for margin analytics. Never exposed to buyers.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `8`.","examples":[8]},"sale_price":{"type":["number","null"],"description":"Scheduled sale price; charged instead of price while the sale window is active.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `19.99`.","examples":[19.99]},"sale_starts_at":{"type":["string","null"],"format":"date-time","description":"Sale window start. Omit or null for an open-ended start.\n\n**Details:** Type `string`, format `date-time` · Nullable.\n\n**Example:** `2026-09-01 00:00:00`.","examples":["2026-09-01 00:00:00"]},"sale_ends_at":{"type":["string","null"],"format":"date-time","description":"Sale window end; must not precede sale_starts_at. Omit or null for an open-ended end.\n\n**Details:** Type `string`, format `date-time` · Nullable.\n\n**Example:** `2026-09-30 23:59:59`.","examples":["2026-09-30 23:59:59"]},"backorder_policy":{"type":"string","enum":["deny","allow","notify"],"description":"What happens when tracked stock runs out: deny (default, cannot be ordered), allow (orders accepted), notify (orders accepted, buyer told it is backordered).\n\nAllowed values: `deny` · `allow` · `notify`.\n\n**Details:** Type `string`.","examples":["deny"]}}}}}},"responses":{"201":{"description":"Variant created","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"object","description":"Product object. Besides the existing columns it carries cost_price, sale_price, sale_starts_at, sale_ends_at, backorder_policy and the computed effective_price (sale_price while the sale window is active, otherwise price). Variants carry the same fields.\n\n**Details:** Type `object`."}}}}}}}}},"/v1/products/sync/platform":{"post":{"summary":"Sync products from external platform","description":"Trigger product catalog sync from WooCommerce, Shopify, or Magento. Imports products with variants, options, and creates platform links.","operationId":"productSyncPlatform","tags":["Products"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","platform_setting_id"],"properties":{"platform":{"type":"string","description":"**Required.**\n\nPlatform type: woocommerce, shopify, magento\n\nClient platform for bootstrap / capability negotiation.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Type `string`.","enum":["ios","android"],"x-enumDescriptions":["Apple iOS","Google Android"],"examples":["woocommerce"]},"platform_setting_id":{"type":"integer","description":"**Required.**\n\nPlatform connection/setting ID\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]}}}}}},"responses":{"200":{"description":"Sync results","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"msg":{"type":"string","description":"Msg. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `Synced 15 products`.","examples":["Synced 15 products"]},"data":{"type":"object","properties":{"synced":{"type":"integer","description":"Synced. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `15`.","examples":[15]},"errors":{"type":"integer","description":"Errors. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `0`.","examples":[0]},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`.\n\n**Example:** `15`.","examples":[15]}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}}}}},"/v1/customer/storage-orders/config":{"get":{"tags":["Customer"],"summary":"Get the configuration bundle needed to render the customer 'create storage order' form","description":"Returns everything the client needs to render the customer-side create storage order form: the customer's accessible warehouses, the business's packaging catalog, supplies products, pickup timeframes, unit definitions, surcharges, and dynamic form bindings. Requires an authenticated customer account.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Config bundle","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"object","properties":{"warehouses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."}}},"description":"Warehouses. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"packagings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`."},"length":{"type":"number","description":"Length dimension.\n\n**Details:** Type `number`."},"width":{"type":"number","description":"Width dimension.\n\n**Details:** Type `number`."},"height":{"type":"number","description":"Height dimension.\n\n**Details:** Type `number`."},"dimension_unit":{"type":"integer","description":"Dimension unit code from `Packages::DIMENSION_UNIT`: 1=mm, 2=cm, 3=m, 4=inch. Default 1.\n\n**Details:** Type `integer`."}}},"description":"Packagings. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"display_names":{"type":"object","description":"Display names. Human-readable label.\n\n**Details:** Type `object`."},"price":{"type":"number","description":"Price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`."},"image":{"type":["string","null"],"description":"Image. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}},"description":"Products. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"pickup_timeframes":{"type":"array","items":{"type":"object","description":"Pickup timeframes. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Pickup timeframes. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"dimension_units":{"type":"object","description":"Keyed by int ID → {name, accuracy}\n\n**Details:** Type `object`."},"weight_units":{"type":"object","description":"Keyed by int ID → {name, accuracy}\n\n**Details:** Type `object`."},"default_dimension_unit":{"type":["integer","null"],"description":"Default dimension unit. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer` · Nullable."},"default_weight_unit":{"type":["integer","null"],"description":"Default weight unit. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer` · Nullable."},"allow_custom_package":{"type":"boolean","description":"Allow custom package. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"surcharges":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"object","description":"Human-readable name.\n\n**Details:** Type `object`."},"description":{"type":"object","description":"Free-text description.\n\n**Details:** Type `object`."},"charge_type":{"type":"integer","description":"Charge type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"amount":{"type":"number","description":"Amount. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"pricing_config":{"type":["object","null"],"description":"Pricing config. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"display_type":{"type":"string","description":"Display type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"display_options":{"type":["object","null"],"description":"Display options. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"unit_label":{"type":"object","description":"Unit label. Human-readable label.\n\n**Details:** Type `object`."},"is_optional":{"type":"boolean","description":"Is optional. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."}}},"description":"Surcharges. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"form_bindings":{"type":"array","items":{"type":"object","properties":{"form_id":{"type":"integer","description":"Form id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"form_code":{"type":"string","description":"Form code. Stable machine-readable code.\n\n**Details:** Type `string`."},"form_name":{"type":"string","description":"Form name. Human-readable label.\n\n**Details:** Type `string`."},"is_required":{"type":"boolean","description":"Is required. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."},"fields":{"type":"array","items":{"type":"object","description":"Fields. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Fields. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"description":"Form bindings. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}}}}},"/v1/customer/moving-orders/config":{"get":{"tags":["Customer"],"summary":"Get the configuration bundle needed to render the customer 'create moving order' form","description":"Returns the moving service packages (pricing plans) the customer picks from, plus the shared packaging catalog, supplies products, moving-date timeframes, unit definitions, surcharges, and dynamic form bindings. Moving orders do not use warehouses — the customer provides origin/destination addresses directly. Requires an authenticated customer account.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Config bundle","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"object","properties":{"moving_packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"display_name":{"type":"object","description":"Locale map\n\n**Details:** Type `object`."},"description":{"type":"object","description":"Locale map\n\n**Details:** Type `object`."},"is_default":{"type":"boolean","description":"Is default. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"display_order":{"type":"integer","description":"Display order. Field in the JSON request body.\n\n**Details:** Type `integer`."},"pricing_type":{"type":"integer","description":"Pricing type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"base_price":{"type":["number","null"],"description":"Base price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number` · Nullable."},"hourly_rate":{"type":["number","null"],"description":"Hourly rate. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable."},"min_hours":{"type":["number","null"],"description":"Min hours. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable."},"min_charge":{"type":["number","null"],"description":"Min charge. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable."},"prepay_ratio":{"type":["number","null"],"description":"Prepay ratio. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable."}}},"description":"Moving packages. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"packagings":{"type":"array","items":{"type":"object","description":"Packagings. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Packagings. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"products":{"type":"array","items":{"type":"object","description":"Products. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Products. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"moving_timeframes":{"type":"array","items":{"type":"object","description":"Moving timeframes. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Moving timeframes. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"dimension_units":{"type":"object","description":"Dimension units. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `object`."},"weight_units":{"type":"object","description":"Weight units. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `object`."},"default_dimension_unit":{"type":["integer","null"],"description":"Default dimension unit. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer` · Nullable."},"default_weight_unit":{"type":["integer","null"],"description":"Default weight unit. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer` · Nullable."},"surcharges":{"type":"array","items":{"type":"object","description":"Surcharges. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Surcharges. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"form_bindings":{"type":"array","items":{"type":"object","description":"Form bindings. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Form bindings. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}}}}},"/v1/customer/shipping-orders/services":{"get":{"tags":["Customer"],"summary":"List shipping services available to the authenticated customer","description":"Returns a lightweight list of shipping services the customer is authorized to use, derived from the customer_shipping_service assignment table. Used as step 1 of the two-step create-order flow; once the customer picks a service, fetch /v1/customer/shipping-orders/services/{serviceCode}/config for the full details. Customers with no explicit service assignment see an empty list.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Services list","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."},"name":{"type":"object","description":"Locale map\n\n**Details:** Type `object`."},"offer_pickup":{"type":"boolean","description":"Offer pickup. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"allow_warehouse_delivery":{"type":"boolean","description":"Allow warehouse delivery. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"support_multi_package":{"type":"boolean","description":"Support multi package. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"allow_special_requirements":{"type":"boolean","description":"Allow special requirements. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"allow_purchase_supplies":{"type":"boolean","description":"Allow purchase supplies. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"send_confirmation_email":{"type":"boolean","description":"Send confirmation email. Email address.\n\n**Details:** Type `boolean`."},"warehouses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}}},"description":"Warehouses. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"description":"Services. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"services":[{"id":12,"service_code":"intl_express","name":{"en":"International Express","chs":"国际快递"},"offer_pickup":true,"allow_warehouse_delivery":true,"support_multi_package":true,"allow_special_requirements":false,"allow_purchase_supplies":true,"send_confirmation_email":true,"warehouses":[{"id":5,"name":"Toronto Hub"}]}]}}}}}}}},"/v1/customer/shipping-orders/services/{serviceCode}/config":{"get":{"tags":["Customer"],"summary":"Get the per-service configuration bundle needed to render the 'create shipping order' form","description":"Returns the full config for one shipping service: that service's warehouses (with full address fields), surcharges (drawn from the service's surcharge groups), plus the shared packaging catalog, supplies products (only when allow_purchase_supplies), unit definitions, and dynamic form bindings. Call this after the user picks a service from /v1/customer/shipping-orders/services. Returns 403 if the customer is not authorized for the given service, 404 if it does not exist.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"serviceCode","required":true,"schema":{"type":"string","description":"The shipping service service_code (unique per business)\n\n**Details:** Required · Type `string`."},"description":"The shipping service service_code (unique per business)\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Config bundle","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"data":{"type":"object","properties":{"service":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"service_code":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Type `string`."},"name":{"type":"object","description":"Human-readable name.\n\n**Details:** Type `object`."},"offer_pickup":{"type":"boolean","description":"Offer pickup. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"allow_warehouse_delivery":{"type":"boolean","description":"Allow warehouse delivery. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"support_multi_package":{"type":"boolean","description":"Support multi package. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"allow_special_requirements":{"type":"boolean","description":"Allow special requirements. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"allow_purchase_supplies":{"type":"boolean","description":"Allow purchase supplies. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"send_confirmation_email":{"type":"boolean","description":"Send confirmation email. Email address.\n\n**Details:** Type `boolean`."}},"description":"Service. Field in the JSON request body.\n\n**Details:** Type `object`."},"warehouses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."}}},"description":"Warehouses. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"packagings":{"type":"array","items":{"type":"object","description":"Packagings. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Packagings. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"products":{"type":"array","items":{"type":"object","description":"Products. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Empty unless the service has allow_purchase_supplies=true\n\n**Details:** Type `array`, items `object`."},"surcharges":{"type":"array","items":{"type":"object","description":"Surcharges. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Surcharges. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"dimension_units":{"type":"object","description":"Dimension units. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `object`."},"weight_units":{"type":"object","description":"Weight units. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `object`."},"default_dimension_unit":{"type":["integer","null"],"description":"Default dimension unit. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer` · Nullable."},"default_weight_unit":{"type":["integer","null"],"description":"Default weight unit. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer` · Nullable."},"form_bindings":{"type":"array","items":{"type":"object","description":"Form bindings. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Form bindings. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"Customer not authorized for this service","content":{"application/json":{"example":{"result":false,"message":"Shipping service not available."}}}},"404":{"description":"Service not found","content":{"application/json":{"example":{"result":false,"message":"Shipping service not found."}}}}}}},"/v1/customer/storage-orders":{"post":{"tags":["Customer Storage Orders"],"operationId":"customerStorageOrderCreate","summary":"Create a storage order","description":"Creates a storage order for the authenticated customer. Same fields as the storage order form; business_id and customer_id come from the authentication and are never read from the body. Supports the OPTIONAL Idempotency-Key header.","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first 2xx answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-2xx outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."},"description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first 2xx answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-2xx outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The storage order form fields: warehouse, packages/items, timeframe, channel fields, and per-form form_data. The authoritative field list is the storage order form; unknown fields are ignored.","additionalProperties":true}}}},"responses":{"200":{"description":"Created. The body carries result and the created order.","headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"replayed":{"type":"boolean","description":"Present only on an Idempotency-Key replay\n\n**Details:** Type `boolean`."}},"additionalProperties":true}}}},"409":{"description":"Idempotency conflict: the key was already used with a different body (IDEMPOTENCY_CONFLICT), or the original request is still processing (IDEMPOTENCY_IN_PROGRESS, with Retry-After: 1).","headers":{"Retry-After":{"description":"Present only on the IDEMPOTENCY_IN_PROGRESS answer: retry after this many seconds.","schema":{"type":"string","examples":[1]}}}},"422":{"description":"Validation failed"}}},"get":{"tags":["Customer"],"summary":"List the authenticated customer's storage orders","description":"Paginated list; mirrors admin StorageOrderController::index filter/sort semantics via StorageOrderService::getStorageOrders, scoped to the authenticated customer.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"status","schema":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},{"in":"query","name":"warehouse_id","schema":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `integer`."},"description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `integer`."},{"in":"query","name":"store_from","schema":{"type":"string","format":"date","description":"Store from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Store from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"store_to","schema":{"type":"string","format":"date","description":"Store to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Store to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"created_at_from","schema":{"type":"string","format":"date","description":"Created at from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Created at from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"created_at_to","schema":{"type":"string","format":"date","description":"Created at to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Created at to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"quick_search","schema":{"type":"string","description":"Quick search. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`."},"description":"Quick search. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`."},{"in":"query","name":"id","schema":{"type":"string","description":"Resource identifier.\n\n**Details:** Type `string`."},"description":"Resource identifier.\n\n**Details:** Type `string`."},{"in":"query","name":"package_id","schema":{"type":"string","description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"description":"Package id. Identifier referencing the related record.\n\n**Details:** Type `string`."},{"in":"query","name":"sort_by","schema":{"type":"string","enum":["created_desc","expiry_asc"],"default":"created_desc","description":"Allowed values: `created_desc` · `expiry_asc`.\n\n**Details:** Type `string` · Default: `created_desc`."},"description":"Allowed values: `created_desc` · `expiry_asc`.\n\n**Details:** Type `string` · Default: `created_desc`."},{"in":"query","name":"per_page","schema":{"type":"integer","default":20,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `20`."},"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `20`."},{"in":"query","name":"page","schema":{"type":"integer","default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","description":"Laravel paginator (data[], current_page, last_page, total, per_page, ...)\n\n**Details:** Type `object`."}}}}}}}}},"/v1/customer/storage-orders/{id}":{"get":{"tags":["Customer"],"summary":"Get the detail of one storage order owned by the authenticated customer","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Storage order detail","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"can_edit":{"type":"boolean","description":"True when the customer may edit the order in its current status.\n\n**Details:** Type `boolean`."},"can_cancel":{"type":"boolean","description":"True when the customer may cancel the order in its current status.\n\n**Details:** Type `boolean`."},"storage_code":{"type":["string","null"],"description":"Storage code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"store_from":{"type":"string","description":"Store from. Field in the JSON request body.\n\n**Details:** Type `string`."},"store_to":{"type":"string","description":"Store to. Field in the JSON request body.\n\n**Details:** Type `string`."},"warehouse_id":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `integer`."},"need_pickup":{"type":"boolean","description":"Need pickup. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"need_delivery":{"type":"boolean","description":"Need delivery. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable."},"value":{"type":["string","null"],"description":"Value. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"weight":{"type":["string","null"],"description":"Weight of the package or shipment.\n\n**Details:** Type `string` · Nullable."},"weight_unit":{"type":["integer","null"],"description":"1=g, 2=kg, 3=oz, 4=lb\n\n**Details:** Type `integer` · Nullable."},"length":{"type":"string","description":"Length dimension.\n\n**Details:** Type `string`."},"width":{"type":"string","description":"Width dimension.\n\n**Details:** Type `string`."},"height":{"type":"string","description":"Height dimension.\n\n**Details:** Type `string`."},"dimension_unit":{"type":"integer","description":"1=mm, 2=cm, 3=m, 4=in\n\n**Details:** Type `integer`."},"packaging_id":{"type":["integer","null"],"description":"Packaging id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"packaging":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}},"description":"Packaging. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"received":{"type":"boolean","description":"True once the warehouse has received this package.\n\n**Details:** Type `boolean`."}}},"description":"Items. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable."},"value":{"type":["string","null"],"description":"Value. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"weight":{"type":["string","null"],"description":"Weight of the package or shipment.\n\n**Details:** Type `string` · Nullable."},"weight_unit":{"type":["integer","null"],"description":"1=g, 2=kg, 3=oz, 4=lb\n\n**Details:** Type `integer` · Nullable."},"length":{"type":"string","description":"Length dimension.\n\n**Details:** Type `string`."},"width":{"type":"string","description":"Width dimension.\n\n**Details:** Type `string`."},"height":{"type":"string","description":"Height dimension.\n\n**Details:** Type `string`."},"dimension_unit":{"type":"integer","description":"1=mm, 2=cm, 3=m, 4=in\n\n**Details:** Type `integer`."},"packaging_id":{"type":["integer","null"],"description":"Packaging id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"packaging":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}},"description":"Packaging. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"quantity":{"type":"integer","description":"Quantity of units.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"received":{"type":"boolean","description":"True once the warehouse has received this package.\n\n**Details:** Type `boolean`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"total_price":{"type":["number","null"],"description":"Total price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"created_at":{"type":"string","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"id":1532,"status":"partial received","can_edit":true,"can_cancel":false,"storage_code":"S7K2P9","store_from":"2026-10-01","store_to":"2026-10-31","warehouse_id":12,"need_pickup":false,"need_delivery":false,"items":[{"id":901,"description":"Books","value":0,"weight":12,"weight_unit":2,"length":60,"width":40,"height":40,"dimension_unit":2,"packaging_id":null,"packaging":null,"quantity":1,"received":true},{"id":902,"description":"Lamp","value":0,"weight":3,"weight_unit":2,"length":50,"width":30,"height":30,"dimension_unit":2,"packaging_id":null,"packaging":null,"quantity":1,"received":false}],"total_price":42.5,"currency":"CAD","created_at":"2026-09-20 10:12:00"}}}}},"404":{"description":"Not found"}},"description":"Returns one storage order owned by the authenticated customer. `can_edit` and `can_cancel` tell the client whether PUT /v1/customer/storage-orders/{id} and POST /v1/customer/storage-orders/{id}/cancel will be accepted in the order's current status. Each package carries `received`: a received package is kept when the order is edited, so an edit must send only the packages whose `received` is false in `items`."}},"/v1/customer/moving-orders":{"post":{"tags":["Customer Moving Orders"],"operationId":"customerMovingOrderCreate","summary":"Create a moving order","description":"Creates a moving order for the authenticated customer. Same fields as the moving order form; business_id and customer_id come from the authentication and are never read from the body. Supports the OPTIONAL Idempotency-Key header.","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first 2xx answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-2xx outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."},"description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first 2xx answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-2xx outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The moving order form fields: addresses, date, resources, channel fields, and per-form form_data. The authoritative field list is the moving order form; unknown fields are ignored.","additionalProperties":true}}}},"responses":{"200":{"description":"Created. The body carries result and the created order.","headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"replayed":{"type":"boolean","description":"Present only on an Idempotency-Key replay\n\n**Details:** Type `boolean`."}},"additionalProperties":true}}}},"409":{"description":"Idempotency conflict: the key was already used with a different body (IDEMPOTENCY_CONFLICT), or the original request is still processing (IDEMPOTENCY_IN_PROGRESS, with Retry-After: 1).","headers":{"Retry-After":{"description":"Present only on the IDEMPOTENCY_IN_PROGRESS answer: retry after this many seconds.","schema":{"type":"string","examples":[1]}}}},"422":{"description":"Validation failed"}}},"get":{"tags":["Customer"],"summary":"List the authenticated customer's moving orders","description":"Paginated list; mirrors admin MovingOrderController::index filter/sort semantics via MovingOrderService::getMovingOrders, scoped to the authenticated customer.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"status","schema":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},{"in":"query","name":"moving_date_from","schema":{"type":"string","format":"date","description":"Moving date from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Moving date from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"moving_date_to","schema":{"type":"string","format":"date","description":"Moving date to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Moving date to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"created_at_from","schema":{"type":"string","format":"date","description":"Created at from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Created at from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"created_at_to","schema":{"type":"string","format":"date","description":"Created at to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Created at to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"sort_by","schema":{"type":"string","enum":["created_desc","date_asc"],"default":"created_desc","description":"Allowed values: `created_desc` · `date_asc`.\n\n**Details:** Type `string` · Default: `created_desc`."},"description":"Allowed values: `created_desc` · `date_asc`.\n\n**Details:** Type `string` · Default: `created_desc`."},{"in":"query","name":"per_page","schema":{"type":"integer","default":20,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `20`."},"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `20`."},{"in":"query","name":"page","schema":{"type":"integer","default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."}],"responses":{"200":{"description":"Paginated list"}}}},"/v1/customer/moving-orders/{id}":{"get":{"tags":["Customer"],"summary":"Get the detail of one moving order owned by the authenticated customer","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Moving order detail"},"404":{"description":"Not found"}}}},"/v1/customer/shipping-orders/services/{serviceCode}/orders":{"post":{"tags":["Customer Shipping Orders"],"operationId":"customerShippingOrderCreate","summary":"Create a shipping order on a service","description":"Creates a shipping order on the named shipping service for the authenticated customer. The service must be active and available to the caller. Supports the OPTIONAL Idempotency-Key header; the serviceCode path parameter joins the idempotency fingerprint, so the same key on a different service is a conflict, never a replay.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"serviceCode","required":true,"schema":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Required · Type `string`."},"description":"Service code. Stable machine-readable code.\n\n**Details:** Required · Type `string`."},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first 2xx answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-2xx outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."},"description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first 2xx answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-2xx outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The shipping order fields for the service: consignee address and contact, packages with stated units, pickup/delivery options. The authoritative field list is the shipping order form of the service; unknown fields are ignored.","additionalProperties":true}}}},"responses":{"200":{"description":"Created. The body carries result and the created order.","headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome.","schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"replayed":{"type":"boolean","description":"Present only on an Idempotency-Key replay\n\n**Details:** Type `boolean`."}},"additionalProperties":true}}}},"409":{"description":"Idempotency conflict: the key was already used with a different body (IDEMPOTENCY_CONFLICT), or the original request is still processing (IDEMPOTENCY_IN_PROGRESS, with Retry-After: 1).","headers":{"Retry-After":{"description":"Present only on the IDEMPOTENCY_IN_PROGRESS answer: retry after this many seconds.","schema":{"type":"string","examples":[1]}}}},"422":{"description":"Validation failed"}}},"get":{"tags":["Customer"],"summary":"List the authenticated customer's shipping orders under one service","description":"Paginated list scoped to the customer + service. 403 if the customer is not authorized for the service; 404 if the service does not exist.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"serviceCode","required":true,"schema":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Required · Type `string`."},"description":"Service code. Stable machine-readable code.\n\n**Details:** Required · Type `string`."},{"in":"query","name":"status","schema":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},{"in":"query","name":"id","schema":{"type":"string","description":"Matches order id, tracking_number or reference_number\n\nResource identifier.\n\n**Details:** Type `string`."},"description":"Matches order id, tracking_number or reference_number\n\nResource identifier.\n\n**Details:** Type `string`."},{"in":"query","name":"created_at_from","schema":{"type":"string","format":"date","description":"Created at from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Created at from. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"created_at_to","schema":{"type":"string","format":"date","description":"Created at to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},"description":"Created at to. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"sort_by","schema":{"type":"string","enum":["created_desc","created_asc"],"default":"created_desc","description":"Allowed values: `created_desc` · `created_asc`.\n\n**Details:** Type `string` · Default: `created_desc`."},"description":"Allowed values: `created_desc` · `created_asc`.\n\n**Details:** Type `string` · Default: `created_desc`."},{"in":"query","name":"per_page","schema":{"type":"integer","default":20,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `20`."},"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `20`."},{"in":"query","name":"page","schema":{"type":"integer","default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."}],"responses":{"200":{"description":"Paginated list"},"403":{"description":"Customer not authorized for this service"},"404":{"description":"Service not found"}}}},"/v1/customer/shipping-orders/{id}":{"get":{"tags":["Customer"],"summary":"Get the detail of one shipping order owned by the authenticated customer","description":"The order id alone identifies the service; the customer's service access is enforced via the customer_shipping_service assignment (returns 403 if the order's service is not granted to this customer).","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Shipping order detail"},"403":{"description":"Customer not authorized for this order's service"},"404":{"description":"Order not found"}}}},"/v1/customer/shipout-orders/available-items":{"get":{"tags":["Customer"],"summary":"List storage packages eligible for shipout","description":"Returns storage packages that are received, not yet stocked out, and not locked by an active shipout request. Grouped by StorageOrder. Optional warehouse_id filter narrows the result to one source warehouse. Partner accounts (groups_id=7) receive 403. Requires the customer shipout_service setting to be enabled; otherwise returns 403.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"warehouse_id","required":false,"schema":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"description":"Warehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Available items grouped by storage order, plus warehouse summary","content":{"application/json":{"example":{"result":true,"data":{"warehouses":[{"id":7,"name":"Toronto Hub","available_count":4}],"storage_orders":[{"id":1024,"warehouse_id":7,"created_at":"2026-04-10","packages":[{"id":5001,"description":"Box A","weight":2,"weight_unit":2,"length":30,"width":20,"height":15,"dimension_unit":2,"value":100,"packaging":null}]}]}}}}},"403":{"description":"Shipout disabled for this customer, partner accounts blocked, or customer context missing"}}}},"/v1/customer/shipout-orders/services":{"get":{"tags":["Customer"],"summary":"List shipping services available from a given warehouse","description":"Filters ShippingService records to those whose shipping_service_warehouse pivot includes the given warehouse_id. Further filtered by the customer's customer_shipping_service assignment. pricing_method=0 means manual pricing (request will go to staff queue), pricing_method=1 means price plan (auto-priced). Requires the customer shipout_service setting to be enabled; otherwise returns 403.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"warehouse_id","required":true,"schema":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."},"description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Services available from this warehouse","content":{"application/json":{"example":{"result":true,"data":{"services":[{"id":5,"service_code":"intl_standard","name":{"en":"International Standard"},"pricing_method":1,"pricing_method_name":"Shipping Price Plan","support_multi_package":true,"allow_special_requirements":false}]}}}}},"403":{"description":"Shipout disabled for this customer, partner accounts blocked, or customer context missing"},"422":{"description":"warehouse_id is required"}}}},"/v1/customer/shipout-orders/services/{serviceCode}/estimate":{"post":{"tags":["Customer"],"summary":"Estimate the price of a shipout request","description":"Returns either a price breakdown (PRICING_PRICE_PLAN services) or {has_items_needing_quote: true} when the service uses manual pricing. Customer should still proceed to /orders even when manual — the request will land in the staff pricing queue. Requires the customer shipout_service setting to be enabled; otherwise returns 403.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"serviceCode","required":true,"schema":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Required · Type `string`."},"description":"Service code. Stable machine-readable code.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"warehouse_id":7,"delivery_postcode":"M5V2H1","delivery_country":"CA","packages":[{"weight":2.5,"length":30,"width":20,"height":15,"weight_unit":2,"dimension_unit":2}]}}}},"responses":{"200":{"description":"Price quote (or {has_items_needing_quote:true} for manual pricing)"},"403":{"description":"Shipout disabled for this customer, partner accounts blocked, or customer context missing"},"404":{"description":"Service not found"}}}},"/v1/customer/shipout-orders/{id}":{"get":{"tags":["Customer"],"summary":"Get shipout detail","description":"Returns the full detail of one shipout owned by the authenticated customer, including paid_amount, remaining_balance, has_items_needing_quote, can_be_paid, can_be_cancelled, and the linked storage_packages + shipping_packages arrays. Requires the customer shipout_service setting to be enabled; otherwise returns 403.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Shipout detail"},"403":{"description":"Shipout disabled for this customer, partner accounts blocked, or customer context missing"},"404":{"description":"Not found"}}}},"/v1/customer/shipout-orders/{id}/pay":{"post":{"tags":["Customer"],"summary":"Pay a shipout from wallet balance","description":"Customer pays a (priced) shipout from their wallet. Body may include `amount` to pay partially; default is the full remaining balance. Status auto-bumps to CONFIRMED when remaining_balance reaches zero. Requires the customer shipout_service setting to be enabled; otherwise returns 403.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"content":{"application/json":{"example":{"amount":45.3}}}},"responses":{"200":{"description":"Payment recorded","content":{"application/json":{"example":{"result":true,"data":{"transaction_id":9001,"amount":"45.30","order_status":1,"paid_amount":45.3,"remaining_balance":0}}}}},"402":{"description":"Insufficient wallet balance"},"403":{"description":"Shipout disabled for this customer, partner accounts blocked, or customer context missing"},"422":{"description":"Order not payable, or invalid amount"}}}},"/v1/customer/shipout-orders/{id}/cancel":{"post":{"tags":["Customer"],"summary":"Cancel a shipout (releases the StoragePackage lock)","description":"Customer cancels — only allowed in PENDING/CONFIRMED. The linked StoragePackages immediately become available for another shipout request. Refund is NOT issued automatically — staff handles refunds manually. Requires the customer shipout_service setting to be enabled; otherwise returns 403.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"content":{"application/json":{"example":{"reason":"Changed shipping plans"}}}},"responses":{"200":{"description":"Cancelled"},"403":{"description":"Shipout disabled for this customer, partner accounts blocked, or customer context missing"},"422":{"description":"Cannot cancel in current state"}}}},"/v1/customer/shipout-orders/services/{serviceCode}/orders":{"post":{"tags":["Customer"],"summary":"Create a shipout request","description":"Creates a ShippingOrder with is_storage_shipout=true and locks the chosen StoragePackages via the shipping_order_storage_packages pivot. All selected packages must belong to the requesting customer and live at the same warehouse. Auto-priced services compute total_price immediately; manual-priced services land in the staff pricing queue with has_items_needing_quote=true. Requires the customer shipout_service setting to be enabled; otherwise returns 403. Optional consolidation mode: pass is_consolidation=true (requires the customer consolidation_service setting instead of shipout_service) to create a consolidation shipout — no outbound cartons are created up front (warehouse staff pack N stored parcels into M cartons later and the price is re-quoted from measured cartons; the initial quote carries price_breakdown.is_estimate=true), and fulfillment_channel picks how the shipment leaves the warehouse: label_service (default), own_delivery, or tpd.","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first HTTP 200 answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-200 outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."},"description":"Optional. A key derived from your own stable ids. A repeated key with the same body replays the first HTTP 200 answer (body replayed: true, header Idempotency-Replayed: true); the same key with a different body is refused 409 IDEMPOTENCY_CONFLICT; a non-200 outcome releases the key so the request may be corrected and retried.\n\n**Details:** Optional · Type `string`."},{"in":"path","name":"serviceCode","required":true,"schema":{"type":"string","description":"Service code. Stable machine-readable code.\n\n**Details:** Required · Type `string`."},"description":"Service code. Stable machine-readable code.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"warehouse_id":7,"storage_package_ids":[5001,5002,5003],"delivery_name":"Jane Doe","delivery_telephone":"+14165551234","delivery_email":"jane@example.com","delivery_address_1":"123 King St W","delivery_city":"Toronto","delivery_province":"ON","delivery_country":"CA","delivery_postcode":"M5V2H1","package":[{"description":"Repacked box 1","quantity":1,"weight":5.5,"weight_unit":2,"length":40,"width":30,"height":25,"dimension_unit":2,"value":200}],"scheduled_date":"2026-05-01","note":"Please handle with care","is_consolidation":false,"fulfillment_channel":"label_service"}}}},"responses":{"409":{"description":"Idempotency conflict: the key was already used with a different body (IDEMPOTENCY_CONFLICT), or the original request is still processing (IDEMPOTENCY_IN_PROGRESS, with Retry-After: 1).","headers":{"Retry-After":{"description":"Present only on the IDEMPOTENCY_IN_PROGRESS answer: retry after this many seconds.","schema":{"type":"string","examples":[1]}}}},"201":{"headers":{"Idempotency-Replayed":{"description":"Present only when the response is an Idempotency-Key replay of a previously stored outcome. The body also carries replayed: true.","schema":{"type":"string","enum":["true"]}}},"description":"Shipout request created","content":{"application/json":{"example":{"result":true,"data":{"id":1234,"status":0,"is_storage_shipout":true,"total_price":"45.30","price_breakdown":{"base_price":40,"tax_amount":5.3,"total":45.3,"has_items_needing_quote":false},"has_items_needing_quote":false,"storage_package_ids":[5001,5002,5003]}}}}},"403":{"description":"Shipout disabled for this customer, partner accounts blocked, or customer context missing"},"422":{"description":"Validation error: missing fields, mixed warehouses, or one of the packages is not available"}}}},"/v1/warehouse-transfer/search":{"post":{"tags":["Warehouse Transfer"],"summary":"Search candidate mis-received local delivery packages","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from_warehouse_id"],"properties":{"from_warehouse_id":{"type":"integer","description":"**Required.**\n\nCurrent (wrong) warehouse id\n\n**Details:** Type `integer`."},"received_by":{"type":"integer","description":"Receiver user id\n\n**Details:** Type `integer`."},"date_from":{"type":"string","format":"date","description":"Date from. Field in the JSON request body.\n\n**Details:** Type `string`, format `date`."},"date_to":{"type":"string","format":"date","description":"Date to. Field in the JSON request body.\n\n**Details:** Type `string`, format `date`."},"order_ref":{"type":"string","description":"Order ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"customer_id":{"type":"integer","description":"Filter by customer (users.id where the user is a customer of this business)\n\n**Details:** Type `integer`."},"order_channel_id":{"type":"integer","description":"Filter by order channel id\n\n**Details:** Type `integer`."},"order_batch":{"type":"string","description":"Filter by order batch label (exact match, orders.order_batch)\n\n**Details:** Type `string`."}}},"example":{"from_warehouse_id":12,"received_by":88,"date_from":"2026-05-01","date_to":"2026-05-19","order_ref":"SR12345","customer_id":42,"order_channel_id":7,"order_batch":"BATCH-2026-05-19-A"}}}},"responses":{"200":{"description":"List of candidate packages","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"count":{"type":"integer","description":"Count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"packages":{"type":"array","items":{"type":"object","description":"Packages. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-transfer":{"post":{"tags":["Warehouse Transfer"],"summary":"Queue a transfer of selected orders (async)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from_warehouse_id","to_warehouse_id","order_ids"],"properties":{"from_warehouse_id":{"type":"integer","description":"**Required.**\n\nSource warehouse id\n\n**Details:** Type `integer`."},"to_warehouse_id":{"type":"integer","description":"**Required.**\n\nTarget warehouse id\n\n**Details:** Type `integer`."},"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nOrder ids — all eligible packages of each order will move together\n\n**Details:** Type `array`, items `integer`."},"reason":{"type":"string","maxLength":500,"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · maxLength `500`."}}},"example":{"from_warehouse_id":12,"to_warehouse_id":23,"order_ids":[501,502,503],"reason":"Wrong warehouse scanned at receive"}}}},"responses":{"200":{"description":"Transfer result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"queued":{"type":"boolean","description":"Always true when accepted\n\n**Details:** Type `boolean`."},"batch_no":{"type":"integer","description":"Auto-increment batch id\n\n**Details:** Type `integer`."},"order_count":{"type":"integer","description":"Order count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"eligible_package_count":{"type":"integer","description":"Number of packages that will actually be transferred when the worker processes the job\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-transfer/list":{"get":{"tags":["Warehouse Transfer"],"summary":"Paginated list of transfer batches","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1`."},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"maximum":100,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `20` · max `100`."},"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `20` · max `100`."}],"responses":{"200":{"description":"List response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"type":"object","properties":{"batch_no":{"type":"integer","description":"Batch no. Field in the JSON request body.\n\n**Details:** Type `integer`."},"status":{"type":"integer","enum":[1,2,3,4,5,6,7],"description":"Job status — 1=Queued, 2=Processing, 3=Completed, 4=Failed, 5=RollbackProcessing, 6=RolledBack, 7=RollbackFailed (see App\\Http\\Helper\\Input\\WarehouseTransferStatusInput)\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `1` · `2` · `3` · `4` · `5` · `6` · `7`.\n\n**Details:** Type `integer`."},"expected_count":{"type":"integer","description":"Total packages the job is expected to process\n\n**Details:** Type `integer`."},"processed_count":{"type":"integer","description":"Packages successfully transferred so far\n\n**Details:** Type `integer`."},"failed_count":{"type":"integer","description":"Packages that failed inside the job\n\n**Details:** Type `integer`."},"error_message":{"type":["string","null"],"description":"Last error message if the job failed\n\n**Details:** Type `string` · Nullable."},"started_at":{"type":["string","null"],"format":"date-time","description":"Started at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"completed_at":{"type":["string","null"],"format":"date-time","description":"Completed at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"created_at":{"type":"string","format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"page":{"type":"integer","description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer`."},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`."}},"examples":[{"result":true,"data":[{"batch_no":42,"status":3,"expected_count":7,"processed_count":7,"failed_count":0,"error_message":null,"started_at":"2026-05-19 12:00:00","completed_at":"2026-05-19 12:00:05","created_at":"2026-05-19 11:59:58"}],"total":1,"page":1,"per_page":20}]}}}}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-transfer/{batchNo}":{"get":{"tags":["Warehouse Transfer"],"summary":"Get a transfer batch detail","parameters":[{"name":"batchNo","in":"path","required":true,"schema":{"type":"integer","description":"Batch no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Batch no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Batch detail","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"batch_no":{"type":"integer","description":"Batch no. Field in the JSON request body.\n\n**Details:** Type `integer`."},"status":{"type":"integer","enum":[1,2,3,4,5,6,7],"description":"Job status — 1=Queued, 2=Processing, 3=Completed, 4=Failed, 5=RollbackProcessing, 6=RolledBack, 7=RollbackFailed (see App\\Http\\Helper\\Input\\WarehouseTransferStatusInput)\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `1` · `2` · `3` · `4` · `5` · `6` · `7`.\n\n**Details:** Type `integer`."},"expected_count":{"type":"integer","description":"Expected count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"processed_count":{"type":"integer","description":"Processed count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"failed_count":{"type":"integer","description":"Failed count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"error_message":{"type":["string","null"],"description":"Error message. Free-text note.\n\n**Details:** Type `string` · Nullable."},"started_at":{"type":["string","null"],"format":"date-time","description":"Started at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"completed_at":{"type":["string","null"],"format":"date-time","description":"Completed at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"in_progress":{"type":"boolean","description":"True while the job is still running (status in {1, 2, 5})\n\n**Details:** Type `boolean`."},"is_rolled_back":{"type":"boolean","description":"Is rolled back. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"transfers":{"type":"array","items":{"type":"object","description":"Transfers. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Transfers. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"rollbacks":{"type":"array","items":{"type":"object","description":"Rollbacks. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Rollbacks. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"examples":[{"result":true,"batch_no":42,"status":3,"expected_count":7,"processed_count":7,"failed_count":0,"error_message":null,"started_at":"2026-05-19 12:00:00","completed_at":"2026-05-19 12:00:05","in_progress":false,"is_rolled_back":false,"transfers":[],"rollbacks":[]}]}}}},"404":{"description":"Batch not found"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-transfer/{batchNo}/rollback":{"post":{"tags":["Warehouse Transfer"],"summary":"Queue an entire-batch rollback (async)","parameters":[{"name":"batchNo","in":"path","required":true,"schema":{"type":"integer","description":"Batch no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Batch no. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Rollback result","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"queued":{"type":"boolean","description":"Queued. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"batch_no":{"type":"integer","description":"Batch no. Field in the JSON request body.\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"422":{"description":"Already rolled back or blocked by stocked-out package"}},"security":[{"bearerAuth":[]}]}},"/v1/rider/orders":{"get":{"tags":["InstantRider"],"summary":"List the rider's Instant Deliver orders","description":"In-progress instant orders assigned to the authenticated rider. Pass ?date=YYYY-MM-DD to list that day's orders (including completed); omit for the current active set.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"date","required":false,"schema":{"type":"string","description":"Optional calendar date (rider timezone)\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-06-08`.","examples":["2026-06-08"]},"description":"Optional calendar date (rider timezone)\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-06-08`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RiderOrder","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `RiderOrder`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/available-orders":{"get":{"tags":["InstantRider"],"summary":"List claimable pool orders (incremental)","description":"Dispatch-pool instant orders the rider may self-claim, filtered by the rider's channel/zone bindings. Pass ?since=<server_time from a previous meta> to poll only newly pooled orders; use the returned meta.server_time as the next cursor.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"since","required":false,"schema":{"type":"string","description":"ISO time cursor from a previous meta.server_time\n\n**Details:** Optional · Type `string`."},"description":"ISO time cursor from a previous meta.server_time\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"array","items":{"$ref":"#/components/schemas/RiderOrder","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `RiderOrder`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`."},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"server_time":{"type":"string","description":"Use as the next ?since cursor\n\n**Details:** Type `string`."}},"description":"Meta. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/failure-reasons":{"get":{"tags":["InstantRider"],"summary":"List business failure reasons","description":"The business's configured failure/return reasons, for use with the fail endpoint.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RiderFailureReason","description":"Data. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `RiderFailureReason`."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/orders/{orderId}":{"get":{"tags":["InstantRider"],"summary":"Get one of the rider orders","description":"Full detail of an instant order assigned to the authenticated rider.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"data":{"$ref":"#/components/schemas/RiderOrder","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `RiderOrder`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/orders/{orderId}/claim":{"post":{"tags":["InstantRider"],"summary":"Self-claim a pool order","description":"Atomically take a Waiting-for-Assignment order. Loses cleanly (409) to the dispatch console, auto-dispatch, or another rider.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"data":{"$ref":"#/components/schemas/RiderOrder","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `RiderOrder`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"409":{"description":"Order is no longer available","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/orders/{orderId}/start-pickup":{"post":{"tags":["InstantRider"],"summary":"Start pickup","description":"Mark that the rider is heading to / at the pickup point (stage → picking_up).","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"data":{"$ref":"#/components/schemas/RiderOrder","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `RiderOrder`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"409":{"description":"Action not allowed in the current order state","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/orders/{orderId}/complete-pickup":{"post":{"tags":["InstantRider"],"summary":"Complete pickup","description":"Mark the parcel collected (stage → picked_up).","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"data":{"$ref":"#/components/schemas/RiderOrder","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `RiderOrder`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"409":{"description":"Action not allowed in the current order state","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","description":"Optional rider note recorded on the order\n\n**Details:** Type `string`."}}}}}}}},"/v1/rider/orders/{orderId}/start-delivery":{"post":{"tags":["InstantRider"],"summary":"Start delivery","description":"Mark the rider en route to the dropoff (stage → delivering).","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"data":{"$ref":"#/components/schemas/RiderOrder","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `RiderOrder`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"409":{"description":"Action not allowed in the current order state","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/orders/{orderId}/complete-delivery":{"post":{"tags":["InstantRider"],"summary":"Complete delivery","description":"Mark the order delivered (stage → delivered). Triggers customer delivered notifications.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"data":{"$ref":"#/components/schemas/RiderOrder","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `RiderOrder`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"409":{"description":"Action not allowed in the current order state","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","description":"Optional rider note recorded on the order\n\n**Details:** Type `string`."}}}}}}}},"/v1/rider/orders/{orderId}/fail":{"post":{"tags":["InstantRider"],"summary":"Fail the current leg","description":"Mark the current leg failed; the order leaves the rider flow for the dispatcher (stage → failed). Triggers customer failure notifications.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Free-text failure reason\n\n**Details:** Type `string`."},"return_reason_id":{"type":["integer","null"],"description":"Optional id from /v1/rider/failure-reasons\n\n**Details:** Type `integer` · Nullable."}}}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Successful`.","examples":["Successful"]},"data":{"$ref":"#/components/schemas/RiderOrder","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `RiderOrder`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"409":{"description":"Action not allowed in the current order state","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/online":{"post":{"tags":["InstantRider"],"summary":"Go online (take work)","description":"Mark the rider online. Online riders are eligible for auto-dispatch and the new-order push; offline pauses both.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"task_online":{"type":"boolean","description":"Task online. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/offline":{"post":{"tags":["InstantRider"],"summary":"Go offline (pause work)","description":"Mark the rider offline; auto-dispatch and new-order push skip them.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"task_online":{"type":"boolean","description":"Task online. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/rider/status":{"get":{"tags":["InstantRider"],"summary":"Current online state","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"task_online":{"type":"boolean","description":"Task online. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"Not an authorized Instant Deliver rider","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/smart-locker/superbox/ingest":{"post":{"tags":["SmartLocker"],"summary":"Superbox native device event ingest (EMQX forwarder)","description":"Receives Superbox smart locker device events forwarded by the platform EMQX rules. One JSON document per device MQTT publication: `{\"topic\": \"mibox/{locker_id}/<suffix>\", \"payload\": {...}}`. Supported topic suffixes: `status` (heartbeat, updates the device state registry), `grids-snapshot` (full grid snapshot; Superroute diffs it against the previous snapshot and routes door changes through the shared smart locker webhook pipeline), `event/photos` (POD photo URLs; triggers photo download jobs), `event/open-grids-result` (device acknowledgement of an open command; recorded on the matching smart locker logs), `event/manual-unlock-selfcheck` and `event/boot-rescan-finished`. Authenticated by the platform-level X-Superbox-Token header.","operationId":"superboxDeviceIngest","parameters":[{"name":"X-Superbox-Token","in":"header","required":true,"schema":{"type":"string","description":"Platform ingest token shared with the EMQX rule action (SUPERBOX_INGEST_TOKEN).\n\n**Details:** Required · Type `string`."},"description":"Platform ingest token shared with the EMQX rule action (SUPERBOX_INGEST_TOKEN).\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["topic","payload"],"properties":{"topic":{"type":"string","description":"**Required.**\n\nOriginal device MQTT topic.\n\n**Details:** Type `string`.\n\n**Example:** `mibox/GYB0BF020260/status`.","examples":["mibox/GYB0BF020260/status"]},"payload":{"type":"object","description":"**Required.**\n\nDevice-published JSON payload (also accepted as a JSON-encoded string).\n\n**Details:** Type `object`."}}},"example":{"topic":"mibox/GYB0BF020260/grids-snapshot","payload":{"smart_locker_id":"GYB0BF020260","snapshot_at":"2026-06-12T18:21:47Z","grid_count":54,"grid_details":[{"grid_id":"G-01","grid_number":1,"grid_status":"closed","fault_code":null,"updated_at":"2026-06-12T18:21:47Z"}]}}}}},"responses":{"200":{"description":"Event accepted and processed.","content":{"application/json":{"example":{"result":true,"message":"ok","data":{"event":"grids-snapshot","changes":1}}}}},"400":{"description":"Unsupported topic or malformed payload.","content":{"application/json":{"example":{"result":false,"error":"Unsupported topic suffix 'unknown'.","error_code":"UNSUPPORTED_TOPIC"}}}},"401":{"description":"Missing or invalid X-Superbox-Token.","content":{"application/json":{"example":{"result":false,"error":"Invalid ingest token.","error_code":"INGEST_TOKEN_INVALID"}}}}}}},"/device-telemetry/ingest":{"post":{"tags":["Device Operations"],"summary":"Device usage telemetry ingest (EMQX forwarder / device agent)","description":"Receives a batch of device usage telemetry from a smart locker, Smart Drop or kiosk: which module of the screen was entered, how long a visit lasted, and how it ended. EMQX rules forward what devices publish to `sr/telemetry/{business}/{device_type}/{device_key}` here, and a device agent posts here directly when MQTT is unreachable. Nothing is written to the database on this path: the batch is folded into Redis counters and drained into the usage tables by `device-usage:collect`. Devices upload on a long interval (20 minutes by default, jittered) rather than per interaction — see docs/device-usage-telemetry-design.md. Event types: `session_start`, `module_enter`, `module_exit`, `action`, `error`, `session_end`. A session is counted when it ends, so one spanning two uploads is counted once. Timestamps outside the configured clock skew fall back to arrival time, batches are de-duplicated by `batch_id`, mock devices and unknown device keys are accepted and discarded. Authenticated by the platform-level X-Device-Telemetry-Token header.","operationId":"deviceTelemetryIngest","parameters":[{"name":"X-Device-Telemetry-Token","in":"header","required":true,"schema":{"type":"string","description":"Platform ingest token shared with the EMQX rule action (DEVICE_TELEMETRY_INGEST_TOKEN).\n\n**Details:** Required · Type `string`."},"description":"Platform ingest token shared with the EMQX rule action (DEVICE_TELEMETRY_INGEST_TOKEN).\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_type","device_key","events"],"properties":{"device_type":{"type":"string","enum":["smart_locker","smart_drop","kiosk"],"description":"**Required.**\n\nDevice family reporting the batch.\n\nAllowed values: `smart_locker` · `smart_drop` · `kiosk`.\n\n**Details:** Type `string`."},"device_key":{"type":"string","description":"**Required.**\n\nThe id the hardware knows itself by: locker device id / cpuid, drop code, or kiosk code.\n\n**Details:** Type `string`."},"batch_id":{"type":"string","description":"Identifies the upload so a retry is counted once. Derived from the event ids when omitted.\n\n**Details:** Type `string`."},"sent_at":{"type":"string","format":"date-time","description":"Sent at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"agent":{"type":"string","description":"Agent. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `supercabinet/1.4.2`.","examples":["supercabinet/1.4.2"]},"events":{"type":"array","maxItems":500,"description":"**Required.**\n\nAt most 500 events; a longer batch is refused so the device splits it rather than losing its newest sessions.\n\n**Details:** Type `array`, items `object` · maxItems `500`.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique per event (ULID).\n\n**Details:** Type `string`."},"ts":{"type":"string","format":"date-time","description":"Ts. Field in the JSON request body.\n\n**Details:** Type `string`, format `date-time`."},"session":{"type":"string","description":"Session the event belongs to.\n\n**Details:** Type `string`."},"type":{"type":"string","enum":["session_start","module_enter","module_exit","action","error","session_end"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `session_start` · `module_enter` · `module_exit` · `action` · `error` · `session_end`.\n\n**Details:** Type `string`."},"module":{"type":"string","description":"Part of the screen; unknown values are recorded as `other`.\n\n**Details:** Type `string`.\n\n**Example:** `pickup_by_code`.","examples":["pickup_by_code"]},"outcome":{"type":"string","enum":["completed","abandoned","timeout","error"],"description":"Allowed values: `completed` · `abandoned` · `timeout` · `error`.\n\n**Details:** Type `string`."},"duration_ms":{"type":"integer","description":"Duration ms. Field in the JSON request body.\n\n**Details:** Type `integer`."},"started_at":{"type":"string","format":"date-time","description":"session_end only: when the visit began. The day and hour a session is attributed to.\n\n**Details:** Type `string`, format `date-time`."},"entry_module":{"type":"string","description":"Entry module. Field in the JSON request body.\n\n**Details:** Type `string`."},"exit_module":{"type":"string","description":"Exit module. Field in the JSON request body.\n\n**Details:** Type `string`."},"step_count":{"type":"integer","description":"Step count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"error_count":{"type":"integer","description":"Error count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"language":{"type":"string","description":"Language. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `chs`.","examples":["chs"]},"identity":{"type":["string","null"],"description":"Phone or email, only when the person identified themselves. Hashed on arrival and never stored raw.\n\n**Details:** Type `string` · Nullable."},"path":{"type":"array","items":{"type":"object","description":"Path. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Step path; stored for sessions that ended badly and a sample of the rest.\n\n**Details:** Type `array`, items `object`."}}}}}},"example":{"device_type":"smart_locker","device_key":"GYB0BF020260","batch_id":"01J8Z5N2C7QK9V3M4T6R8W0XYZ","sent_at":"2026-08-29T14:20:11Z","agent":"supercabinet/1.4.2","events":[{"id":"01J8Z5N2C7QK9V3M4T6R8W0AA1","ts":"2026-08-29T14:03:52Z","session":"01J8Z5N2C7QK9V3M4T6R8W0SES","type":"module_enter","module":"pickup_by_code"},{"id":"01J8Z5N2C7QK9V3M4T6R8W0AA2","ts":"2026-08-29T14:04:31Z","session":"01J8Z5N2C7QK9V3M4T6R8W0SES","type":"session_end","module":"pickup_by_code","started_at":"2026-08-29T14:03:52Z","duration_ms":39000,"outcome":"completed","entry_module":"home","exit_module":"pickup_by_code","step_count":3,"error_count":0,"language":"chs"}]}}}},"responses":{"202":{"description":"Batch accepted. Also the answer for an unknown device key, a mock device, or a duplicate batch — a device must stop retrying in all three cases.","content":{"application/json":{"example":{"ok":true,"accepted":12,"skipped":0,"sessions":1,"stored":true}}}},"401":{"description":"Missing or invalid X-Device-Telemetry-Token.","content":{"application/json":{"example":{"ok":false,"message":"Unauthorized"}}}},"422":{"description":"`events` is not an array, or the batch holds more events than the configured maximum.","content":{"application/json":{"example":{"ok":false,"message":"batch holds more than 500 events; split it"}}}}}}},"/print-nodes/pair":{"post":{"tags":["SuperPrinter"],"summary":"Pair a SuperPrinter agent with a one-time code","description":"Redeems the one-time pairing code a client admin generated for a print node. On success the node is bound to the calling PC (fingerprint stored) and a long-lived node_token is returned for all subsequent agent calls. Public endpoint — the pairing code is the credential; it is single-use and expires.","operationId":"printNodePair","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pairing_code"],"properties":{"pairing_code":{"type":"string","description":"**Required.**\n\nPairing code. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `K2M9XY`.","examples":["K2M9XY"]},"hostname":{"type":"string","description":"Hostname. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `STORE-PC-01`.","examples":["STORE-PC-01"]},"os":{"type":"string","description":"Os. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `windows`.","examples":["windows"]},"os_user":{"type":"string","description":"Os user. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `cashier`.","examples":["cashier"]},"machine_id":{"type":"string","description":"Machine id. Identifier referencing the related record.\n\n**Details:** Type `string`.\n\n**Example:** `a1b2c3-machine-guid`.","examples":["a1b2c3-machine-guid"]},"agent_version":{"type":"string","description":"Agent version. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `1.0.0`.","examples":["1.0.0"]}}},"example":{"pairing_code":"K2M9XY","hostname":"STORE-PC-01","os":"windows","os_user":"cashier","machine_id":"a1b2c3-machine-guid","agent_version":"1.0.0"}}}},"responses":{"200":{"description":"Paired.","content":{"application/json":{"example":{"result":true,"message":"Paired successfully.","data":{"node_token":"<64-char token>","node_id":12,"name":"Front Desk PC","mqtt":{"url":"wss://mqtt.srsr.ca/mqtt","username":12,"topic":"superprinter/12/jobs"}}}}}},"404":{"description":"Code invalid or already used.","content":{"application/json":{"example":{"result":false,"error":"Pairing code is invalid or already used.","error_code":"PAIRING_CODE_INVALID"}}}},"410":{"description":"Code expired.","content":{"application/json":{"example":{"result":false,"error":"Pairing code has expired. Ask your administrator for a new one.","error_code":"PAIRING_CODE_EXPIRED"}}}}}}},"/print-nodes/heartbeat":{"post":{"tags":["SuperPrinter"],"summary":"Agent heartbeat + printer inventory","description":"Refreshes the node's last-seen time and stores the printer list the agent enumerated. Authenticated by the node_token.","operationId":"printNodeHeartbeat","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <node_token> from pairing.\n\n**Details:** Required · Type `string`."},"description":"Bearer <node_token> from pairing.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"printers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"default":{"type":"boolean","description":"Default. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}},"description":"Printers. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"agent_version":{"type":"string","description":"Agent version. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"printers":[{"name":"HP M1005","default":true},{"name":"TSC TTP-244","default":false}],"agent_version":"1.0.0"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"result":true}}}},"401":{"description":"Invalid node token."}}}},"/print-nodes/jobs":{"get":{"tags":["SuperPrinter"],"summary":"Poll queued print jobs","description":"Atomically claims this node's queued (non-expired) jobs, marking them sent so a repeat poll will not return them again. Each job is pdf (download payload_url) or raw (inline base64 payload or payload_url; raw_host targets a 9100 printer).","operationId":"printNodeJobs","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <node_token> from pairing.\n\n**Details:** Required · Type `string`."},"description":"Bearer <node_token> from pairing.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Jobs","content":{"application/json":{"example":{"result":true,"jobs":[{"id":9912,"payload_type":"pdf","payload_url":"https://.../inv.pdf","payload":null,"printer_name":"HP M1005","raw_host":null,"options":{"copies":2,"duplex":"long"}}]}}}}}}},"/print-nodes/jobs/{jobId}/ack":{"post":{"tags":["SuperPrinter"],"summary":"Acknowledge a job outcome","description":"Reports the result of a job. Authenticated by the node_token.","operationId":"printNodeAck","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <node_token> from pairing.\n\n**Details:** Required · Type `string`."},"description":"Bearer <node_token> from pairing.\n\n**Details:** Required · Type `string`."},{"name":"jobId","in":"path","required":true,"schema":{"type":"integer","description":"Job id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Job id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["printed","failed","printing"],"description":"**Required.**\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `printed` · `failed` · `printing`.\n\n**Details:** Type `string`."},"error":{"type":"string","description":"Error. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"status":"printed"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"result":true}}}},"404":{"description":"Job not found for this node."}}}},"/print-jobs":{"post":{"tags":["SuperPrinter"],"summary":"Submit a print job to a node","description":"Queues a print job for one of the authenticated business's SuperPrinter nodes and pushes a doorbell to it over EMQX (the agent also polls as fallback). payload_type is pdf (payload_url the agent downloads) or raw (inline base64 payload or payload_url — ZPL/TSPL/ESC-POS or a bitmap-in-command; raw_host targets a 9100 printer).","operationId":"printJobSubmit","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["print_node_id","payload_type"],"properties":{"print_node_id":{"type":"integer","description":"**Required.**\n\nPrint node id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `12`.","examples":[12]},"payload_type":{"type":"string","enum":["pdf","raw"],"description":"**Required.**\n\nAllowed values: `pdf` · `raw`.\n\n**Details:** Type `string`."},"payload_url":{"type":"string","description":"Payload url. Absolute or relative URL.\n\n**Details:** Type `string`.\n\n**Example:** `https://files.example/invoice.pdf`.","examples":["https://files.example/invoice.pdf"]},"payload":{"type":"string","description":"base64 inline bytes for raw jobs\n\n**Details:** Type `string`."},"printer_name":{"type":"string","description":"Printer name. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `HP M1005`.","examples":["HP M1005"]},"raw_host":{"type":"string","description":"Raw host. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `192.168.1.50:9100`.","examples":["192.168.1.50:9100"]},"options":{"type":"object","properties":{"copies":{"type":"integer","description":"Copies. Field in the JSON request body.\n\n**Details:** Type `integer`."},"duplex":{"type":"string","enum":["none","long","short"],"description":"Allowed values: `none` · `long` · `short`.\n\n**Details:** Type `string`."},"paper":{"type":"string","description":"Paper. Field in the JSON request body.\n\n**Details:** Type `string`."}},"description":"Options. Field in the JSON request body.\n\n**Details:** Type `object`."},"source":{"type":"string","description":"Document or data source selector for this developer-center export.\n\n**Details:** Type `string`.\n\n**Example:** `outbound_order:8831`.","examples":["outbound_order:8831"]}}},"example":{"print_node_id":12,"payload_type":"pdf","payload_url":"https://files.example/invoice.pdf","printer_name":"HP M1005","options":{"copies":2,"duplex":"long"},"source":"outbound_order:8831"}}}},"responses":{"200":{"description":"Queued","content":{"application/json":{"example":{"result":true,"message":"Job queued.","data":{"job_id":9912,"status":"queued"}}}}},"404":{"description":"Node not found / not active for this business."},"422":{"description":"Missing payload for the chosen type."}}}},"/device-operation-logs":{"get":{"tags":["Device Operations"],"summary":"List device operation logs","description":"Paginated, newest first, scoped to the authenticated business. Every token field is paired with a *_label translated into the caller’s language. Timestamps are returned in the caller’s timezone with an explicit offset, and date_from/date_to are interpreted in that same timezone. Rows also carry the operation context: grid, operation channel, code used, associated order (typed id), external provider, external order id and mock flag.","operationId":"deviceOperationLogsIndex","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},{"name":"warehouse_id","in":"query","required":false,"schema":{"type":"integer","description":"Filter by warehouse (addressbook id).\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"description":"Filter by warehouse (addressbook id).\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},{"name":"device_type","in":"query","required":false,"schema":{"type":"string","description":"kiosk / smart_locker / smart_drop.\n\n**Details:** Optional · Type `string`."},"description":"kiosk / smart_locker / smart_drop.\n\n**Details:** Optional · Type `string`."},{"name":"action","in":"query","required":false,"schema":{"type":"string","description":"Exact action token, e.g. open, self_pickup, label_printed.\n\n**Details:** Optional · Type `string`."},"description":"Exact action token, e.g. open, self_pickup, label_printed.\n\n**Details:** Optional · Type `string`."},{"name":"result","in":"query","required":false,"schema":{"type":"string","description":"success / failed / pending.\n\n**Details:** Optional · Type `string`."},"description":"success / failed / pending.\n\n**Details:** Optional · Type `string`."},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d, inclusive, in the caller’s timezone.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d, inclusive, in the caller’s timezone.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d, inclusive, in the caller’s timezone.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d, inclusive, in the caller’s timezone.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"keyword","in":"query","required":false,"schema":{"type":"string","description":"Matches device name, target, customer contact or operator name.\n\n**Details:** Optional · Type `string`."},"description":"Matches device name, target, customer contact or operator name.\n\n**Details:** Optional · Type `string`."},{"name":"grid_id","in":"query","required":false,"schema":{"type":"integer","description":"Filter by compartment (grids.id).\n\n**Details:** Optional · Type `integer`."},"description":"Filter by compartment (grids.id).\n\n**Details:** Optional · Type `integer`."},{"name":"operation_channel","in":"query","required":false,"schema":{"type":"string","description":"How the operation reached the system: web / api / device / webhook / system.\n\n**Details:** Optional · Type `string`."},"description":"How the operation reached the system: web / api / device / webhook / system.\n\n**Details:** Optional · Type `string`."},{"name":"code","in":"query","required":false,"schema":{"type":"string","description":"Exact pickup/delivery/return/shipping code presented for the operation.\n\nStable machine code for this resource.\n\n**Details:** Optional · Type `string`."},"description":"Exact pickup/delivery/return/shipping code presented for the operation.\n\nStable machine code for this resource.\n\n**Details:** Optional · Type `string`."},{"name":"order_id","in":"query","required":false,"schema":{"type":"integer","description":"Typed order id; the table it points to is decided by order_type.\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`."},"description":"Typed order id; the table it points to is decided by order_type.\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`."},{"name":"order_type","in":"query","required":false,"schema":{"type":"string","description":"delivery / express / return / storage / carrier_package / partner_delivery.\n\nOrder type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nOrder type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nEnum values (from deployed code):\n- `D` — Delivery\n- `P` — Pickup\n- `L` — Label Service\n- `P2P` — Peer to Peer\n- `S` — Storage Order\n- `M` — Moving Order\n- `SH` — Shipping Service\n- `SO` — Shipout\n- `LTL` — LTL Service\n- `I` — Instant Delivery\n\n**Details:** Optional · Type `string`.","enum":["D","P","L","P2P","S","M","SH","SO","LTL","I"],"x-enumDescriptions":["Delivery","Pickup","Label Service","Peer to Peer","Storage Order","Moving Order","Shipping Service","Shipout","LTL Service","Instant Delivery"]},"description":"delivery / express / return / storage / carrier_package / partner_delivery.\n\nOrder type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nOrder type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nEnum values (from deployed code):\n- `D` — Delivery\n- `P` — Pickup\n- `L` — Label Service\n- `P2P` — Peer to Peer\n- `S` — Storage Order\n- `M` — Moving Order\n- `SH` — Shipping Service\n- `SO` — Shipout\n- `LTL` — LTL Service\n- `I` — Instant Delivery\n\n**Details:** Optional · Type `string`."},{"name":"provider_id","in":"query","required":false,"schema":{"type":"integer","description":"External third-party provider id the operation is attributed to.\n\n**Details:** Optional · Type `integer`."},"description":"External third-party provider id the operation is attributed to.\n\n**Details:** Optional · Type `integer`."},{"name":"external_order_id","in":"query","required":false,"schema":{"type":"string","description":"The external provider's own order/package reference.\n\nMerchant / upstream order reference stored on the Superroute order.\n\n**Details:** Optional · Type `string`."},"description":"The external provider's own order/package reference.\n\nMerchant / upstream order reference stored on the Superroute order.\n\n**Details:** Optional · Type `string`."},{"name":"is_mock","in":"query","required":false,"schema":{"type":"string","enum":["0","1"],"description":"1 = only sandbox mock locker operations, 0 = only real ones.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `string`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"description":"1 = only sandbox mock locker operations, 0 = only real ones.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `string`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","description":"Default 50, maximum 200.\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"Default 50, maximum 200.\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"1-based page number.\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"1-based page number.\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Paginated events","content":{"application/json":{"example":{"success":true,"data":[{"id":974,"occurred_at":"2026-07-16T19:48:50-04:00","warehouse_id":10,"warehouse_name":"Toronto DC","device_type":"smart_locker","device_type_label":"Smart Locker","device_id":5,"device_name":"SL01","action":"open","action_label":"Open Door","target_type":"grid","target_id":5011,"target_label":"SL01 #1","grid_id":5011,"operation_channel":"web","operation_channel_label":"Web Console","code_used":null,"order_id":null,"order_type":null,"order_type_label":"-","provider_id":null,"provider_name":null,"external_order_id":null,"is_mock":false,"operator_type":"user","operator_name":"Akira Tanaka","result":"success","result_label":"Success","error_message":null,"source_table":"smart_locker_logs","source_id":955,"detail":{"initiated_via":"web","compartment_number":1},"detail_rows":[{"label":"Initiated Via","value":"Web Console"},{"label":"Compartment Number","value":1}]}],"pagination":{"current_page":1,"per_page":50,"total":974,"last_page":20}}}}},"401":{"description":"Missing or invalid token."},"422":{"description":"Invalid filter value."}}}},"/device-usage/summary":{"get":{"tags":["Device Operations"],"summary":"Headline device usage for a period, screen and API side by side","description":"How the smart lockers, Smart Drops and kiosks are actually used, screen and API channels side by side, for the authenticated business. The screen channel comes from the terminals themselves and arrives in batches, so the most recent minutes are normally still missing; the API channel is derived from the device operation log. Days follow the account's timezone, sandbox devices are excluded, and devices whose usage collection was switched off do not appear at all.\n\nA venue-partner token is pinned to that partner's own sites and reads a privacy-floored projection: head counts below the floor are withheld rather than rounded, and per-day head counts are not returned at all.\n\nUnique people are counted so that somebody who visits every day counts once for the range, not once per day; the daily `people` figure is each day's own count and must never be summed across days.","operationId":"deviceUsageSummary","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"warehouse_id","in":"query","required":false,"schema":{"type":"integer","description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"The report. `installed` is false, with an empty `data`, while the usage tables have not been created yet.","content":{"application/json":{"example":{"success":true,"installed":true,"data":{"from":"2026-08-23","to":"2026-08-29","summary":{"sessions":1218,"screen_sessions":340,"api_sessions":878,"events":1402,"completed":291,"abandoned":38,"timeouts":11,"errors":7,"identified":180,"avg_seconds":42.6,"abandoned_pct":11.2,"people":164}}}}}},"403":{"description":"The token's holder could not open this report in the web UI either.","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}}}}},"/device-usage/daily":{"get":{"tags":["Device Operations"],"summary":"Device usage day by day, screen and API side by side","description":"How the smart lockers, Smart Drops and kiosks are actually used, screen and API channels side by side, for the authenticated business. The screen channel comes from the terminals themselves and arrives in batches, so the most recent minutes are normally still missing; the API channel is derived from the device operation log. Days follow the account's timezone, sandbox devices are excluded, and devices whose usage collection was switched off do not appear at all.\n\nA venue-partner token is pinned to that partner's own sites and reads a privacy-floored projection: head counts below the floor are withheld rather than rounded, and per-day head counts are not returned at all.\n\nUnique people are counted so that somebody who visits every day counts once for the range, not once per day; the daily `people` figure is each day's own count and must never be summed across days.","operationId":"deviceUsageDaily","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"warehouse_id","in":"query","required":false,"schema":{"type":"integer","description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"The report. `installed` is false, with an empty `data`, while the usage tables have not been created yet.","content":{"application/json":{"example":{"success":true,"installed":true,"data":{"from":"2026-08-23","to":"2026-08-29","days":[{"date":"2026-08-23","screen_sessions":48,"api_operations":126,"people":31,"errors":1,"abandoned_pct":10.4,"avg_seconds":41.2}]}}}}},"403":{"description":"The token's holder could not open this report in the web UI either.","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}}}}},"/device-usage/devices":{"get":{"tags":["Device Operations"],"summary":"Device usage per machine","description":"How the smart lockers, Smart Drops and kiosks are actually used, screen and API channels side by side, for the authenticated business. The screen channel comes from the terminals themselves and arrives in batches, so the most recent minutes are normally still missing; the API channel is derived from the device operation log. Days follow the account's timezone, sandbox devices are excluded, and devices whose usage collection was switched off do not appear at all.\n\nA venue-partner token is pinned to that partner's own sites and reads a privacy-floored projection: head counts below the floor are withheld rather than rounded, and per-day head counts are not returned at all.\n\nUnique people are counted so that somebody who visits every day counts once for the range, not once per day; the daily `people` figure is each day's own count and must never be summed across days.","operationId":"deviceUsageDevices","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"warehouse_id","in":"query","required":false,"schema":{"type":"integer","description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"The report. `installed` is false, with an empty `data`, while the usage tables have not been created yet.","content":{"application/json":{"example":{"success":true,"installed":true,"data":{"from":"2026-08-23","to":"2026-08-29","devices":[{"device_type":"smart_locker","device_id":3,"device_name":"SL-A","warehouse_id":11,"screen_sessions":340,"api_operations":878,"abandoned_pct":11.2,"avg_seconds":42.6,"errors":7,"peak_day_people":34}]}}}}},"403":{"description":"The token's holder could not open this report in the web UI either.","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}}}}},"/device-usage/sites":{"get":{"tags":["Device Operations"],"summary":"Device usage per site","description":"How the smart lockers, Smart Drops and kiosks are actually used, screen and API channels side by side, for the authenticated business. The screen channel comes from the terminals themselves and arrives in batches, so the most recent minutes are normally still missing; the API channel is derived from the device operation log. Days follow the account's timezone, sandbox devices are excluded, and devices whose usage collection was switched off do not appear at all.\n\nA venue-partner token is pinned to that partner's own sites and reads a privacy-floored projection: head counts below the floor are withheld rather than rounded, and per-day head counts are not returned at all.\n\nUnique people are counted so that somebody who visits every day counts once for the range, not once per day; the daily `people` figure is each day's own count and must never be summed across days.","operationId":"deviceUsageSites","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"warehouse_id","in":"query","required":false,"schema":{"type":"integer","description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"The report. `installed` is false, with an empty `data`, while the usage tables have not been created yet.","content":{"application/json":{"example":{"success":true,"installed":true,"data":{"from":"2026-08-23","to":"2026-08-29","sites":[{"warehouse_id":11,"site_name":"King Street","region_key":"Downtown","devices":2,"screen_sessions":340,"api_operations":878,"people":164,"abandoned_pct":11.2,"avg_seconds":42.6}]}}}}},"403":{"description":"The token's holder could not open this report in the web UI either.","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}}}}},"/device-usage/modules":{"get":{"tags":["Device Operations"],"summary":"Device usage per module of the screen, per channel","description":"How the smart lockers, Smart Drops and kiosks are actually used, screen and API channels side by side, for the authenticated business. The screen channel comes from the terminals themselves and arrives in batches, so the most recent minutes are normally still missing; the API channel is derived from the device operation log. Days follow the account's timezone, sandbox devices are excluded, and devices whose usage collection was switched off do not appear at all.\n\nA venue-partner token is pinned to that partner's own sites and reads a privacy-floored projection: head counts below the floor are withheld rather than rounded, and per-day head counts are not returned at all.\n\nUnique people are counted so that somebody who visits every day counts once for the range, not once per day; the daily `people` figure is each day's own count and must never be summed across days.","operationId":"deviceUsageModules","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to six days before `to`. Ranges longer than 366 days are trimmed to the most recent 366.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"warehouse_id","in":"query","required":false,"schema":{"type":"integer","description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"description":"Limit to one site (addressbook id). A site outside the caller's scope returns nothing, never everything.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"The report. `installed` is false, with an empty `data`, while the usage tables have not been created yet.","content":{"application/json":{"example":{"success":true,"installed":true,"data":{"from":"2026-08-23","to":"2026-08-29","modules":[{"module":"pickup_by_code","channel":"screen","entries":210,"actions":396,"completions":171,"abandons":39,"errors":4,"abandoned_pct":18.6,"avg_seconds":36.4}]}}}}},"403":{"description":"The token's holder could not open this report in the web UI either.","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}}}}},"/resale/token/exchange":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Trade an account login for a scoped resale token","description":"The way out of storing a partner's account password. A reseller still configured with the grantor's account credentials signs in with them one last time, exchanges that login for a resale token scoped to the arrangement, and deletes the password.\n\nUnlike every other resale endpoint this one authenticates as the ACCOUNT (a bearer token from `/v1/user/login`) rather than by `X-Resale-Token`, because a caller here has no resale token yet. It refuses unless the grantor has published a live grant to the calling account: a token is a projection of an arrangement, never a substitute for one.\n\nThe plaintext token is returned once and cannot be recovered afterwards.","operationId":"resaleTokenExchange","security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"mapped_shipping_method_id":{"type":"integer","description":"The grantor's shipping method this arrangement sells. When given, the token is scoped to the grant that publishes exactly that service, and the call is refused when no such grant exists. Omit it for a token scoped to the pair.\n\n**Details:** Type `integer`.\n\n**Example:** `42`.","examples":[42]},"note":{"type":"string","maxLength":80,"description":"Free text appended to the token's label, so the grantor can see where the token came from.\n\n**Details:** Type `string` · maxLength `80`.\n\n**Example:** `Migrated from SuperProxy`.","examples":["Migrated from SuperProxy"]}}}}}},"responses":{"200":{"description":"A resale token, shown once.","content":{"application/json":{"example":{"success":true,"token":"srt_example","token_prefix":"srt_exampleA","grant_id":12,"grantor_business_id":101,"grantee_business_id":205,"expires_at":null}}}},"401":{"description":"Not signed in.","content":{"application/json":{"example":{"success":false,"message":"Sign in first."}}}},"409":{"description":"Not a reseller account of the grantor, no grant published to it, or that shipping method was not granted.","content":{"application/json":{"example":{"success":false,"message":"We have not published anything for you to resell yet, so there is nothing to issue a token for."}}}},"503":{"description":"Resale tokens are not set up on the grantor's deployment yet.","content":{"application/json":{"example":{"success":false,"message":"Resale tokens are not set up on this deployment yet."}}}}}}},"/resale/adjustments":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Corrections raised against this reseller's bookings since it last asked","description":"Corrections raised against this reseller's bookings since it last asked.\n\nPulled rather than pushed, deliberately. A push looks simpler until the receiver is down for an afternoon: the sender has tried, the receiver never knew, and money quietly stops being owed. Asking cannot lose anything, because the reseller asks again and its cursor has not moved.\n\n`since` is the `as_of` from the previous answer — the GRANTOR's clock, echoed back. The two deployments do not share one, and comparing your own would skip or repeat rows by exactly the drift between them. The window is inclusive of its own watermark, so re-reading around a shared second is normal; record each correction by its `id`, scoped to this server, and reading the same one twice costs nothing.\n\nOnly corrections against BOOKINGS of the pair on the token are returned. In-instance hops belong to two businesses on the grantor's deployment and are never visible here.\n\nPass the token as `X-Resale-Token`.","operationId":"resaleRemoteAdjustments","parameters":[{"name":"X-Resale-Token","in":"header","required":true,"schema":{"type":"string","description":"The token the grantor issued (srt_…).\n\n**Details:** Required · Type `string`."},"description":"The token the grantor issued (srt_…).\n\n**Details:** Required · Type `string`."},{"name":"since","in":"query","required":false,"schema":{"type":"string","description":"The `as_of` from the previous answer — the grantor's clock, echoed back. Omit to read everything.\n\n**Details:** Optional · Type `string`."},"description":"The `as_of` from the previous answer — the grantor's clock, echoed back. Omit to read everything.\n\n**Details:** Optional · Type `string`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"default":200,"description":"How many corrections to return.\n\n**Details:** Optional · Type `integer` · Default: `200` · max `500`."},"description":"How many corrections to return.\n\n**Details:** Optional · Type `integer` · Default: `200` · max `500`."}],"responses":{"200":{"description":"Answered.","content":{"application/json":{"example":{"success":true,"adjustments":[{"id":77,"booking_ref":"RSB-2026-000123","amount":4.5,"currency":"CAD","origin":"carrier_invoice","status":"accepted","reason":"Carrier billed 14.50 against a quoted 10.00 (reweigh)","updated_at":"2026-09-17T09:59:00+00:00"}],"as_of":"2026-09-17T10:00:00+00:00"}}}},"401":{"description":"No such token.","content":{"application/json":{"example":{"success":false,"message":"This resale token is not recognised."}}}},"403":{"description":"The token was withdrawn or has expired.","content":{"application/json":{"example":{"success":false,"message":"This resale token has been withdrawn."}}}},"422":{"description":"`since` could not be read as a timestamp.","content":{"application/json":{"example":{"success":false,"message":"That timestamp could not be read."}}}}}}},"/resale/capabilities":{"get":{"tags":["ThirdPartyDelivery"],"summary":"What this token may sell, with the terms attached","description":"Cross-deployment resale. A reseller on another Superroute installation presents the resale token the grantor issued it — a credential scoped to that one arrangement, revocable on its own, and with no user session behind it. Nothing outside the grants the token names is reachable through it, and a grant that has been suspended, expired or whose alliance ended stops answering even while the token is still valid.\n\nPass it as `X-Resale-Token`.","operationId":"resaleRemoteCapabilities","parameters":[{"name":"X-Resale-Token","in":"header","required":true,"schema":{"type":"string","description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."},"description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Answered.","content":{"application/json":{"example":{"success":true,"capabilities":[{"grant_id":12,"capability_type":"self_delivery","profile":"parcel","service_name":"Standard","rate_basis":"per_kg","rate_amount":2,"rate_markup_pct":null,"rate_minimum":9,"currency":"CAD","valid_until":null,"quotable_remotely":true}]}}}},"401":{"description":"No such token.","content":{"application/json":{"example":{"success":false,"message":"This resale token is not recognised."}}}},"403":{"description":"The token was withdrawn, or has expired.","content":{"application/json":{"example":{"success":false,"message":"This resale token has been withdrawn."}}}}}}},"/resale/quote":{"post":{"tags":["ThirdPartyDelivery"],"summary":"What a described shipment would cost this reseller","description":"Cross-deployment resale. A reseller on another Superroute installation presents the resale token the grantor issued it — a credential scoped to that one arrangement, revocable on its own, and with no user session behind it. Nothing outside the grants the token names is reachable through it, and a grant that has been suspended, expired or whose alliance ended stops answering even while the token is still valid.\n\nPass it as `X-Resale-Token`.\n\nA moving or storage capability (`profile` `moving` / `storage` in the capabilities list) is not a shipment and is refused with 422. Without `grant_id`, the token's first shipment capability is priced.","operationId":"resaleRemoteQuote","parameters":[{"name":"X-Resale-Token","in":"header","required":true,"schema":{"type":"string","description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."},"description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Answered.","content":{"application/json":{"example":{"success":true,"grant_id":12,"service_name":"Standard","amount":10,"currency":"CAD","breakdown":{"rate_basis":"per_kg","units":5,"weight_kg":5}}}}},"401":{"description":"No such token.","content":{"application/json":{"example":{"success":false,"message":"This resale token is not recognised."}}}},"403":{"description":"The token was withdrawn, or has expired.","content":{"application/json":{"example":{"success":false,"message":"This resale token has been withdrawn."}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"grant_id":{"type":"integer","description":"Grant id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"packages":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"integer","description":"Grams, as this product stores weights\n\n**Details:** Type `integer`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."}}},"example":{"postcode":"M5V 2T6","packages":[{"weight":2500},{"weight":2500}]}}}}}},"/resale/book":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Book a shipment on the grantor's deployment and get the label back","description":"The booking half of a cross-deployment resale, on the resale token rather than on the grantor's account password.\n\nThe SERVICE is taken from the grant, never from the caller: anything sent under a shipping-method key is discarded, so a token can only buy what was published to it.\n\n`Idempotency-Key` is required. Presenting the same key twice returns the first booking (with `replayed: true`) rather than buying a second label, so a request that timed out is safe to retry.\n\nBecause a real shipment exists here, the two cost-based bases (`passthrough`, `higher`) price on this endpoint even though they refuse on `/resale/quote`.\n\nPass the token as `X-Resale-Token`.","operationId":"resaleRemoteBook","parameters":[{"name":"X-Resale-Token","in":"header","required":true,"schema":{"type":"string","description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."},"description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","description":"Your own reference for this shipment. A retry with the same key returns the first booking.\n\n**Details:** Required · Type `string`."},"description":"Your own reference for this shipment. A retry with the same key returns the first booking.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shipment"],"properties":{"shipment":{"type":"object","description":"**Required.**\n\nLabel-order fields: address, packages, reference.\n\n**Details:** Type `object`."},"grant_id":{"type":"integer","description":"Which published price; the first available when omitted.\n\n**Details:** Type `integer`."}}},"example":{"grant_id":12,"shipment":{"postcode":"M5V 2T6","address_1":"1 King St W","packages":[{"weight":2500,"description":"Grams"}]}}}}},"responses":{"200":{"description":"Booked. `label_base64` is the label PDF.","content":{"application/json":{"example":{"success":true,"booking_ref":"rsb_9f2c1a7de4b05c38a1d6e0f4","status":"booked","grant_id":12,"amount":22,"currency":"CAD","tracking_numbers":["1Z999AA10123456784"],"label_base64":"JVBERi0xLjQK..."}}}},"401":{"description":"No such token.","content":{"application/json":{"example":{"success":false,"message":"This resale token is not recognised."}}}},"403":{"description":"The token was withdrawn, or has expired.","content":{"application/json":{"example":{"success":false,"message":"This resale token was withdrawn."}}}},"422":{"description":"Refused with a reason the reseller can act on.","content":{"application/json":{"example":{"success":false,"message":"Only a shipping method can be booked remotely."}}}}}}},"/resale/handover":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Hand an order to the grantor's own delivery and get a booking reference back","description":"The other half of a cross-deployment resale. `/resale/book` buys a LABEL on the grantor's carrier; this gives the grantor an order to carry with its own fleet, or with a carrier it resells. Those two capabilities cannot issue a label, which is why `/resale/book` refuses them and this accepts them.\n\nThe order is created in the grantor's account through their ordinary order-create path, so their deduplication, pricing, geocoding and dispatch rules all apply to it — an order that arrived from another installation behaves like every other order they have.\n\nA `customer_id` or `external_customer` among the fields is DROPPED rather than looked up: a resale relationship is two businesses and creates no customer on either side.\n\n`Idempotency-Key` is required. Presenting the same key twice returns the first handover (with `replayed: true`) rather than creating a second order, so a request that timed out is safe to retry.\n\nWhat comes back is a `booking_ref` — the handle for `/resale/tracking` and `/resale/cancel`. There is no label: the grantor is carrying the parcel.\n\nPass the token as `X-Resale-Token`.","operationId":"resaleRemoteHandover","parameters":[{"name":"X-Resale-Token","in":"header","required":true,"schema":{"type":"string","description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."},"description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","description":"Your own reference for this shipment. A retry with the same key returns the first handover.\n\n**Details:** Required · Type `string`."},"description":"Your own reference for this shipment. A retry with the same key returns the first handover.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shipment"],"properties":{"shipment":{"type":"object","description":"**Required.**\n\nOrder fields in the ordinary create shape: address, contact, packagesDetail. A customer id is dropped.\n\n**Details:** Type `object`."},"grant_id":{"type":"integer","description":"Which published price; the first available when omitted.\n\n**Details:** Type `integer`."}}},"example":{"grant_id":12,"shipment":{"postcode":"M5V 2T6","city":"Toronto","province":"ON","country":"Canada","name":"A Customer","street_number":1,"street_name":"King St W","packagesDetail":[{"weight":2500,"weight_unit":1}]}}}}},"responses":{"200":{"description":"Accepted. `booking_ref` is the handle for tracking and cancellation; `forwarded` says what happened to the onward leg when the grantor sold one of its own carriers.","content":{"application/json":{"example":{"success":true,"booking_ref":"rsb_9f2c1a7de4b05c38a1d6e0f4","kind":"order","status":"booked","grant_id":12,"order_id":884210,"amount":17.25,"currency":"CAD","tracking_numbers":["SR0000012345"],"forwarded":{"forwarded":false,"reason":"own_fleet"}}}}},"401":{"description":"No such token.","content":{"application/json":{"example":{"success":false,"message":"This resale token is not recognised."}}}},"403":{"description":"The token was withdrawn, or has expired.","content":{"application/json":{"example":{"success":false,"message":"This resale token was withdrawn."}}}},"422":{"description":"Refused with a reason the reseller can act on — including the grantor's own validation messages for the order.","content":{"application/json":{"example":{"success":false,"message":"This partner sells that as a label rather than carrying it. Buy it through a SuperProxy shipping method instead."}}}}}}},"/resale/cancel":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Withdraw a booking made under a resale token","description":"Resolved by the reference the booking answered with, never by an order id on the grantor's deployment — a token that could name an order could cancel orders it never booked.\n\nPass the token as `X-Resale-Token`.","operationId":"resaleRemoteCancel","parameters":[{"name":"X-Resale-Token","in":"header","required":true,"schema":{"type":"string","description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."},"description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["booking_ref"],"properties":{"booking_ref":{"type":"string","description":"**Required.**\n\nThe reference the booking answered with.\n\n**Details:** Type `string`."}}},"example":{"booking_ref":"rsb_9f2c1a7de4b05c38a1d6e0f4"}}}},"responses":{"200":{"description":"Withdrawn.","content":{"application/json":{"example":{"success":true,"booking_ref":"rsb_9f2c1a7de4b05c38a1d6e0f4","status":"cancelled","grant_id":12,"amount":22,"currency":"CAD","tracking_numbers":[]}}}},"401":{"description":"No such token.","content":{"application/json":{"example":{"success":false,"message":"This resale token is not recognised."}}}},"403":{"description":"The token was withdrawn, or has expired.","content":{"application/json":{"example":{"success":false,"message":"This resale token was withdrawn."}}}},"422":{"description":"Refused with a reason the reseller can act on.","content":{"application/json":{"example":{"success":false,"message":"Only a shipping method can be booked remotely."}}}}}}},"/resale/tracking":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Tracking events for a booking made under a resale token","description":"Scoped the same way cancel is: this token's own bookings and nothing else on the grantor's deployment.\n\nPass the token as `X-Resale-Token`.","operationId":"resaleRemoteTracking","parameters":[{"name":"X-Resale-Token","in":"header","required":true,"schema":{"type":"string","description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."},"description":"The token the grantor issued (srt_…). Shown once at issue and never recoverable.\n\n**Details:** Required · Type `string`."},{"name":"booking_ref","in":"query","required":true,"schema":{"type":"string","description":"The reference the booking answered with.\n\n**Details:** Required · Type `string`."},"description":"The reference the booking answered with.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Answered.","content":{"application/json":{"example":{"success":true,"booking_ref":"rsb_9f2c1a7de4b05c38a1d6e0f4","status":"booked","grant_id":12,"amount":22,"currency":"CAD","tracking_numbers":["1Z999AA10123456784"],"events":[{"status_id":20,"occurred_at":"2026-08-29 10:15:00","note":null}]}}}},"401":{"description":"No such token.","content":{"application/json":{"example":{"success":false,"message":"This resale token is not recognised."}}}},"403":{"description":"The token was withdrawn, or has expired.","content":{"application/json":{"example":{"success":false,"message":"This resale token was withdrawn."}}}},"422":{"description":"Refused with a reason the reseller can act on.","content":{"application/json":{"example":{"success":false,"message":"Only a shipping method can be booked remotely."}}}}}}},"/print-jobs/{id}":{"get":{"tags":["SuperPrinter"],"summary":"Print job status","description":"Returns the lifecycle status of a job owned by the authenticated business.","operationId":"printJobShow","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Status","content":{"application/json":{"example":{"result":true,"data":{"job_id":9912,"status":"printed","error":null,"printed_at":"2026-06-12T18:30:00+00:00"}}}}},"404":{"description":"Job not found."}}}},"/v1/maps/public/{code}/layers":{"get":{"tags":["Custom Maps"],"summary":"List map layers (public/embed)","description":"Returns Layer Envelopes for a public Custom Map. If the map has config.embed_token, pass embed_token.","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Public map code\n\nStable machine code for this resource.\n\n**Details:** Required · Type `string`.\n\n**Example:** `layer-api-test`."},"description":"Public map code\n\nStable machine code for this resource.\n\n**Details:** Required · Type `string`.\n\n**Example:** `layer-api-test`.","example":"layer-api-test"},{"name":"embed_token","in":"query","required":false,"schema":{"type":"string","description":"Required when map config.embed_token is set. Also accepted as X-Map-Embed-Token header.\n\n**Details:** Optional · Type `string`."},"description":"Required when map config.embed_token is set. Also accepted as X-Map-Embed-Token header.\n\n**Details:** Optional · Type `string`."},{"name":"types","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated layer types filter\n\n**Details:** Optional · Type `string`."},"description":"Comma-separated layer types filter\n\n**Details:** Optional · Type `string`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":2000,"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `2000`."},"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `2000`."}],"responses":{"200":{"description":"Layer envelopes","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"api_version":{"type":"integer","description":"Api version. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"map":{"type":"object","description":"Map. Field in the JSON request body.\n\n**Details:** Type `object`."},"layers":{"type":"array","items":{"type":"object","description":"Layers. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Layers. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"layer":{"type":"object","description":"Layer. Field in the JSON request body.\n\n**Details:** Type `object`."},"features":{"type":"array","description":"Features. Field in the JSON request body.\n\n**Details:** Type `array`."},"meta":{"type":"object","description":"Meta. Field in the JSON request body.\n\n**Details:** Type `object`."},"results":{"type":"array","description":"Results. Field in the JSON request body.\n\n**Details:** Type `array`."},"count":{"type":"integer","description":"Count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"success":true,"api_version":1,"layers":[{"layer_type":"warehouses","features":[]}]}}}},"404":{"description":"Map not found or embed token invalid"}}},"post":{"tags":["Custom Maps"],"summary":"List map layers with bounds (public/embed)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Public map code\n\nStable machine code for this resource.\n\n**Details:** Required · Type `string`.\n\n**Example:** `layer-api-test`."},"description":"Public map code\n\nStable machine code for this resource.\n\n**Details:** Required · Type `string`.\n\n**Example:** `layer-api-test`.","example":"layer-api-test"},{"name":"embed_token","in":"query","required":false,"schema":{"type":"string","description":"Required when map config.embed_token is set. Also accepted as X-Map-Embed-Token header.\n\n**Details:** Optional · Type `string`."},"description":"Required when map config.embed_token is set. Also accepted as X-Map-Embed-Token header.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"embed_token":{"type":"string","description":"Embed token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."},"types":{"type":"array","items":{"type":"string","description":"Types. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"description":"Types. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `array`, items `string`."},"limit":{"type":"integer","description":"Limit. Field in the JSON request body.\n\n**Details:** Type `integer`."},"bounds":{"type":"object","properties":{"north":{"type":"number","description":"North. Field in the JSON request body.\n\n**Details:** Type `number`."},"south":{"type":"number","description":"South. Field in the JSON request body.\n\n**Details:** Type `number`."},"east":{"type":"number","description":"East. Field in the JSON request body.\n\n**Details:** Type `number`."},"west":{"type":"number","description":"West. Field in the JSON request body.\n\n**Details:** Type `number`."}},"description":"Bounds. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/v1/maps/public/{code}/layers/{type}/{key}":{"get":{"tags":["Custom Maps"],"summary":"Get single map layer (public/embed)","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Public map code\n\nStable machine code for this resource.\n\n**Details:** Required · Type `string`.\n\n**Example:** `layer-api-test`."},"description":"Public map code\n\nStable machine code for this resource.\n\n**Details:** Required · Type `string`.\n\n**Example:** `layer-api-test`.","example":"layer-api-test"},{"name":"type","in":"path","required":true,"schema":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Required · Type `string`.\n\n**Example:** `dataset_view`."},"example":"dataset_view","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Required · Type `string`.\n\n**Example:** `dataset_view`."},{"name":"key","in":"path","required":true,"schema":{"type":"string","description":"Key. Stable machine-readable code.\n\n**Details:** Required · Type `string`.\n\n**Example:** `0`."},"example":0,"description":"Key. Stable machine-readable code.\n\n**Details:** Required · Type `string`.\n\n**Example:** `0`."},{"name":"embed_token","in":"query","required":false,"schema":{"type":"string","description":"Required when map config.embed_token is set. Also accepted as X-Map-Embed-Token header.\n\n**Details:** Optional · Type `string`."},"description":"Required when map config.embed_token is set. Also accepted as X-Map-Embed-Token header.\n\n**Details:** Optional · Type `string`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":2000,"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `2000`."},"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `2000`."}],"responses":{"200":{"description":"Single layer envelope"},"404":{"description":"Not found"}}}},"/v1/maps/public/{code}/nearest":{"post":{"tags":["Custom Maps"],"summary":"Nearest locations on a public map","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Public map code\n\nStable machine code for this resource.\n\n**Details:** Required · Type `string`.\n\n**Example:** `layer-api-test`."},"description":"Public map code\n\nStable machine code for this resource.\n\n**Details:** Required · Type `string`.\n\n**Example:** `layer-api-test`.","example":"layer-api-test"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lat","lng"],"properties":{"lat":{"type":"number","description":"**Required.**\n\nLat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `49.1666`.","examples":[49.1666]},"lng":{"type":"number","description":"**Required.**\n\nLng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `-123.1336`.","examples":[-123.1336]},"max_results":{"type":"integer","description":"Max results. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `5`.","examples":[5]},"embed_token":{"type":"string","description":"Embed token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."},"filters":{"type":"object","description":"Filters. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"Nearest results"},"404":{"description":"Not found"}}}},"/v1/maps/{code}/layers":{"get":{"tags":["Custom Maps"],"summary":"List map layers (authenticated business)","security":[{"bearerAuth":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."},"description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."},{"name":"types","in":"query","schema":{"type":"string","description":"Types. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"description":"Types. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},{"name":"limit","in":"query","schema":{"type":"integer","description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `integer`."},"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `integer`."}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}},"/v1/maps/{code}/layers/{type}/{key}":{"get":{"tags":["Custom Maps"],"summary":"Get single map layer (authenticated)","security":[{"bearerAuth":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."},"description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."},{"name":"type","in":"path","required":true,"schema":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Required · Type `string`."},"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Required · Type `string`."},{"name":"key","in":"path","required":true,"schema":{"type":"string","description":"Key. Stable machine-readable code.\n\n**Details:** Required · Type `string`."},"description":"Key. Stable machine-readable code.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/v1/maps/{code}/nearest":{"post":{"tags":["Custom Maps"],"summary":"Nearest search (authenticated)","security":[{"bearerAuth":[]}],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."},"description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["lat","lng"],"properties":{"lat":{"type":"number","description":"**Required.**\n\nLat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`."},"lng":{"type":"number","description":"**Required.**\n\nLng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`."},"max_results":{"type":"integer","description":"Max results. Field in the JSON request body.\n\n**Details:** Type `integer`."}}}}}},"responses":{"200":{"description":"OK"}}}},"/v1/orders/{orderId}/hold":{"post":{"tags":["Orders"],"summary":"Hold order","description":"Put an order on HOLD so it is not dispatched until released. Auth: client API Bearer.","operationId":"holdOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","description":"Order ID\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `string`."},"description":"Order ID\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `string`."},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer token\n\n**Details:** Required · Type `string`."},"description":"Bearer token\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Order held","content":{"application/json":{"example":{"result":true,"id":11092,"before_status":2,"after_status":14,"message":"Order 11092 has been held successfully."}}}},"400":{"description":"Bad request / invalid status"},"401":{"description":"Unauthorized"}}}},"/v1/orders/{orderId}/release":{"post":{"tags":["Orders"],"summary":"Release order from HOLD","description":"Release an order from HOLD back to NEW_ORDER. Auth: client API Bearer.","operationId":"releaseOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","description":"Order ID\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `string`."},"description":"Order ID\n\nSuperroute order id (`orders.id`).\n\n**Details:** Required · Type `string`."},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer token\n\n**Details:** Required · Type `string`."},"description":"Bearer token\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Order released","content":{"application/json":{"example":{"result":true,"id":11092,"before_status":14,"after_status":2,"message":"Order 11092 has been released from hold successfully."}}}},"400":{"description":"Bad request / not on hold"},"401":{"description":"Unauthorized"}}}},"/v1/smart-locker/operator/{deviceId}/session":{"get":{"tags":["Smart Locker"],"summary":"Get smart locker operator session","description":"Resolve the smart locker device for the authenticated operator and return enabled stock-in methods, grid stats, warehouse details, and operator details. Accessible to client, employee, and partner users with warehouse access.","parameters":[{"name":"deviceId","in":"path","required":true,"description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.","schema":{"type":"string","description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"example":{"result":true,"success":true,"device":{"id":"DEVICE-1","shelf_id":30,"shelf_code":"SL-01","warehouse_id":20,"warehouse_name":"Main Warehouse","features":{"carrier_stockin":true,"stockin_by_code":true},"grid_stats":{"total":24,"occupied":6,"empty":18}},"operator":{"id":10,"name":"Operator","email":"operator@example.com","group":"employee"}}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"500":{"description":"Server error"}}}},"/v1/smart-locker/operator/{deviceId}/carriers":{"get":{"tags":["Smart Locker"],"summary":"List carriers for smart locker operator stock-in","description":"Return active carrier settings for the locker business, including whether each carrier requires member number and/or tracking number.","parameters":[{"name":"deviceId","in":"path","required":true,"description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.","schema":{"type":"string","description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}},{"name":"per_page","in":"query","required":false,"description":"Results per page, 1-50. Defaults to 20.\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Results per page, 1-50. Defaults to 20.\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"example":{"result":true,"success":true,"carriers":[{"id":7,"name":"Road Carrier","has_member_number":true,"has_tracking_number":true}],"current_page":1,"last_page":1,"total":1}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"500":{"description":"Server error"}}}},"/v1/smart-locker/operator/{deviceId}/lookup-package":{"post":{"tags":["Smart Locker"],"summary":"Validate carrier package identifiers","description":"Validate carrier_id plus tracking_number/member_number according to carrier settings, then return any existing unshelved placeholder package in the locker warehouse.","parameters":[{"name":"deviceId","in":"path","required":true,"description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.","schema":{"type":"string","description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"carrier_id":{"type":"integer","description":"**Required.**\n\nCarrier setting ID.\n\n**Details:** Type `integer`."},"tracking_number":{"type":["string","null"],"description":"Carrier tracking/reference number. Required for tracking-only carriers.\n\n**Details:** Type `string` · Nullable."},"member_number":{"type":["string","null"],"description":"Carrier member number. Required for member-only carriers.\n\n**Details:** Type `string` · Nullable."}},"required":["carrier_id"]}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"example":{"result":true,"success":true,"carrier":{"id":7,"name":"Road Carrier","has_member_number":true,"has_tracking_number":true},"tracking_number":"TRK-1001","member_number":"MEM-1","placeholder":{"inventory_id":123,"ref":"REF-1","batch":"B1","carrier_order_id":"CO-1"}}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"500":{"description":"Server error"}}}},"/v1/smart-locker/operator/{deviceId}/lookup-by-code":{"post":{"tags":["Smart Locker"],"summary":"Lookup a stock-in placeholder by pickup code","description":"Resolve an unshelved carrier package placeholder by its internal one-time pickup code so the operator can place it into a smart locker compartment.","parameters":[{"name":"deviceId","in":"path","required":true,"description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.","schema":{"type":"string","description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"**Required.**\n\nExisting inventory pickup code.\n\n**Details:** Type `string`."}},"required":["code"]}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"example":{"result":true,"success":true,"inventory_id":123,"pickup_code":"ABCD12","carrier_name":"Road Carrier","tracking_number":"TRK-1001","member_number":"MEM-1","ref":"REF-1"}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"500":{"description":"Server error"}}}},"/v1/smart-locker/operator/{deviceId}/suggest-grid":{"post":{"tags":["Smart Locker"],"summary":"Suggest an empty smart locker compartment","description":"Return the smallest currently empty smart-cell grid, plus a few alternatives. The caller can pass exclude_grid_ids after rejecting a suggested grid.","parameters":[{"name":"deviceId","in":"path","required":true,"description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.","schema":{"type":"string","description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exclude_grid_ids":{"type":["array","null"],"items":{"type":"integer","description":"Exclude grid ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Exclude grid ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer` · Nullable."}}}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"example":{"result":true,"success":true,"suggested":{"grid_id":40,"grid_code":"A-01","compartment_number":1,"size_label":"10x10x10cm"},"alternatives":[]}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"500":{"description":"Server error"}}}},"/v1/smart-locker/operator/{deviceId}/open-and-place":{"post":{"tags":["Smart Locker"],"summary":"Open a compartment for carrier package placement","description":"Open the selected compartment for the operator to place the carrier package. Inventory is not committed until confirm is called.","parameters":[{"name":"deviceId","in":"path","required":true,"description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.","schema":{"type":"string","description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"grid_id":{"type":"integer","description":"**Required.**\n\nGrid ID returned by suggest-grid.\n\n**Details:** Type `integer`."}},"required":["grid_id"]}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"example":{"result":true,"success":true,"compartment_number":1,"smart_locker_log_id":9001,"message":"Compartment opened"}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"500":{"description":"Server error"}}}},"/v1/smart-locker/operator/{deviceId}/confirm":{"post":{"tags":["Smart Locker"],"summary":"Confirm carrier package stock-in","description":"Commit the placed package into inventory. If bind_inventory_id is provided, the API binds an existing placeholder resolved by pickup code. Otherwise it creates or binds a carrier package using carrier_id and identifiers. Returns the one-time pickup code and whether a customer binding exists for notification.","parameters":[{"name":"deviceId","in":"path","required":true,"description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.","schema":{"type":"string","description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"grid_id":{"type":"integer","description":"**Required.**\n\nGrid id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"smart_locker_log_id":{"type":["integer","null"],"description":"Smart locker log id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"bind_inventory_id":{"type":["integer","null"],"description":"Bind inventory id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"carrier_id":{"type":["integer","null"],"description":"Carrier id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"tracking_number":{"type":["string","null"],"description":"Superroute or carrier tracking number.\n\n**Details:** Type `string` · Nullable."},"member_number":{"type":["string","null"],"description":"Member number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"ref":{"type":["string","null"],"description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"batch":{"type":["string","null"],"description":"Batch. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"carrier_order_id":{"type":["string","null"],"description":"Carrier order id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"user_confirmed":{"type":["boolean","null"],"description":"User confirmed. Field in the JSON request body.\n\n**Details:** Type `boolean` · Nullable."}},"required":["grid_id"]}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"example":{"result":true,"success":true,"inventory_id":123,"pickup_code":"ABCD12","compartment_number":1,"grid_code":"A-01","has_member_binding":true,"bound_from_placeholder":false,"duplicate_confirm":false}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"500":{"description":"Server error"}}}},"/v1/smart-locker/manage/claim":{"post":{"tags":["SmartLocker"],"summary":"What a scanned smart locker is, and what is in it","description":"Smart Locker management from the SuperDepot app.\n\nThe code is scanned off the cabinet's operator screen and is presented on EVERY call rather than exchanged once for a session: it expires two minutes after it was drawn, so requiring it each time is what keeps \"I am standing at this cabinet\" true for the whole visit.\n\nThe code says where, never who. Identity is the bearer token; whether that account may act on this cabinet is checked separately — a client admin always may, an employee only with the Allow Smart Locker Management permission, and never a contractor. Every action writes a log line, successes and failures alike.\n\nThe code may travel in the body as `qr_token` or as the `X-Locker-Code` header.","operationId":"smartLockerManageClaim","parameters":[{"name":"X-Locker-Code","in":"header","required":false,"schema":{"type":"string","description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."},"description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["qr_token"],"properties":{"qr_token":{"type":"string","description":"**Required.**\n\nThe code the cabinet drew. Accepted for two minutes.\n\n**Details:** Type `string`."}}},"example":{"qr_token":"slm1|42|1756500000|k3n8x2p1qa.9f2c…"}}}},"responses":{"200":{"description":"The cabinet, door by door.","content":{"application/json":{"example":{"success":true,"shelf":{"shelf_id":88,"shelf_code":"SL-A","warehouse_id":12,"doors_total":24,"doors_occupied":7,"doors":[{"grid_id":901,"display_number":"A1","grid_number":1,"compartment_number":1,"size":"M","available":true,"items":1}]}}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"example":{"success":false,"message":"Unauthenticated."}}}},"403":{"description":"The code was not accepted, or this account may not manage this cabinet.","content":{"application/json":{"example":{"success":false,"message":"Point the camera at the cabinet's code again — it is only accepted for two minutes."}}}},"422":{"description":"The action did not work.","content":{"application/json":{"example":{"success":false,"message":"Say why every door is being opened."}}}}}}},"/v1/smart-locker/manage/open-grid":{"post":{"tags":["SmartLocker"],"summary":"Force one door open on a scanned smart locker","description":"Smart Locker management from the SuperDepot app.\n\nThe code is scanned off the cabinet's operator screen and is presented on EVERY call rather than exchanged once for a session: it expires two minutes after it was drawn, so requiring it each time is what keeps \"I am standing at this cabinet\" true for the whole visit.\n\nThe code says where, never who. Identity is the bearer token; whether that account may act on this cabinet is checked separately — a client admin always may, an employee only with the Allow Smart Locker Management permission, and never a contractor. Every action writes a log line, successes and failures alike.\n\nThe code may travel in the body as `qr_token` or as the `X-Locker-Code` header.\n\nOpens through the same path the station console uses, so the door check and the proof capture are the same code. Logged with the actor whether it opens or not.","operationId":"smartLockerManageOpenGrid","parameters":[{"name":"X-Locker-Code","in":"header","required":false,"schema":{"type":"string","description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."},"description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["qr_token","grid_id"],"properties":{"qr_token":{"type":"string","description":"**Required.**\n\nThe code the cabinet drew. Accepted for two minutes.\n\n**Details:** Type `string`."},"grid_id":{"type":"integer","description":"**Required.**\n\nWhich door.\n\n**Details:** Type `integer`."}}},"example":{"qr_token":"slm1|42|1756500000|k3n8x2p1qa.9f2c…","grid_id":901}}}},"responses":{"200":{"description":"The door was told to open.","content":{"application/json":{"example":{"success":true,"result":true,"message":"Door opened","shelf_id":88,"grid_id":901,"operation_batch_id":"b-77213"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"example":{"success":false,"message":"Unauthenticated."}}}},"403":{"description":"The code was not accepted, or this account may not manage this cabinet.","content":{"application/json":{"example":{"success":false,"message":"Point the camera at the cabinet's code again — it is only accepted for two minutes."}}}},"422":{"description":"The action did not work.","content":{"application/json":{"example":{"success":false,"message":"Say why every door is being opened."}}}}}}},"/v1/smart-locker/manage/open-all":{"post":{"tags":["SmartLocker"],"summary":"Open every door on a scanned smart locker, with a reason","description":"Smart Locker management from the SuperDepot app.\n\nThe code is scanned off the cabinet's operator screen and is presented on EVERY call rather than exchanged once for a session: it expires two minutes after it was drawn, so requiring it each time is what keeps \"I am standing at this cabinet\" true for the whole visit.\n\nThe code says where, never who. Identity is the bearer token; whether that account may act on this cabinet is checked separately — a client admin always may, an employee only with the Allow Smart Locker Management permission, and never a contractor. Every action writes a log line, successes and failures alike.\n\nThe code may travel in the body as `qr_token` or as the `X-Locker-Code` header.\n\nThe heaviest action here: it exposes every parcel in the cabinet. The reason is required and is written onto EACH door's own log line, not onto a summary that could be separated from them. A door that refuses is reported alongside the ones that opened rather than failing the whole run.","operationId":"smartLockerManageOpenAll","parameters":[{"name":"X-Locker-Code","in":"header","required":false,"schema":{"type":"string","description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."},"description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["qr_token","reason"],"properties":{"qr_token":{"type":"string","description":"**Required.**\n\nThe code the cabinet drew. Accepted for two minutes.\n\n**Details:** Type `string`."},"reason":{"type":"string","minLength":3,"maxLength":255,"description":"**Required.**\n\nWhy every door is being opened.\n\n**Details:** Type `string` · minLength `3` · maxLength `255`."}}},"example":{"qr_token":"slm1|42|1756500000|k3n8x2p1qa.9f2c…","reason":"Door fault survey"}}}},"responses":{"200":{"description":"Reported door by door.","content":{"application/json":{"example":{"success":true,"result":true,"reason":"Door fault survey","doors_total":24,"opened":[901,902,903],"failed":[{"grid_id":904,"message":"Door did not respond"}]}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"example":{"success":false,"message":"Unauthenticated."}}}},"403":{"description":"The code was not accepted, or this account may not manage this cabinet.","content":{"application/json":{"example":{"success":false,"message":"Point the camera at the cabinet's code again — it is only accepted for two minutes."}}}},"422":{"description":"The action did not work.","content":{"application/json":{"example":{"success":false,"message":"Say why every door is being opened."}}}}}}},"/v1/smart-locker/manage/report-anomaly":{"post":{"tags":["SmartLocker"],"summary":"Report something an operator can see at a scanned smart locker","description":"What an operator standing at the cabinet can see and the cabinet cannot: a jammed door, a parcel in a compartment the records call empty, one that should be there and is not.\n\nRecorded on the cabinet's own log timeline, beside the door opens it usually follows, rather than as a ticket somewhere else. The kind is a closed list so a fault log stays groupable; the note carries the detail.\n\n`grid_id` is optional — a report about the cabinet as a whole names no door.\n\nPass the token as `qr_token` or `X-Locker-Code`.","operationId":"smartLockerManageReportAnomaly","parameters":[{"name":"X-Locker-Code","in":"header","required":false,"schema":{"type":"string","description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."},"description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["qr_token","kind","note"],"properties":{"qr_token":{"type":"string","description":"**Required.**\n\nThe code the cabinet drew.\n\n**Details:** Type `string`."},"kind":{"type":"string","enum":["door_stuck","item_missing","item_unexpected","damage","other"],"description":"**Required.**\n\nAllowed values: `door_stuck` · `item_missing` · `item_unexpected` · `damage` · `other`.\n\n**Details:** Type `string`."},"note":{"type":"string","minLength":3,"maxLength":255,"description":"**Required.**\n\nWhat was seen.\n\n**Details:** Type `string` · minLength `3` · maxLength `255`."},"grid_id":{"type":"integer","description":"The door it concerns, when it concerns one.\n\n**Details:** Type `integer`."}}},"example":{"qr_token":"slm1|42|1756500000|k3n8x2p1qa.9f2c…","kind":"door_stuck","note":"Door will not latch","grid_id":901}}}},"responses":{"200":{"description":"Recorded on the cabinet's log.","content":{"application/json":{"example":{"success":true,"log_id":88213,"kind":"door_stuck","grid_id":901}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"example":{"success":false,"message":"Unauthenticated."}}}},"403":{"description":"The code was not accepted, or this account may not manage this cabinet.","content":{"application/json":{"example":{"success":false,"message":"Point the camera at the cabinet's code again — it is only accepted for two minutes."}}}},"422":{"description":"Refused with a reason.","content":{"application/json":{"example":{"success":false,"message":"Say what you saw."}}}}}}},"/v1/smart-locker/manage/resolve-door":{"post":{"tags":["SmartLocker"],"summary":"Confirm a flagged smart locker door is shut","description":"Confirm a flagged door is really shut, putting its compartment back into use.\n\nA door the system believes is still open blocks its own compartment: it will not be offered for a parcel and cannot be opened again. Only somebody in front of it can say whether it is really shut.\n\nThis is the ONLY anomaly with a resolve action. The others mean writing off a parcel the records promise, or accepting one nobody expected, and neither is a thing to do from a phone on one person's word — those are reported instead.\n\nA door the system has not flagged is refused rather than answered \"done\", so a stale screen cannot appear to fix a healthy door.\n\nPass the token as `qr_token` or `X-Locker-Code`.","operationId":"smartLockerManageResolveDoor","parameters":[{"name":"X-Locker-Code","in":"header","required":false,"schema":{"type":"string","description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."},"description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["qr_token","grid_id"],"properties":{"qr_token":{"type":"string","description":"**Required.**\n\nQr token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."},"grid_id":{"type":"integer","description":"**Required.**\n\nGrid id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"note":{"type":"string","maxLength":255,"description":"Note. Free-text note.\n\n**Details:** Type `string` · maxLength `255`."}}},"example":{"qr_token":"slm1|42|1756500000|k3n8x2p1qa.9f2c…","grid_id":901,"note":"Latched by hand"}}}},"responses":{"200":{"description":"The compartment is back in use.","content":{"application/json":{"example":{"success":true,"log_id":88214,"grid_id":901,"door_state":"ok"}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"example":{"success":false,"message":"Unauthenticated."}}}},"403":{"description":"The code was not accepted, or this account may not manage this cabinet.","content":{"application/json":{"example":{"success":false,"message":"Point the camera at the cabinet's code again — it is only accepted for two minutes."}}}},"422":{"description":"Nothing to confirm.","content":{"application/json":{"example":{"success":false,"message":"That door is not flagged, so there is nothing to confirm."}}}}}}},"/v1/smart-locker/manage/door-contents":{"post":{"tags":["SmartLocker"],"summary":"What the records say is behind one smart locker door","description":"The list an operator ticks against what they can actually see. Read before the door opens as well as after: \"the records say two and there is one\" is a finding, not a failure.\n\nPass the token as `qr_token` or `X-Locker-Code`.","operationId":"smartLockerManageDoorContents","parameters":[{"name":"X-Locker-Code","in":"header","required":false,"schema":{"type":"string","description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."},"description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["qr_token","grid_id"],"properties":{"qr_token":{"type":"string","description":"**Required.**\n\nQr token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."},"grid_id":{"type":"integer","description":"**Required.**\n\nGrid id. Identifier referencing the related record.\n\n**Details:** Type `integer`."}}},"example":{"qr_token":"slm1|42|1756500000|k3n8x2p1qa.9f2c…","grid_id":901}}}},"responses":{"200":{"description":"What the records hold.","content":{"application/json":{"example":{"success":true,"grid_id":901,"items":[{"inventory_id":55021,"package_id":90210,"tracking_number":"1Z999AA10123456784","ref":null,"member_number":"+14165550100","stored_at":"2026-08-24 11:02:00"}]}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"example":{"success":false,"message":"Unauthenticated."}}}},"403":{"description":"The code was not accepted, or this account may not manage this cabinet.","content":{"application/json":{"example":{"success":false,"message":"Point the camera at the cabinet's code again — it is only accepted for two minutes."}}}},"422":{"description":"Refused with a reason.","content":{"application/json":{"example":{"success":false,"message":"Nothing you named is behind that door."}}}}}}},"/v1/smart-locker/manage/take-out":{"post":{"tags":["SmartLocker"],"summary":"Take parcels out of a smart locker door, under a reason","description":"Taking parcels back OUT of a cabinet.\n\n**handover** ends in the ordinary pickup, the same settlement the cabinet's own screen makes when a customer collects, witnessed by the operator rather than signed for. **overdue_return** and **relay** both end in a stock out under their own reason: neither pretends the parcel reached a warehouse or another cabinet, because it has not — it is in somebody's hands, and the next movement is recorded through the receiving and stock-in flows when it actually happens.\n\nWhether the recipient hears about any of it is the business's own notification settings; these paths emit the events and decide nothing.\n\nPass the token as `qr_token` or `X-Locker-Code`.","operationId":"smartLockerManageTakeOut","parameters":[{"name":"X-Locker-Code","in":"header","required":false,"schema":{"type":"string","description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."},"description":"The scanned code, when not sent in the body.\n\n**Details:** Optional · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["qr_token","grid_id","inventory_ids","reason"],"properties":{"qr_token":{"type":"string","description":"**Required.**\n\nQr token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."},"grid_id":{"type":"integer","description":"**Required.**\n\nGrid id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"inventory_ids":{"type":"array","items":{"type":"integer","description":"Inventory ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"maxItems":50,"description":"**Required.**\n\nWhat the operator actually took — never everything the records hold.\n\n**Details:** Type `array`, items `integer` · maxItems `50`."},"reason":{"type":"string","enum":["handover","overdue_return","relay"],"description":"**Required.**\n\nHuman-readable reason for the action (failure, cancellation, reassignment, etc.).\n\nAllowed values: `handover` · `overdue_return` · `relay`.\n\n**Details:** Type `string`."},"note":{"type":"string","maxLength":255,"description":"Note. Free-text note.\n\n**Details:** Type `string` · maxLength `255`."}}},"example":{"qr_token":"slm1|42|1756500000|k3n8x2p1qa.9f2c…","grid_id":901,"inventory_ids":[55021],"reason":"handover","note":"Collected at the counter"}}}},"responses":{"200":{"description":"Reported parcel by parcel: one that would not settle does not strand the others, which are already out of the cabinet.","content":{"application/json":{"example":{"success":true,"grid_id":901,"reason":"handover","taken":[55021],"failed":[]}}}},"401":{"description":"Not authenticated.","content":{"application/json":{"example":{"success":false,"message":"Unauthenticated."}}}},"403":{"description":"The code was not accepted, or this account may not manage this cabinet.","content":{"application/json":{"example":{"success":false,"message":"Point the camera at the cabinet's code again — it is only accepted for two minutes."}}}},"422":{"description":"Refused with a reason.","content":{"application/json":{"example":{"success":false,"message":"Nothing you named is behind that door."}}}}}}},"/v1/smart-locker/operator/{deviceId}/notify":{"post":{"tags":["Smart Locker"],"summary":"Notify the bound customer for a shelved carrier package","description":"Queue the customer arrival notification for an already-shelved carrier package. A notification is queued only when carrier_setting_id and member_number match an existing customer carrier binding.","parameters":[{"name":"deviceId","in":"path","required":true,"description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`.","schema":{"type":"string","description":"Smart locker device_id, or smart_locker_id when device_id is not configured.\n\nDevice id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"inventory_id":{"type":"integer","description":"**Required.**\n\nShelved carrier package inventory ID.\n\n**Details:** Type `integer`."}},"required":["inventory_id"]}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"example":{"result":true,"success":true,"queued":true,"message":"Notification queued"}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not found"},"409":{"description":"Conflict"},"500":{"description":"Server error"}}}},"/v1/orders-files/reconciliation":{"get":{"tags":["Orders"],"summary":"Incremental proof-attachment reconciliation feed","description":"Pages orders_files rows by updated_at window + id-ASC cursor, scoped to the caller's business (and customer for customer users). Lets partners sync late or replaced POD attachments without re-querying whole orders. Hard-deleted files stop appearing - pair with the pod.files_updated webhook (action=deleted) to observe removals. signed_url expires; re-fetch the feed for a fresh one.","parameters":[{"in":"query","name":"updated_from","required":false,"schema":{"type":"string","description":"Unix timestamp or 'Y-m-d H:i:s' in the platform timezone\n\n**Details:** Optional · Type `string`."},"description":"Unix timestamp or 'Y-m-d H:i:s' in the platform timezone\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"updated_to","required":false,"schema":{"type":"string","description":"Unix timestamp or 'Y-m-d H:i:s' in the platform timezone\n\n**Details:** Optional · Type `string`."},"description":"Unix timestamp or 'Y-m-d H:i:s' in the platform timezone\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"cursor","required":false,"schema":{"type":"string","description":"Opaque cursor from a previous page (next_cursor)\n\n**Details:** Optional · Type `string`."},"description":"Opaque cursor from a previous page (next_cursor)\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `50` · min `1` · max `200`."},"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `50` · min `1` · max `200`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"items":[{"file_id":234567,"order_id":123456,"order_ref":"WP-REF-001","tracking_number":["SR00012345601"],"external_tracking_number":["WP1234567890"],"type":2,"url":"storage/2026-07-20/123456_P_abc.jpeg","signed_url":"https://.../pod-files/234567?expires=...&signature=...","signed_url_expires_at":1784748605,"updated_at":"2026-07-20 14:30:05","updated_timestamp":1784745005,"created_timestamp":1784658605}],"per_page":50,"has_more":true,"next_cursor":"MjM0NTY3"}}}},"400":{"description":"Validation failed"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/orders-reconciliation/diff":{"post":{"tags":["Orders"],"summary":"Reconciliation diff for a batch of numbers","description":"Submit up to 500 of YOUR numbers (matched against external_tracking_number, tracking_number and package ref) and get back, per number: whether it exists, the matched order(s) with current status, proof-attachment count and latest tracking-event id - plus a `missing` list. Designed for scheduled consistency checks (which of my orders never made it / lost events / lack POD) without one-by-one tracking queries.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["numbers"],"properties":{"numbers":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","maxLength":255,"description":"Numbers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string` · maxLength `255`."},"description":"**Required.**\n\nNumbers. Field in the JSON request body.\n\n**Details:** Type `array`, items `string` · minItems `1` · maxItems `500`."}}},"example":{"numbers":["WP1234567890","NO-SUCH-NUMBER"]}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"items":[{"number":"WP1234567890","found":true,"orders":[{"order_id":123456,"order_ref":"WP-REF-001","orders_status_id":8,"proof_file_count":2,"last_tracking_event_id":987654}]},{"number":"NO-SUCH-NUMBER","found":false,"orders":[]}],"missing":["NO-SUCH-NUMBER"],"submitted":2,"found":1}}}},"400":{"description":"Validation failed"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/v1/orders-reconciliation/export":{"get":{"tags":["Orders"],"summary":"Reconciliation CSV export","description":"Streams every order in the requested updated_at window (same filters and scoping as GET /v1/orders-reconciliation) as CSV, one row per package, for spreadsheet-side diffing. UTF-8 with BOM. Capped at 100k orders per export - narrow the window for larger datasets. Columns: order_id, order_ref, type, orders_status_id, orders_status_key, customer_id, package_id, package_ref, tracking_number, external_tracking_number, order_updated_at, order_updated_timestamp.","parameters":[{"in":"query","name":"updated_from","required":false,"schema":{"type":"string","description":"Unix timestamp or 'Y-m-d H:i:s' in the platform timezone\n\n**Details:** Optional · Type `string`."},"description":"Unix timestamp or 'Y-m-d H:i:s' in the platform timezone\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"updated_to","required":false,"schema":{"type":"string","description":"Unix timestamp or 'Y-m-d H:i:s' in the platform timezone\n\n**Details:** Optional · Type `string`."},"description":"Unix timestamp or 'Y-m-d H:i:s' in the platform timezone\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"CSV stream","content":{"text/csv":{"example":"order_id,order_ref,type,orders_status_id,orders_status_key,customer_id,package_id,package_ref,tracking_number,external_tracking_number,order_updated_at,order_updated_timestamp\n123456,WP-REF-001,D,8,successful,1981,234567,WP-REF-001,SR00012345601,WP1234567890,\"2026-07-20 14:30:05\",1784745005"}}},"400":{"description":"Validation failed"},"401":{"description":"Unauthorized"}},"security":[{"bearerAuth":[]}]}},"/webhooks-guide/logs/{id}/redeliver":{"post":{"tags":["Webhooks"],"summary":"Officially redeliver a webhook from its delivery log","description":"Requeues the ORIGINAL payload of a logged webhook delivery to its original URL as an official (non-test) delivery, signed with the current secret. Unlike POST /webhooks-guide/logs/{id}/resend (which marks the delivery as a test), redelivered events are indistinguishable from first-time deliveries to the receiver. Note: the body is re-serialized from the stored JSON, so key order may differ from the original delivery bytes; the signature is computed over the redelivered body, so verification is unaffected.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Webhook delivery log id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Webhook delivery log id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Redelivery queued","content":{"application/json":{"example":{"result":true,"message":"Redelivery queued through the production webhook pipeline.","log_id":12345,"event_type":"tracking.event","target_url":"https://partner.example.com/webhooks"}}}},"401":{"description":"Unauthenticated"},"403":{"description":"Log entry not owned by the caller"},"404":{"description":"Log entry not found"},"422":{"description":"Test delivery, no stored payload, or no webhook_sign_secret configured"},"503":{"description":"Log storage not initialized"}},"security":[{"bearerAuth":[]}]}},"/v1/user/rotate-token":{"post":{"summary":"Rotate API token with a zero-downtime overlap window","description":"Issues a NEW access token while the CURRENT one keeps working for a grace window (default 60 minutes), after which it expires automatically. Unlike /user/refresh-token (which leaves the old token untouched until its original expiry), rotation guarantees the old credential dies shortly after the switch - without ever cutting off in-flight traffic. The current token's lifetime is only ever shortened, never extended.","operationId":"rotateToken","tags":["User"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"grace_period_minutes":{"type":"integer","minimum":1,"maximum":10080,"default":60,"description":"How long the current token stays valid after rotation\n\n**Details:** Type `integer` · Default: `60` · min `1` · max `10080`."}}},"example":{"grace_period_minutes":60}}}},"responses":{"200":{"description":"Rotation successful","content":{"application/json":{"example":{"result":true,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOi...","token_type":"Bearer","expires_at":"2026-07-27 14:30:05","expires_timestamp":1785349805,"name":"John Doe","email":"john@example.com","previous_token_expires_at":"2026-07-20 15:30:05","previous_token_expires_timestamp":1784748605,"grace_period_minutes":60}}}},"400":{"description":"grace_period_minutes out of range (1-10080)"},"401":{"description":"Unauthorized"}}}},"/v1/webhook-settings":{"get":{"tags":["Webhooks"],"summary":"Show my webhook settings","description":"Returns the caller's current webhook configuration (business settings for client/employee callers, customer settings for customer callers). The signing secret is always masked to its last 4 characters. Includes route_board_webhook_url, which delivers route_board.seat_changed (business-level; one event type whose action says whether a seat was claimed / promoted / withdrawn / vetoed / replaced / assigned / awarded / lost / displaced or the board opened / closed / cancelled / settled). Outbound payloads: tracking_event_webhook_url delivers tracking.event, whose delivered (500) / picked-up (510) events carry proof_files plus proof_files_detail (file_id, type 1=signature 2=photo, url, full_url, signed_url, signed_url_expires_at); pod_files_webhook_url delivers pod.files_updated once per proof file with action added / updated / removed (updated also when staff replace a file or set an archived version as current; only the current file is sent, never an archived version). Full payload catalog: /api/webhooks-guide. Every proof file also carries its event context: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery | 2 = pickup) and service_status (1 = success | 2 = failed) — all null for legacy files without a recorded event. device_order_webhook_url (comma-separate multiple URLs; empty string clears) delivers the device_order.* events (stored, collected, removed, overdue, exception_opened, exception_resolved) for parcels handled by smart lockers, kiosks and smart drops, with the same signing, headers and retries as the other business webhooks; event_id is DOE-<id> and stable across retries. It is off unless a URL is set; device_order_events optionally narrows it to a comma-separated list of those event types (empty = all; unknown names are rejected). Partner-owned parcels are not sent on this channel. Payload schema: DeviceOrderWebhookEvent. tracking.event also carries four additive codes for device orders: 470 at_device (awaiting_pickup), 471 device_picked_up (delivered), 472 device_expired (awaiting_pickup), 473 device_removed (received); their location is the device's site and they never include the cell or the pickup code. webhook_endpoint_options (optional; returned only when stored): an object keyed by a webhook URL that is set in one of the URL fields, each value {\"format\": \"native\" | \"ce_binary\" | \"ce_structured\", \"signature\": \"native\" | \"standard_webhooks\"} (an omitted field is native). ce_binary keeps the body and adds CloudEvents 1.0 ce-* headers (ce-id, ce-source, ce-type = ca.superroute.<event>, ce-time, ce-subject, ce-dataschema, ce-srbusiness, ce-srattempt); ce_structured sends the body as a CloudEvent with Content-Type application/cloudevents+json and the native body in data. standard_webhooks adds webhook-id, webhook-timestamp and webhook-signature (Standard Webhooks v1, re-signed on every retry), keyed with webhook_sign_secret in whsec_ form (whsec_ + base64 of the secret). The native headers are always sent as well. A URL that is not listed receives exactly what it received before. Submitting the object replaces the whole map, {} clears it, and entries whose URL is removed from the URL fields are dropped automatically.","responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"recipient_type":"business","settings":{"webhook_sign_secret":"************ABCD","order_status_change_webhook_url":"https://partner.example.com/status","tracking_event_webhook_url":"https://partner.example.com/tracking","pod_files_webhook_url":"https://partner.example.com/pod","webhook_payload_envelope":1,"webhook_verify_ssl":1,"device_order_webhook_url":"https://partner.example.com/device-orders","device_order_events":"device_order.stored,device_order.collected","webhook_endpoint_options":{"https://partner.example.com/tracking":{"format":"ce_structured","signature":"standard_webhooks"}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Settings row not initialized"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Webhooks"],"summary":"Self-serve partial update of my webhook settings","description":"Updates ONLY the submitted keys of the caller's webhook configuration - other keys are untouched, so partners can rotate a URL or the signing secret without an operator and without resending the full form. Unknown keys are rejected (400) so a typo cannot silently drop a URL. Every successful change is recorded in an audit trail (actor, changed keys, masked old/new values, IP). Allowed keys: order_status_change_webhook_url, order_create_async_postback_url, order_create_webhook_url, tracking_event_webhook_url, pod_files_webhook_url, order_deleted_webhook_url, order_cancel_failed_webhook_url, route_board_webhook_url, device_order_webhook_url (URL fields; comma-separate multiple URLs for fan-out; empty string clears), webhook_payload_envelope / order_created_webhook_all_types / webhook_verify_ssl (0 or 1), webhook_sign_secret (16-255 chars), device_order_events (comma-separated device_order.* event types; empty = all). Outbound payloads: tracking_event_webhook_url delivers tracking.event, whose delivered (500) / picked-up (510) events carry proof_files plus proof_files_detail (file_id, type 1=signature 2=photo, url, full_url, signed_url, signed_url_expires_at); pod_files_webhook_url delivers pod.files_updated once per proof file with action added / updated / removed (updated also when staff replace a file or set an archived version as current; only the current file is sent, never an archived version); route_board_webhook_url delivers route_board.seat_changed (business-level; action = claimed / standby / pooled / promoted / withdrawn / vetoed / replaced / assigned / awarded / lost / displaced / settled / board_opened / board_closed / board_cancelled, with board, seat and claim objects always present and null when not applicable). Full payload catalog: /api/webhooks-guide. Every proof file also carries its event context: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery | 2 = pickup) and service_status (1 = success | 2 = failed) — all null for legacy files without a recorded event. webhook_endpoint_options (optional; returned only when stored): an object keyed by a webhook URL that is set in one of the URL fields, each value {\"format\": \"native\" | \"ce_binary\" | \"ce_structured\", \"signature\": \"native\" | \"standard_webhooks\"} (an omitted field is native). ce_binary keeps the body and adds CloudEvents 1.0 ce-* headers (ce-id, ce-source, ce-type = ca.superroute.<event>, ce-time, ce-subject, ce-dataschema, ce-srbusiness, ce-srattempt); ce_structured sends the body as a CloudEvent with Content-Type application/cloudevents+json and the native body in data. standard_webhooks adds webhook-id, webhook-timestamp and webhook-signature (Standard Webhooks v1, re-signed on every retry), keyed with webhook_sign_secret in whsec_ form (whsec_ + base64 of the secret). The native headers are always sent as well. A URL that is not listed receives exactly what it received before. Submitting the object replaces the whole map, {} clears it, and entries whose URL is removed from the URL fields are dropped automatically.","requestBody":{"required":true,"content":{"application/json":{"example":{"tracking_event_webhook_url":"https://partner.example.com/tracking-v2","webhook_sign_secret":"new-strong-secret-0123456789","webhook_endpoint_options":{"https://partner.example.com/tracking-v2":{"format":"ce_structured","signature":"standard_webhooks"}}}}}},"responses":{"200":{"description":"Update applied","content":{"application/json":{"example":{"result":true,"changed_keys":["tracking_event_webhook_url","webhook_sign_secret"],"recipient_type":"business","settings":{"webhook_sign_secret":"************ABCD","order_status_change_webhook_url":"https://partner.example.com/status","tracking_event_webhook_url":"https://partner.example.com/tracking","pod_files_webhook_url":"https://partner.example.com/pod","webhook_payload_envelope":1,"webhook_verify_ssl":1,"device_order_webhook_url":"https://partner.example.com/device-orders","device_order_events":"device_order.stored,device_order.collected","webhook_endpoint_options":{"https://partner.example.com/tracking":{"format":"ce_structured","signature":"standard_webhooks"}}}}}}},"400":{"description":"Unknown key, invalid URL, invalid flag, secret too short, or webhook_endpoint_options that is malformed or names a URL not set in any URL field"},"401":{"description":"Unauthorized"},"404":{"description":"Settings row not initialized"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/bootstrap":{"get":{"tags":["Warehouse Mobile"],"summary":"Bootstrap the warehouse mobile app","description":"Returns the authenticated user, authorized warehouses, per-warehouse capabilities, feature flags and device contract versions.","responses":{"200":{"description":"Bootstrap data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Warehouse mobile is ready.","data":{"api_version":"1.0","user":{"id":10,"name":"Warehouse Operator","group":"employee"},"warehouses":[{"id":276,"name":"Toronto Depot","code":"YYZ","capabilities":{"receive":true,"ship":true,"transfer":false,"count":false}}]}}}}},"401":{"description":"Unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/packages/lookup":{"post":{"tags":["Warehouse Mobile"],"summary":"Look up one package","description":"Resolves an unambiguous package-level code within the authenticated business and returns package, order and inventory location details.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileOperation"},"example":{"warehouse_id":276,"search":"SR10000001"}}}},"responses":{"200":{"description":"Package details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Package found.","data":{"package_id":1001,"order_id":10001,"order_ref":"ORD-10001","package":{"id":1001,"tracking_number":"TRACK-1001","external_tracking_number":"EXT-1001","status_name":"In Warehouse"},"order":{"ref":"ORD-10001"}}}}}},"403":{"description":"Warehouse access denied"},"404":{"description":"Package not found"},"409":{"description":"Ambiguous package code"},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/receive":{"post":{"tags":["Warehouse Mobile"],"summary":"Receive one package","description":"Receives one package into an authorized warehouse using the same order-status rules as the web receive page, including Need Reschedule transitions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileOperation"}}}},"responses":{"200":{"description":"Package received or already received","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Package received successfully.","data":{"package_id":1001,"order_id":10001,"order_ref":"ORD-10001","duplicate":false}}}}},"403":{"description":"Receive capability denied"},"409":{"description":"Package is received at another warehouse"},"422":{"description":"Validation or receive error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/putaway":{"post":{"tags":["Warehouse Mobile"],"summary":"Put away one package","description":"Moves a received package into an existing scannable warehouse grid. Unknown grids are rejected and are never created by this endpoint. When no delivery package or consolidation parcel matches, a pre-advised carrier package staged for this warehouse is shelved on the grid instead (kind=carrier_package); a smart locker compartment is refused for it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WarehouseMobileOperation"},{"type":"object","properties":{"grid_code":{"type":"string","description":"**Required.**\n\nGrid code. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `A-03-02`.","examples":["A-03-02"]}},"required":["grid_code"]}]}}}},"responses":{"200":{"description":"Package put away","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Package put away successfully.","data":{"package_id":1001,"order_id":10001,"order_ref":"ORD-10001","grid":{"id":30,"code":"A-03-02"},"duplicate":false}}}}},"403":{"description":"Receive capability denied"},"404":{"description":"Package or grid not found"},"409":{"description":"Package must be received or transferred first"},"422":{"description":"Validation or putaway error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/putaway-suggestions":{"get":{"tags":["Warehouse Mobile"],"summary":"Ranked putaway suggestions","description":"Returns empty grids ranked by walking distance from the staging/receiving area (entrance as fallback) on the warehouse floor plan. Optionally filters by item size fit when an inventory_id with known package dimensions is given. Distances are in the floor plan's unit (meter or feet).","parameters":[{"name":"warehouse_id","in":"query","required":true,"schema":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."},"description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."},{"name":"floor_plan_id","in":"query","required":false,"description":"Specific floor plan; defaults to the warehouse's lowest active floor level.\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Specific floor plan; defaults to the warehouse's lowest active floor level.\n\n**Details:** Optional · Type `integer`."}},{"name":"inventory_id","in":"query","required":false,"description":"Inventory row whose package dimensions filter the candidates by size fit.\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Inventory row whose package dimensions filter the candidates by size fit.\n\n**Details:** Optional · Type `integer`."}},{"name":"limit","in":"query","required":false,"description":"Maximum suggestions to return (1-50, default 10).\n\n**Details:** Optional · Type `integer` · Default: `10`.","schema":{"type":"integer","default":10,"description":"Maximum suggestions to return (1-50, default 10).\n\n**Details:** Optional · Type `integer` · Default: `10`."}}],"responses":{"200":{"description":"Ranked suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Putaway suggestions are ready.","data":{"origin":{"x":3.5,"y":2,"type":"staging"},"unit":"meter","warehouse_id":12,"floor_plan_id":4,"suggestions":[{"grid_id":30,"grid_code":"A-03-02","shelf_id":7,"shelf_code":"A-03","shelf_row":2,"shelf_column":2,"distance":6.4,"coordinates":{"x":8.2,"y":4.5},"zone":{"id":2,"name":"Picking Zone A","zone_type":"picking"},"reason":"Nearest empty slot","reason_key":"putaway_reason_nearest_empty"},{"grid_id":41,"grid_code":"B-01-01","shelf_id":9,"shelf_code":"B-01","shelf_row":1,"shelf_column":1,"distance":9.8,"coordinates":{"x":12.6,"y":4.5},"zone":null,"reason":"Nearest empty slot","reason_key":"putaway_reason_nearest_empty"}]}}}}},"403":{"description":"Warehouse access denied"},"404":{"description":"Warehouse or floor plan not found"},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/routes":{"get":{"tags":["Warehouse Mobile"],"summary":"List warehouse route jobs","description":"Returns successful routes and route-driver jobs starting from the selected warehouse for one date.","parameters":[{"name":"warehouse_id","in":"query","required":true,"schema":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."},"description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`."}],"responses":{"200":{"description":"Route jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"}}}},"403":{"description":"Ship capability denied"},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/routes/{route}/sort":{"post":{"tags":["Warehouse Mobile"],"summary":"Scan a package for route sorting","description":"Returns the route driver and stop number and updates the existing route sorting scan progress.","parameters":[{"name":"route","in":"path","required":true,"schema":{"type":"integer","description":"Route. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Route. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileOperation"}}}},"responses":{"200":{"description":"Stop and driver assignment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Package sorted successfully.","data":{"order_id":10001,"order_ref":"ORD-10001","stopnumber":"DRV-18","route_driver_id":501,"orders_scanned":20,"orders_unscanned":5}}}}},"403":{"description":"Ship capability denied"},"404":{"description":"Route or package not found"},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/route-drivers/{routeDriver}/outbound":{"get":{"tags":["Warehouse Mobile"],"summary":"Get a route outbound picking list","description":"Returns route-driver packages ordered by grid with remaining and completed progress. Each item carries kind (package or distribution); a distribution item counts as outbound once loaded.","parameters":[{"name":"routeDriver","in":"path","required":true,"schema":{"type":"integer","description":"Route driver. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Route driver. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},{"name":"warehouse_id","in":"query","required":true,"schema":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."},"description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Outbound list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"}}}},"403":{"description":"Ship capability denied"},"404":{"description":"Route-driver job not found"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Warehouse Mobile"],"summary":"Stock one route package out","description":"Writes package and inventory audit data, then deletes the package grid inventory record. Repeated scans return already_outbound. A package on a distribution order of pre-advised carrier packages is not stocked out; its loading is stamped instead and the response carries kind=distribution (code already_outbound when it was loaded before).","parameters":[{"name":"routeDriver","in":"path","required":true,"schema":{"type":"integer","description":"Route driver. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."},"description":"Route driver. Path parameter identifying the resource in the URL.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileOperation"}}}},"responses":{"200":{"description":"Package stocked out or already outbound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Package stocked out successfully.","data":{"package_id":1001,"order_ref":"ORD-10001","duplicate":false,"progress":{"total":10,"remaining":5,"completed":5}}}}}},"403":{"description":"Ship capability denied"},"404":{"description":"Package is not assigned to this route-driver job"},"409":{"description":"Package is not in this warehouse"},"422":{"description":"Validation or stock-out error"}},"security":[{"bearerAuth":[]}]}},"/v1/apps/{appCode}/clients/{clientCode}/locker-locations":{"get":{"tags":["Platform Apps"],"summary":"List app-enabled SmartLocker locations","description":"Searches the selected Client’s complete active SmartLocker catalog with server-side text search, viewport bounds, service and availability filters, pagination and optional live locker-status/capacity summaries. Each item is an address location; locker_status_summary counts the actual locker devices below that location. The existing status field remains an aggregate for compatibility. Optional coordinates or an origin address sort results by distance; direct coordinates take precedence, while address fields use Superroute’s shared geocoding service.","operationId":"platformAppLockerLocations","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"latitude","in":"query","required":false,"description":"Origin latitude\n\n**Details:** Optional · Type `number`, format `double` · min `-90` · max `90`.","schema":{"type":"number","format":"double","minimum":-90,"maximum":90,"description":"Origin latitude\n\n**Details:** Optional · Type `number`, format `double` · min `-90` · max `90`."}},{"name":"longitude","in":"query","required":false,"description":"Origin longitude\n\n**Details:** Optional · Type `number`, format `double` · min `-180` · max `180`.","schema":{"type":"number","format":"double","minimum":-180,"maximum":180,"description":"Origin longitude\n\n**Details:** Optional · Type `number`, format `double` · min `-180` · max `180`."}},{"name":"origin_address_1","in":"query","required":false,"description":"Selected customer address line 1 used when coordinates are not supplied\n\n**Details:** Optional · Type `string` · maxLength `255`.","schema":{"type":"string","maxLength":255,"description":"Selected customer address line 1 used when coordinates are not supplied\n\n**Details:** Optional · Type `string` · maxLength `255`."}},{"name":"origin_address_2","in":"query","required":false,"description":"Selected customer address line 2\n\n**Details:** Optional · Type `string` · maxLength `255`.","schema":{"type":"string","maxLength":255,"description":"Selected customer address line 2\n\n**Details:** Optional · Type `string` · maxLength `255`."}},{"name":"origin_city","in":"query","required":false,"description":"Selected customer address city\n\n**Details:** Optional · Type `string` · maxLength `100`.","schema":{"type":"string","maxLength":100,"description":"Selected customer address city\n\n**Details:** Optional · Type `string` · maxLength `100`."}},{"name":"origin_province","in":"query","required":false,"description":"Selected customer address province or region\n\n**Details:** Optional · Type `string` · maxLength `100`.","schema":{"type":"string","maxLength":100,"description":"Selected customer address province or region\n\n**Details:** Optional · Type `string` · maxLength `100`."}},{"name":"origin_country","in":"query","required":false,"description":"Selected customer address country name or ISO-2 code\n\n**Details:** Optional · Type `string` · maxLength `100`.","schema":{"type":"string","maxLength":100,"description":"Selected customer address country name or ISO-2 code\n\n**Details:** Optional · Type `string` · maxLength `100`."}},{"name":"origin_postcode","in":"query","required":false,"description":"Selected customer address postcode\n\n**Details:** Optional · Type `string` · maxLength `50`.","schema":{"type":"string","maxLength":50,"description":"Selected customer address postcode\n\n**Details:** Optional · Type `string` · maxLength `50`."}},{"name":"search","in":"query","required":false,"description":"Location name, city or postcode\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","description":"Location name, city or postcode\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Optional · Type `string`."}},{"name":"limit","in":"query","required":false,"description":"Maximum locations\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `50`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Maximum locations\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `50`."}},{"name":"per_page","in":"query","required":false,"description":"Page size, up to 100\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `100`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Page size, up to 100\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `100`."}},{"name":"page","in":"query","required":false,"description":"One-based result page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`.","schema":{"type":"integer","minimum":1,"default":1,"description":"One-based result page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."}},{"name":"north","in":"query","required":false,"description":"Viewport north latitude\n\n**Details:** Optional · Type `number`, format `double` · min `-90` · max `90`.","schema":{"type":"number","format":"double","minimum":-90,"maximum":90,"description":"Viewport north latitude\n\n**Details:** Optional · Type `number`, format `double` · min `-90` · max `90`."}},{"name":"south","in":"query","required":false,"description":"Viewport south latitude\n\n**Details:** Optional · Type `number`, format `double` · min `-90` · max `90`.","schema":{"type":"number","format":"double","minimum":-90,"maximum":90,"description":"Viewport south latitude\n\n**Details:** Optional · Type `number`, format `double` · min `-90` · max `90`."}},{"name":"east","in":"query","required":false,"description":"Viewport east longitude\n\n**Details:** Optional · Type `number`, format `double` · min `-180` · max `180`.","schema":{"type":"number","format":"double","minimum":-180,"maximum":180,"description":"Viewport east longitude\n\n**Details:** Optional · Type `number`, format `double` · min `-180` · max `180`."}},{"name":"west","in":"query","required":false,"description":"Viewport west longitude\n\n**Details:** Optional · Type `number`, format `double` · min `-180` · max `180`.","schema":{"type":"number","format":"double","minimum":-180,"maximum":180,"description":"Viewport west longitude\n\n**Details:** Optional · Type `number`, format `double` · min `-180` · max `180`."}},{"name":"pickup","in":"query","required":false,"description":"Narrows the list to locations that support pickup. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`.","schema":{"type":"boolean","description":"Narrows the list to locations that support pickup. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`."}},{"name":"return","in":"query","required":false,"description":"Narrows the list to locations that accept returns. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`.","schema":{"type":"boolean","description":"Narrows the list to locations that accept returns. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`."}},{"name":"online","in":"query","required":false,"description":"Narrows the list to locations whose aggregated status is online. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`.","schema":{"type":"boolean","description":"Narrows the list to locations whose aggregated status is online. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`."}},{"name":"available","in":"query","required":false,"description":"Narrows the list to locations with at least one available compartment. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`.","schema":{"type":"boolean","description":"Narrows the list to locations with at least one available compartment. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`."}},{"name":"favorite","in":"query","required":false,"description":"Narrows the list to the signed-in customer’s favorites. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`.","schema":{"type":"boolean","description":"Narrows the list to the signed-in customer’s favorites. Only applied when true; false, empty or omitted returns the unfiltered catalog.\n\n**Details:** Optional · Type `boolean`."}},{"name":"include_status","in":"query","required":false,"description":"Include batched runtime status and capacity summaries\n\n**Details:** Optional · Type `boolean` · Default: `false`.","schema":{"type":"boolean","default":false,"description":"Include batched runtime status and capacity summaries\n\n**Details:** Optional · Type `boolean` · Default: `false`."}},{"name":"sort","in":"query","required":false,"description":"Sort by distance, name, favorite, recent or popular\n\nSort field or sort expression for the listing.\n\nAllowed values: `distance` · `name` · `favorite` · `recent` · `popular`.\n\n**Details:** Optional · Type `string` · Default: `distance`.","schema":{"type":"string","enum":["distance","name","favorite","recent","popular"],"default":"distance","description":"Sort by distance, name, favorite, recent or popular\n\nSort field or sort expression for the listing.\n\nAllowed values: `distance` · `name` · `favorite` · `recent` · `popular`.\n\n**Details:** Optional · Type `string` · Default: `distance`."}}],"responses":{"200":{"description":"Locker locations","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"items":[{"id":81,"name":"Downtown locker","address":"100 King Street","city":"Toronto","latitude":43.6487,"longitude":-79.3817,"distance_km":1.3,"locker_count":2,"services":{"pickup":true,"return":true},"status":"online","locker_status_summary":{"total":2,"online":1,"offline":1,"maintenance":0,"unknown":0},"capacity":{"estimated":true,"source":"superroute_records","total":24,"available":16,"occupied":6,"reserved":2,"unavailable":0,"unknown":0,"occupancy_percent":33.3},"is_favorite":true,"view_count":4,"last_viewed_at":"2026-07-25T00:30:00-04:00"}],"origin":{"latitude":43.65,"longitude":-79.38,"source":"geocoded_address"},"pagination":{"current_page":1,"per_page":20,"total":1,"last_page":1,"has_more":false}}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-locations/{locationId}":{"get":{"tags":["Platform Apps"],"summary":"Show a SmartLocker location","description":"Returns location details plus the distance from optional coordinates or an origin address, a status count for the actual locker devices below the address, live status, door summary, compartment dimensions, estimated occupancy and services. Capacity is grouped by physical compartment size and estimated from Superroute inventory, active grid allocations and provider parcel-presence data when available.","operationId":"platformAppLockerLocation","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"locationId","in":"path","required":true,"schema":{"type":"integer","description":"Location id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Location id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},{"name":"latitude","in":"query","required":false,"description":"Origin latitude\n\n**Details:** Optional · Type `number`, format `double` · min `-90` · max `90`.","schema":{"type":"number","format":"double","minimum":-90,"maximum":90,"description":"Origin latitude\n\n**Details:** Optional · Type `number`, format `double` · min `-90` · max `90`."}},{"name":"longitude","in":"query","required":false,"description":"Origin longitude\n\n**Details:** Optional · Type `number`, format `double` · min `-180` · max `180`.","schema":{"type":"number","format":"double","minimum":-180,"maximum":180,"description":"Origin longitude\n\n**Details:** Optional · Type `number`, format `double` · min `-180` · max `180`."}},{"name":"origin_address_1","in":"query","required":false,"description":"Selected customer address line 1 used when coordinates are not supplied\n\n**Details:** Optional · Type `string` · maxLength `255`.","schema":{"type":"string","maxLength":255,"description":"Selected customer address line 1 used when coordinates are not supplied\n\n**Details:** Optional · Type `string` · maxLength `255`."}},{"name":"origin_address_2","in":"query","required":false,"description":"Selected customer address line 2\n\n**Details:** Optional · Type `string` · maxLength `255`.","schema":{"type":"string","maxLength":255,"description":"Selected customer address line 2\n\n**Details:** Optional · Type `string` · maxLength `255`."}},{"name":"origin_city","in":"query","required":false,"description":"Selected customer address city\n\n**Details:** Optional · Type `string` · maxLength `100`.","schema":{"type":"string","maxLength":100,"description":"Selected customer address city\n\n**Details:** Optional · Type `string` · maxLength `100`."}},{"name":"origin_province","in":"query","required":false,"description":"Selected customer address province or region\n\n**Details:** Optional · Type `string` · maxLength `100`.","schema":{"type":"string","maxLength":100,"description":"Selected customer address province or region\n\n**Details:** Optional · Type `string` · maxLength `100`."}},{"name":"origin_country","in":"query","required":false,"description":"Selected customer address country name or ISO-2 code\n\n**Details:** Optional · Type `string` · maxLength `100`.","schema":{"type":"string","maxLength":100,"description":"Selected customer address country name or ISO-2 code\n\n**Details:** Optional · Type `string` · maxLength `100`."}},{"name":"origin_postcode","in":"query","required":false,"description":"Selected customer address postcode\n\n**Details:** Optional · Type `string` · maxLength `50`.","schema":{"type":"string","maxLength":50,"description":"Selected customer address postcode\n\n**Details:** Optional · Type `string` · maxLength `50`."}}],"responses":{"200":{"description":"Locker location detail","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"id":81,"name":"Downtown locker","distance_km":0.55,"status":"online","locker_status_summary":{"total":1,"online":1,"offline":0,"maintenance":0,"unknown":0},"lockers":[{"id":12,"name":"Main entrance locker","code":"LK-12","provider":"superbox","status":"online","compartment_count":24,"compartments":{"open":0,"closed":23,"fault":1,"unknown":0},"capacity":{"estimated":true,"source":"superroute_records","total":24,"available":16,"occupied":6,"reserved":1,"unavailable":1,"unknown":0,"occupancy_percent":29.2,"sizes":[{"length_mm":400,"width_mm":500,"height_mm":300,"total":12,"available":7,"occupied":4,"reserved":1,"unavailable":0,"unknown":0,"occupancy_percent":41.7}]},"features":["pickup_package","dropoff"]}]}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/home":{"get":{"tags":["Platform Apps"],"summary":"App home screen summary","description":"The app home screen in one call. Each section comes from the service behind its own list endpoint and has that endpoint's shape ({\"items\": [...]}; nearby_locker is one location). pickups: ready or partly collected; returns: approved, holding a code, not dropped off; luggage: current rentals; handovers: open deals (from the deals list, under items); nearby_locker: the nearest favourite, else the nearest (origin as on locker-locations: latitude/longitude or origin_*); recent_orders: the latest orders of every type. A section is null when the Client does not run its service, and null with its code in errors when its service refused or failed; one section failing never fails the call.","operationId":"platformAppHome","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"latitude","in":"query","required":false,"schema":{"type":"number","description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Optional · Type `number`.\n\n**Example:** `45.5017`.","examples":[45.5017]},"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Optional · Type `number`.\n\n**Example:** `45.5017`."},{"name":"longitude","in":"query","required":false,"schema":{"type":"number","description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Optional · Type `number`.\n\n**Example:** `-73.5673`.","examples":[-73.5673]},"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Optional · Type `number`.\n\n**Example:** `-73.5673`."}],"responses":{"200":{"description":"Home summary","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"pickups":{"items":[{"id":72,"delivery_number":"PLD-72","pickup_status":"ready","pickup_code":482913,"remaining_count":1}]},"returns":{"items":[{"id":12,"status":1,"return_code":"R7K2P9","custom_channel_name":"Amazon"}]},"luggage":null,"handovers":null,"nearby_locker":{"id":81,"name":"Downtown locker","distance_km":0.4,"is_favorite":true},"recent_orders":{"items":[{"type":"shipping","id":710,"status":2,"status_name":"Confirmed","reference":"SHIP-710"}]},"errors":[]}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"422":{"description":"Invalid origin"}}}},"/v1/apps/{appCode}/clients/{clientCode}/pickups":{"get":{"tags":["Platform Apps"],"summary":"List customer locker pickups","description":"Lists only PartnerLocker deliveries owned by the authenticated customer. Ownership is matched against the normalized, encrypted-recipient hash and selected Client.","operationId":"platformAppPickups","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"status","in":"query","required":false,"description":"Pickup status\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `not_ready` · `ready` · `partial` · `completed`.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","enum":["not_ready","ready","partial","completed"],"description":"Pickup status\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `not_ready` · `ready` · `partial` · `completed`.\n\n**Details:** Optional · Type `string`."}},{"name":"per_page","in":"query","required":false,"description":"Items per page\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `50`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Items per page\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `50`."}},{"name":"page","in":"query","required":false,"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`.","schema":{"type":"integer","minimum":1,"default":1,"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."}}],"responses":{"200":{"description":"Customer pickups","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"items":[{"id":72,"delivery_no":"PLD-01","pickup_status":"ready","pickup_code":482913,"pickup_qr_value":482913,"remote_open_available":true}],"pagination":{"current_page":1,"total":1,"has_more":false}}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/pickups/{deliveryId}":{"get":{"tags":["Platform Apps"],"summary":"Show a customer locker pickup","description":"Returns pickup code, QR payload, location, compartment and package state for a customer-owned delivery.","operationId":"platformAppPickup","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"integer","description":"Delivery id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Delivery id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Pickup detail","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"id":72,"pickup_status":"ready","pickup_code":482913,"location":{"id":81,"name":"Downtown locker"},"items":[{"id":1,"compartment_number":"A03","status":"ready"}]}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/pickups/{deliveryId}/collect":{"post":{"tags":["Platform Apps"],"summary":"Collect and remotely open a locker pickup","description":"Requires the effective locker.remote_open capability and explicit customer confirmation. Reuses WarehouseSelfPickup, SmartLocker door verification, compartment locks, inventory settlement and audit services.","operationId":"platformAppCollectPickup","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"integer","description":"Delivery id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Delivery id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_confirmed"],"properties":{"user_confirmed":{"type":"boolean","enum":[true],"description":"**Required.**\n\nAllowed values: `true`.\n\n**Details:** Type `boolean`."}}},"example":{"user_confirmed":true}}}},"responses":{"200":{"description":"Locker opened and pickup settled, possibly with a partial result","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"picked_up_count":1,"partial_success":false,"opened":[{"compartment_number":"A03"}],"failed":[]}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"409":{"description":"Pickup is already in progress or has no usable pickup code"},"422":{"description":"Invalid request"},"502":{"description":"The SmartLocker operation could not be confirmed"}}}},"/v1/apps/{appCode}/clients/{clientCode}/orders":{"get":{"tags":["Platform Apps"],"summary":"List app-enabled customer orders","description":"Combines existing customer shipping, storage and return records into a normalized read model. It does not create a second order table or ledger.","operationId":"platformAppOrders","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"type","in":"query","required":false,"description":"Order family\n\nType discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `all` · `shipping` · `storage` · `return`.\n\n**Details:** Optional · Type `string` · Default: `all`.","schema":{"type":"string","enum":["all","shipping","storage","return"],"default":"all","description":"Order family\n\nType discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `all` · `shipping` · `storage` · `return`.\n\n**Details:** Optional · Type `string` · Default: `all`."}},{"name":"status","in":"query","required":false,"description":"Existing service status\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","description":"Existing service status\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."}},{"name":"search","in":"query","required":false,"description":"Order ID or service-supported search term\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","description":"Order ID or service-supported search term\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Optional · Type `string`."}},{"name":"per_page","in":"query","required":false,"description":"Items per page\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `50`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Items per page\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `50`."}},{"name":"page","in":"query","required":false,"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`.","schema":{"type":"integer","minimum":1,"default":1,"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."}}],"responses":{"200":{"description":"Unified order list","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"items":[{"type":"shipping","id":710,"status":1,"reference":"TRACK-001","total":"18.20","currency":"CAD"}],"pagination":{"current_page":1,"total":1,"has_more":false},"creation_endpoints":{"shipping_services":"/v1/customer/shipping-orders/services","storage_config":"/v1/customer/storage-orders/config"}}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/orders/{orderType}/{orderId}":{"get":{"tags":["Platform Apps"],"summary":"Show an app-enabled customer order","description":"Routes to the existing shipping, storage or return service and preserves its source-of-truth detail payload.","operationId":"platformAppOrder","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"orderType","in":"path","required":true,"schema":{"type":"string","enum":["shipping","storage","return"],"description":"Order type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nOrder type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nAllowed values: `shipping` · `storage` · `return`.\n\n**Details:** Required · Type `string`."},"description":"Order type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nOrder type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nAllowed values: `shipping` · `storage` · `return`.\n\n**Details:** Required · Type `string`."},{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Order detail","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"type":"shipping","order":{"id":710,"tracking_number":"TRACK-001"}}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/returns/config":{"get":{"tags":["Platform Apps"],"summary":"Get App return configuration","description":"Returns the authenticated customer’s existing return-center eligibility, channels, Client-owned addresses, reasons and effective SmartLocker return methods. Each channel carries logo_url: the absolute URL of the logo the Client uploaded for it, or null. guide holds the Client's own wording for the app's return guide pages (platform, upload, confirm, success), each with title and description in the requested locale; null means the app shows its built-in text. Each channel also carries its step 2 of the return guide: return_code_upload_mode (1 image required, 2 optional, 3 not asked), upload_step {tab, title, description} in the requested locale (null where the channel left it empty) and reference_number_description.","operationId":"platformAppReturnConfiguration","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"locale","in":"query","required":false,"description":"Preferred response locale\n\nUI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","description":"Preferred response locale\n\nUI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`."}}],"responses":{"200":{"description":"Return configuration","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"return_types":[{"id":1,"code":"self_paid","name":"Self-paid return","requires_approval":false,"requires_channel":true,"requires_upload":false,"requires_channel_name":false,"requires_reference_number":false},{"id":2,"code":"free_return","name":"Free return","requires_approval":true,"requires_channel":true,"requires_upload":false,"requires_channel_name":false,"requires_reference_number":false},{"id":3,"code":"self_label","name":"Own shipping label","requires_approval":false,"requires_channel":false,"requires_upload":true,"requires_channel_name":true,"requires_reference_number":true},{"id":4,"code":"return_barcode","name":"Return barcode / QR code","requires_approval":false,"requires_channel":false,"requires_upload":true,"requires_channel_name":false,"requires_reference_number":false}],"contact":{"name":"Jane Doe","telephone":"+14165550123","email":"jane@example.com"},"requires_designated_address":true,"other_channel":{"available":true,"id":"other","allowed_return_types":[1],"pickup_address_mode":1,"requires_return_reason":true},"uploaded_label":{"pickup_address_mode":1,"accepted_extensions":["pdf","png","jpg","jpeg"],"max_size_kb":10240,"requires_return_reason":true},"channels":[{"id":4,"name":"Online","description":null,"logo_url":"https://admin.superroute.ca/storage/return-channels/online.png","reference_number_description":null,"return_code_upload_mode":1,"upload_step":{"tab":null,"title":null,"description":null},"reference_number_enabled":true,"reference_number_required":false,"return_methods":[1,2],"allowed_return_types":[1,2],"pickup_address_mode":1,"form":{"id":9,"name":"Return details","fields":[{"code":"order_ref","name":"Order reference","type":"text","required":true,"options":null,"max_files":null},{"code":"condition","name":"Item condition","type":"select","required":false,"options":[{"value":"new","name":"Unopened"},{"value":"used","name":"Opened"}],"max_files":null}]},"addresses":[{"id":6,"name":"Return warehouse"}],"requires_return_reason":true}],"guide":{"platform":{"title":"Where did you buy it?","description":null},"upload":{"title":null,"description":null},"confirm":{"title":null,"description":null},"success":{"title":null,"description":null}},"reasons":[{"id":3,"name":"Changed mind","requires_description":false}]}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/returns":{"get":{"tags":["Platform Apps"],"summary":"List customer return requests","description":"Lists existing ReturnRequest records for the authenticated customer and selected Client.","operationId":"platformAppReturns","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"status","in":"query","required":false,"description":"Existing return status\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `integer` · min `0` · max `5`.","schema":{"type":"integer","minimum":0,"maximum":5,"description":"Existing return status\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `integer` · min `0` · max `5`."}},{"name":"per_page","in":"query","required":false,"description":"Items per page\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `50`.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20,"description":"Items per page\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `20` · min `1` · max `50`."}},{"name":"page","in":"query","required":false,"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`.","schema":{"type":"integer","minimum":1,"default":1,"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1` · min `1`."}}],"responses":{"200":{"description":"Return requests","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"items":[{"id":901,"status":1,"status_name":"Approved","return_code":"RTN-TEST","can_cancel":true}],"pagination":{"current_page":1,"total":1,"has_more":false}}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request"}}},"post":{"tags":["Platform Apps"],"summary":"Create a customer return request","description":"Creates the normal ReturnRequest record using the selected Client’s existing return channel, address, reason, approval and unique-code behavior. return_channel_id: required for self-paid and free returns; for a return barcode (type 4) it is optional and names the platform the code was issued by — one of the customer's channels whose allowed_return_types include 4. With it, that channel decides whether a return reason and a pickup address are asked; without it, the customer's channels decide together as before. A return barcode naming a channel follows that channel: self_label_file is required, optional or ignored per its return_code_upload_mode, reference_number is kept (and required) when the channel asks for one, and form_data answers the channel's bound form.","operationId":"platformAppCreateReturn","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["return_type","pickup_name"],"description":"The same rules as the customer web form. return_type 1 (self-paid) and 2 (free return, awaits approval) name a return channel (return_channel_id + return_address_id), or, for type 1 only, return_channel_id \"other\" with custom_channel_name and a typed return_name / return_address_1 / return_city / return_country / return_postcode. Type 3 (own label) uploads the label and gives self_label_channel_name plus reference_number (the label's tracking number); type 4 (return barcode) uploads a file holding exactly one barcode / QR code; neither names a channel or address. The upload is a multipart self_label_file (PDF, PNG or JPG, 10 MB) or self_label_file_base64 + self_label_file_name in JSON. pickup_address_1, pickup_city, pickup_country and pickup_postcode are required when the applicable pickup_address_mode (the channel's, other_channel's, or uploaded_label's from the config call) is 1, optional when 2, ignored when 3. reference_number is required on a channel whose reference_number_required is true. form_data answers the channel's bound form, keyed by field code. pickup_telephone and email are both optional: an empty one falls back to the account's phone / email (see contact in the config call), and the call is refused with PHONE_OR_EMAIL_REQUIRED only when neither exists. Once the return holds a return code (on creation unless it awaits approval, else on approval) the customer is emailed the code, its QR code and a link to the return's status page, in the request's language, using the Client's own \"Return Confirmation\" email template or the built-in wording; data.confirmation_email in the response is the address it goes to, or null when none is sent.","properties":{"original_order_id":{"type":["integer","null"],"description":"Original order id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"return_type":{"type":"integer","enum":[1,2,3,4],"description":"**Required.**\n\n1 self-paid; 2 free return requiring approval; 3 own shipping label; 4 return barcode / QR code\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer`."},"return_channel_id":{"oneOf":[{"type":"integer","description":"Return channel id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},{"type":"string","enum":["other"],"description":"Allowed values: `other`.\n\n**Details:** Type `string`."}],"description":"Return channel id. Identifier referencing the related record.\n\n**Details:** Nullable."},"return_address_id":{"type":["integer","null"],"description":"Return address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"return_reason_id":{"type":["integer","null"],"description":"required unless the applicable requires_return_reason (the channel's, other_channel's or uploaded_label's from the config call) is false, in which case it is ignored\n\n**Details:** Type `integer` · Nullable."},"reference_number":{"type":["string","null"],"description":"Reference number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"custom_channel_name":{"type":["string","null"],"description":"\"other\" channel: the carrier's name\n\n**Details:** Type `string` · Nullable."},"return_name":{"type":["string","null"],"description":"Return name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"return_address_1":{"type":["string","null"],"description":"Return address 1. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"return_address_2":{"type":["string","null"],"description":"Return address 2. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"return_city":{"type":["string","null"],"description":"Return city. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"return_province":{"type":["string","null"],"description":"Return province. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"return_country":{"type":["string","null"],"description":"Return country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string` · Nullable."},"return_postcode":{"type":["string","null"],"description":"Return postcode. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"return_telephone":{"type":["string","null"],"description":"Return telephone. Phone number in local or E.164 form.\n\n**Details:** Type `string` · Nullable."},"return_lat":{"type":["number","null"],"description":"Return lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"return_lng":{"type":["number","null"],"description":"Return lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"self_label_channel_name":{"type":["string","null"],"description":"type 3: the carrier of the uploaded label\n\n**Details:** Type `string` · Nullable."},"self_label_file":{"type":["string","null"],"description":"multipart upload for types 3 and 4\n\n**Details:** Type `string`, format `binary` · Nullable.","contentMediaType":"application/octet-stream"},"self_label_file_base64":{"type":["string","null"],"description":"JSON alternative to self_label_file; bare base64 or a data URL\n\n**Details:** Type `string` · Nullable."},"self_label_file_name":{"type":["string","null"],"description":"file name carrying the extension, with self_label_file_base64\n\n**Details:** Type `string` · Nullable."},"form_data":{"type":["object","null"],"additionalProperties":true,"description":"Form data. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"pickup_name":{"type":"string","description":"**Required.**\n\nPickup name. Human-readable label.\n\n**Details:** Type `string`."},"pickup_address_1":{"type":["string","null"],"description":"Pickup address 1. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"pickup_address_2":{"type":["string","null"],"description":"Pickup address 2. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"pickup_city":{"type":["string","null"],"description":"Pickup city. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"pickup_province":{"type":["string","null"],"description":"Pickup province. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"pickup_country":{"type":["string","null"],"description":"Pickup country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string` · Nullable."},"pickup_postcode":{"type":["string","null"],"description":"Pickup postcode. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"pickup_lat":{"type":["number","null"],"description":"Pickup lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"pickup_lng":{"type":["number","null"],"description":"Pickup lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"pickup_telephone":{"type":["string","null"],"description":"Pickup telephone. Phone number in local or E.164 form.\n\n**Details:** Type `string` · Nullable."},"email":{"type":["string","null"],"format":"email","description":"Account email address.\n\n**Details:** Type `string`, format `email` · Nullable."},"return_description":{"type":["string","null"],"description":"Return description. Free-text note.\n\n**Details:** Type `string` · Nullable."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."}}},"examples":{"self_paid":{"summary":"Self-paid return through a listed channel","value":{"return_type":1,"return_channel_id":4,"return_address_id":6,"return_reason_id":3,"pickup_name":"MiBox Customer","pickup_address_1":"100 King Street West","pickup_city":"Toronto","pickup_province":"ON","pickup_country":"CA","pickup_postcode":"M5X 1A9","pickup_telephone":"+14165550123","return_description":"Package is unopened"}},"other_channel":{"summary":"Self-paid return through the \"other\" channel","value":{"return_type":1,"return_channel_id":"other","custom_channel_name":"Purolator","return_reason_id":3,"return_name":"Acme Returns","return_address_1":"200 Queen Street West","return_city":"Toronto","return_province":"ON","return_country":"CA","return_postcode":"M5H 2M9","pickup_name":"MiBox Customer","pickup_address_1":"100 King Street West","pickup_city":"Toronto","pickup_province":"ON","pickup_country":"CA","pickup_postcode":"M5X 1A9","pickup_telephone":"+14165550123"}},"self_label":{"summary":"Own shipping label (JSON upload)","value":{"return_type":3,"self_label_channel_name":"Canada Post","reference_number":"7012345678901234","return_reason_id":3,"self_label_file_name":"label.pdf","self_label_file_base64":"JVBERi0xLjQK...","pickup_name":"MiBox Customer","pickup_address_1":"100 King Street West","pickup_city":"Toronto","pickup_country":"CA","pickup_postcode":"M5X 1A9","pickup_telephone":"+14165550123"}},"return_barcode":{"summary":"Return barcode / QR code (JSON upload)","value":{"return_type":4,"return_reason_id":3,"self_label_file_name":"return-code.png","self_label_file_base64":"iVBORw0KGgo...","pickup_name":"MiBox Customer","pickup_telephone":"+14165550123"}}}},"multipart/form-data":{"schema":{"type":"object","required":["return_type","pickup_name"],"description":"The same rules as the customer web form. return_type 1 (self-paid) and 2 (free return, awaits approval) name a return channel (return_channel_id + return_address_id), or, for type 1 only, return_channel_id \"other\" with custom_channel_name and a typed return_name / return_address_1 / return_city / return_country / return_postcode. Type 3 (own label) uploads the label and gives self_label_channel_name plus reference_number (the label's tracking number); type 4 (return barcode) uploads a file holding exactly one barcode / QR code; neither names a channel or address. The upload is a multipart self_label_file (PDF, PNG or JPG, 10 MB) or self_label_file_base64 + self_label_file_name in JSON. pickup_address_1, pickup_city, pickup_country and pickup_postcode are required when the applicable pickup_address_mode (the channel's, other_channel's, or uploaded_label's from the config call) is 1, optional when 2, ignored when 3. reference_number is required on a channel whose reference_number_required is true. form_data answers the channel's bound form, keyed by field code. pickup_telephone and email are both optional: an empty one falls back to the account's phone / email (see contact in the config call), and the call is refused with PHONE_OR_EMAIL_REQUIRED only when neither exists. Once the return holds a return code (on creation unless it awaits approval, else on approval) the customer is emailed the code, its QR code and a link to the return's status page, in the request's language, using the Client's own \"Return Confirmation\" email template or the built-in wording; data.confirmation_email in the response is the address it goes to, or null when none is sent.","properties":{"original_order_id":{"type":["integer","null"],"description":"Original order id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"return_type":{"type":"integer","enum":[1,2,3,4],"description":"**Required.**\n\n1 self-paid; 2 free return requiring approval; 3 own shipping label; 4 return barcode / QR code\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer`."},"return_channel_id":{"oneOf":[{"type":"integer","description":"Return channel id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},{"type":"string","enum":["other"],"description":"Allowed values: `other`.\n\n**Details:** Type `string`."}],"description":"Return channel id. Identifier referencing the related record.\n\n**Details:** Nullable."},"return_address_id":{"type":["integer","null"],"description":"Return address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"return_reason_id":{"type":["integer","null"],"description":"required unless the applicable requires_return_reason (the channel's, other_channel's or uploaded_label's from the config call) is false, in which case it is ignored\n\n**Details:** Type `integer` · Nullable."},"reference_number":{"type":["string","null"],"description":"Reference number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"custom_channel_name":{"type":["string","null"],"description":"\"other\" channel: the carrier's name\n\n**Details:** Type `string` · Nullable."},"return_name":{"type":["string","null"],"description":"Return name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"return_address_1":{"type":["string","null"],"description":"Return address 1. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"return_address_2":{"type":["string","null"],"description":"Return address 2. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"return_city":{"type":["string","null"],"description":"Return city. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"return_province":{"type":["string","null"],"description":"Return province. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"return_country":{"type":["string","null"],"description":"Return country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string` · Nullable."},"return_postcode":{"type":["string","null"],"description":"Return postcode. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"return_telephone":{"type":["string","null"],"description":"Return telephone. Phone number in local or E.164 form.\n\n**Details:** Type `string` · Nullable."},"return_lat":{"type":["number","null"],"description":"Return lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"return_lng":{"type":["number","null"],"description":"Return lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"self_label_channel_name":{"type":["string","null"],"description":"type 3: the carrier of the uploaded label\n\n**Details:** Type `string` · Nullable."},"self_label_file":{"type":["string","null"],"format":"binary","description":"multipart upload for types 3 and 4\n\n**Details:** Type `string`, format `binary` · Nullable."},"self_label_file_base64":{"type":["string","null"],"description":"JSON alternative to self_label_file; bare base64 or a data URL\n\n**Details:** Type `string` · Nullable."},"self_label_file_name":{"type":["string","null"],"description":"file name carrying the extension, with self_label_file_base64\n\n**Details:** Type `string` · Nullable."},"form_data":{"type":["object","null"],"additionalProperties":true,"description":"Form data. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"pickup_name":{"type":"string","description":"**Required.**\n\nPickup name. Human-readable label.\n\n**Details:** Type `string`."},"pickup_address_1":{"type":["string","null"],"description":"Pickup address 1. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"pickup_address_2":{"type":["string","null"],"description":"Pickup address 2. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"pickup_city":{"type":["string","null"],"description":"Pickup city. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"pickup_province":{"type":["string","null"],"description":"Pickup province. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"pickup_country":{"type":["string","null"],"description":"Pickup country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string` · Nullable."},"pickup_postcode":{"type":["string","null"],"description":"Pickup postcode. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"pickup_lat":{"type":["number","null"],"description":"Pickup lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"pickup_lng":{"type":["number","null"],"description":"Pickup lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"pickup_telephone":{"type":["string","null"],"description":"Pickup telephone. Phone number in local or E.164 form.\n\n**Details:** Type `string` · Nullable."},"email":{"type":["string","null"],"format":"email","description":"Account email address.\n\n**Details:** Type `string`, format `email` · Nullable."},"return_description":{"type":["string","null"],"description":"Return description. Free-text note.\n\n**Details:** Type `string` · Nullable."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."}}}}}},"responses":{"201":{"description":"Return request created","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"Return request created.","data":{"id":901,"status":1,"return_code":"RTN-TEST","return_methods":[1,2],"return_type_code":"self_paid","return_type_name":"Self-paid return","custom_channel_name":null,"self_label_file_url":null,"return_code_value":null,"return_code_symbology":null,"form_data":null}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request. Besides Laravel validation errors, the service answers with a code: RETURN_TYPE_NOT_AVAILABLE, RETURN_CHANNEL_REQUIRED, RETURN_CHANNEL_NOT_AVAILABLE, RETURN_ADDRESS_NOT_AVAILABLE, OTHER_CHANNEL_SELF_PAID_ONLY, OTHER_CHANNEL_ADDRESS_REQUIRED, REFERENCE_NUMBER_REQUIRED, RETURN_FORM_INVALID, RETURN_REASON_REQUIRED, RETURN_REASON_NOT_AVAILABLE, RETURN_DESCRIPTION_REQUIRED, RETURN_ORDER_NOT_AVAILABLE, PHONE_OR_EMAIL_REQUIRED, PICKUP_ADDRESS_REQUIRED, SELF_LABEL_CHANNEL_NAME_REQUIRED, RETURN_LABEL_FILE_REQUIRED, RETURN_LABEL_FILE_INVALID, RETURN_BARCODE_UNREADABLE. Field-level detail, when there is any, is under errors.","content":{"application/json":{"example":{"result":false,"code":"RETURN_FORM_INVALID","message":"Some answers to the return channel form are missing or invalid.","errors":{"order_ref":"Order reference is required"}}}}}}}},"/v1/apps/{appCode}/clients/{clientCode}/returns/{returnId}":{"get":{"tags":["Platform Apps"],"summary":"Show a customer return request","description":"Returns an existing customer-owned ReturnRequest with pickup, destination, reason, channel and status details.","operationId":"platformAppReturn","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"returnId","in":"path","required":true,"schema":{"type":"integer","description":"Return id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Return id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Return detail","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"id":901,"status":1,"return_code":"RTN-TEST","destination":{"name":"Return warehouse"}}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/returns/{returnId}/cancel":{"post":{"tags":["Platform Apps"],"summary":"Cancel a customer return request","description":"Cancels an eligible pending or approved ReturnRequest that has not produced a return order, and appends the normal operation record.","operationId":"platformAppCancelReturn","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"returnId","in":"path","required":true,"schema":{"type":"integer","description":"Return id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Return id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Return cancelled","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"Return request cancelled.","data":{"id":901,"status":4,"can_cancel":false}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"409":{"description":"The return can no longer be cancelled"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/returns/{returnId}/confirmation-email":{"post":{"tags":["Platform Apps"],"summary":"Resend a return confirmation email","description":"Sends the return code, its QR code and the status link to the email the return was created with, again, in the request's language, using the Client's \"Return Confirmation\" email template or the built-in wording. At most once a minute per return; can_resend_confirmation on the return says whether it can be sent at all.","operationId":"platformAppResendReturnConfirmation","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"returnId","in":"path","required":true,"schema":{"type":"integer","description":"Return id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Return id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Confirmation email queued","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"The confirmation email has been sent again to jane@example.com.","data":{"confirmation_email":"jane@example.com"}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"The requested customer-owned resource was not found"},"422":{"description":"RETURN_EMAIL_NOT_AVAILABLE: no usable return code or email, or the Client switched the email off"},"429":{"description":"RETURN_EMAIL_RECENTLY_SENT: sent less than a minute ago"}}}},"/v1/apps/{appCode}/clients/{clientCode}/notifications":{"get":{"tags":["Platform Apps"],"summary":"List app notifications","description":"Returns only database notifications scoped to the authenticated user and selected App-Client assignment.","operationId":"platformAppNotifications","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"filter","in":"query","schema":{"type":"string","enum":["all","read","unread"],"description":"Allowed values: `all` · `read` · `unread`.\n\n**Details:** Type `string`."},"description":"Allowed values: `all` · `read` · `unread`.\n\n**Details:** Type `string`."},{"name":"category","in":"query","schema":{"type":"string","enum":["pickup","orders","returns","wallet","security"],"description":"Category filter. For wallet transactions: payment / credit / adjustment / charge / refund.\n\nCategory filter. For wallet transactions: payment / credit / adjustment / charge / refund.\n\nAllowed values: `pickup` · `orders` · `returns` · `wallet` · `security`.\n\n**Details:** Type `string`."},"description":"Category filter. For wallet transactions: payment / credit / adjustment / charge / refund.\n\nCategory filter. For wallet transactions: payment / credit / adjustment / charge / refund.\n\nAllowed values: `pickup` · `orders` · `returns` · `wallet` · `security`.\n\n**Details:** Type `string`."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · min `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · min `1`."},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · min `1` · max `50`."},"description":"Number of items returned per page.\n\n**Details:** Type `integer` · min `1` · max `50`."}],"responses":{"200":{"description":"App notification inbox","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/notifications/preferences":{"get":{"tags":["Platform Apps"],"summary":"Get notification preferences","operationId":"platformAppNotificationPreferences","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"responses":{"200":{"description":"Effective Client and customer notification preferences","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"}}},"put":{"tags":["Platform Apps"],"summary":"Update notification preferences","description":"Customers may opt down from the channels and categories enabled by the Client.","operationId":"platformAppUpdateNotificationPreferences","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channels","categories"],"properties":{"channels":{"type":"object","required":["in_app","push","email","sms"],"properties":{"in_app":{"type":"boolean","description":"**Required.**\n\nIn app. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"push":{"type":"boolean","description":"**Required.**\n\nPush. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"email":{"type":"boolean","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `boolean`."},"sms":{"type":"boolean","description":"**Required.**\n\nSms. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"**Required.**\n\nChannels. Field in the JSON request body.\n\n**Details:** Type `object`."},"categories":{"type":"object","required":["pickup","orders","returns","wallet","security"],"properties":{"pickup":{"type":"boolean","description":"**Required.**\n\nPickup. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"orders":{"type":"boolean","description":"**Required.**\n\nOrders. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"returns":{"type":"boolean","description":"**Required.**\n\nReturns. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"wallet":{"type":"boolean","description":"**Required.**\n\nWallet. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"security":{"type":"boolean","description":"**Required.**\n\nSecurity. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"**Required.**\n\nCategories. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"channels":{"in_app":true,"push":true,"email":false,"sms":false},"categories":{"pickup":true,"orders":true,"returns":true,"wallet":true,"security":true}}}}},"responses":{"200":{"description":"Updated effective preferences","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/notifications/realtime":{"get":{"tags":["Platform Apps"],"summary":"Get foreground notification MQTT credentials","description":"Returns short-lived MQTT-over-WebSocket credentials scoped to the authenticated app, Client assignment, customer and device. When realtime is unavailable, data.enabled is false and the app continues using API refresh.","operationId":"platformAppNotificationRealtime","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"device_id","in":"query","required":true,"schema":{"type":"string","maxLength":191,"description":"Stable device identifier from the mobile / kiosk client.\n\n**Details:** Required · Type `string` · maxLength `191`.\n\n**Example:** `ios-device-1`.","examples":["ios-device-1"]},"description":"Stable device identifier from the mobile / kiosk client.\n\n**Details:** Required · Type `string` · maxLength `191`.\n\n**Example:** `ios-device-1`."}],"responses":{"200":{"description":"Realtime availability and short-lived credentials","content":{"application/json":{"schema":{"type":"object","required":["result","data"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean","description":"**Required.**\n\nEnabled. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"mqtt_url":{"type":"string","format":"uri","description":"Mqtt url. Absolute or relative URL.\n\n**Details:** Type `string`, format `uri`."},"client_id":{"type":"string","description":"Client id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"username":{"type":"string","description":"Username. Human-readable label.\n\n**Details:** Type `string`."},"password":{"type":"string","description":"Account password (never logged or returned by the API).\n\n**Details:** Type `string`."},"topic":{"type":"string","description":"Topic. Field in the JSON request body.\n\n**Details:** Type `string`."},"qos":{"type":"integer","enum":[1],"description":"Allowed values: `1`.\n\n**Details:** Type `integer`."},"contract_version":{"type":"integer","enum":[1],"description":"Allowed values: `1`.\n\n**Details:** Type `integer`."},"expires_at":{"type":"string","format":"date-time","description":"Expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}},"description":"**Required.**\n\nData. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"enabled":true,"mqtt_url":"wss://api.superroute.ca/mqtt","client_id":"pa-a1b2c3d4e5f6g7h8i9j0","username":"app-1-assignment-10-user-100-device-a1b2c3d4e5f6g7h8","password":"short-lived-jwt","topic":"sr/apps/1/assignments/10/users/100/notifications","qos":1,"contract_version":1,"expires_at":"2026-07-25T18:00:00Z"}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/notifications/read-all":{"post":{"tags":["Platform Apps"],"summary":"Mark all app notifications as read","operationId":"platformAppMarkAllNotificationsRead","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"responses":{"200":{"description":"All scoped notifications marked read","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/notifications/{notificationId}/read":{"post":{"tags":["Platform Apps"],"summary":"Mark one app notification as read","operationId":"platformAppMarkNotificationRead","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"notificationId","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Notification id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `string`, format `uuid`."},"description":"Notification id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `string`, format `uuid`."}],"responses":{"200":{"description":"Notification marked read","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"404":{"description":"Notification not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/devices":{"post":{"tags":["Platform Apps"],"summary":"Register an app push device","description":"Stores an encrypted FCM token scoped to the user and App-Client assignment.","operationId":"platformAppRegisterDevice","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["push_token","device_id","device_platform"],"properties":{"push_token":{"type":"string","maxLength":4096,"description":"**Required.**\n\nPush token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string` · maxLength `4096`."},"device_id":{"type":"string","maxLength":191,"description":"**Required.**\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Type `string` · maxLength `191`."},"device_platform":{"type":"string","enum":["ios","android"],"description":"**Required.**\n\nNative client platform for app session / device binding.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Type `string`.","x-enumDescriptions":["Apple iOS","Google Android"]},"preferred_locale":{"type":"string","description":"Preferred locale. Field in the JSON request body.\n\n**Details:** Type `string`."},"app_version":{"type":"string","description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Type `string`."}}},"example":{"push_token":"fcm-token","device_id":"device-uuid","device_platform":"android","preferred_locale":"en","app_version":"1.0.0"}}}},"responses":{"200":{"description":"Push device registered","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/devices/{deviceId}":{"delete":{"tags":["Platform Apps"],"summary":"Revoke an app push device","operationId":"platformAppRevokeDevice","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Push device revoked","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/privacy":{"get":{"tags":["Platform Apps"],"summary":"Get app privacy overview","description":"Returns linked global identity providers, verified-phone state, legal links, data domains and pending deletion status. account.can_request_deletion is false for an account the app must not offer to close (staff and sub-accounts, which their owner closes); the account-deletion call refuses those with ACCOUNT_DELETION_NOT_AVAILABLE.","operationId":"platformAppPrivacy","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"responses":{"200":{"description":"Privacy overview","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/privacy/phone/request":{"post":{"tags":["Platform Apps"],"summary":"Request phone verification for the signed-in customer","description":"Creates a five-minute challenge using the Client's existing SMS configuration. The challenge is bound to the authenticated customer, App and Client.","operationId":"platformAppRequestPhoneVerification","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","maxLength":50,"description":"**Required.**\n\nPhone number used for OTP or contact.\n\n**Details:** Type `string` · maxLength `50`."},"locale":{"type":["string","null"],"description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Type `string` · Nullable."}}},"example":{"phone":"+1 416 555 0100","locale":"en"}}}},"responses":{"200":{"description":"Verification challenge created","content":{"application/json":{"example":{"result":true,"message":"A verification code was sent.","challenge_id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","phone_e164":"+14****0100","expires_in":300,"resend_after":60}}}},"401":{"description":"Authentication required"},"403":{"description":"App access or phone verification is disabled"},"409":{"description":"The customer already has a verified phone"},"422":{"description":"Invalid phone number"},"429":{"description":"Code request rate limit exceeded"},"503":{"description":"Client SMS service is unavailable"}}}},"/v1/apps/{appCode}/clients/{clientCode}/privacy/phone/verify":{"post":{"tags":["Platform Apps"],"summary":"Verify and link the signed-in customer's phone","description":"Consumes the customer-bound SMS challenge, creates the shared verified phone identity and updates the customer's primary telephone. A phone linked to another global account cannot be reused.","operationId":"platformAppVerifyPhone","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["challenge_id","code"],"properties":{"challenge_id":{"type":"string","minLength":64,"maxLength":64,"description":"**Required.**\n\nId of an outstanding verification challenge (OTP / registration).\n\n**Details:** Type `string` · minLength `64` · maxLength `64`."},"code":{"type":"string","pattern":"^[0-9]{6}$","description":"**Required.**\n\nStable machine code for this resource.\n\n**Details:** Type `string` · pattern `^[0-9]{6}$`."},"locale":{"type":["string","null"],"description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Type `string` · Nullable."}}},"example":{"challenge_id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","code":123456,"locale":"en"}}}},"responses":{"200":{"description":"Phone verified and linked","content":{"application/json":{"example":{"result":true,"message":"Your phone number was verified.","data":{"verified_phone":true,"phone_e164":"+14****0100"}}}}},"401":{"description":"Authentication required"},"403":{"description":"App access or phone verification is disabled"},"409":{"description":"Phone linked to another account or verification is already running"},"410":{"description":"Verification challenge expired or belongs to another account"},"422":{"description":"Invalid verification code"},"429":{"description":"Verification attempt limit exceeded"}}}},"/v1/apps/{appCode}/clients/{clientCode}/privacy/identities/google":{"post":{"tags":["Platform Apps"],"summary":"Link Google to the signed-in account","description":"Verifies the Google ID token against this App's configured audiences and creates the single global identity binding shared by Web and all apps.","operationId":"platformAppLinkGoogleIdentity","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id_token"],"properties":{"id_token":{"type":"string","maxLength":10000,"description":"**Required.**\n\nGoogle (or other IdP) ID token to exchange for a Superroute session.\n\n**Details:** Type `string` · maxLength `10000`."}}},"example":{"id_token":"verified-google-id-token"}}}},"responses":{"200":{"description":"Google identity linked","content":{"application/json":{"example":{"result":true,"data":{"provider":"google","linked":true}}}}},"401":{"description":"Authentication required or Google token invalid"},"403":{"description":"App access or Google sign-in is disabled"},"409":{"description":"Google identity conflicts with another account"},"422":{"description":"Invalid request"},"503":{"description":"Google sign-in is not configured"}}},"delete":{"tags":["Platform Apps"],"summary":"Unlink Google from the signed-in account","description":"Removes the single global Google identity binding shared by Web and all apps.","operationId":"platformAppUnlinkGoogleIdentity","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"responses":{"200":{"description":"Google identity unlinked","content":{"application/json":{"example":{"result":true,"data":{"provider":"google","linked":false}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"}}}},"/v1/apps/{appCode}/clients/{clientCode}/sessions":{"get":{"tags":["Platform Apps"],"summary":"List app sessions","operationId":"platformAppSessions","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"responses":{"200":{"description":"App sessions","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/sessions/{sessionId}":{"delete":{"tags":["Platform Apps"],"summary":"Revoke an app session","operationId":"platformAppRevokeSession","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"sessionId","in":"path","required":true,"schema":{"type":"integer","description":"Session id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Session id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Session revoked","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"404":{"description":"Session not found"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/clients/{clientCode}/privacy/account-deletion":{"post":{"tags":["Platform Apps"],"summary":"Request account closure","description":"Opens a reviewed account closure. The account is suspended immediately — sign-in and API access both stop and every live token is revoked — and the business is notified to approve or reject it. The customer is emailed a withdrawal link, and `withdrawal_token` is returned here once so the app can offer the same withdrawal itself.\n\nBackward compatible with the previous delete-request endpoint: the response keeps its shape, `status` keeps its original values (`pending`, `cancelled`, `completed`) and gained one new value (`rejected`), and the added fields are additive.","operationId":"platformAppRequestAccountDeletion","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirmation"],"properties":{"confirmation":{"type":"boolean","description":"**Required.**\n\nConfirmation. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"reason":{"type":"string","maxLength":500,"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · maxLength `500`."}}},"example":{"confirmation":true,"reason":"No longer using MiBox"}}}},"responses":{"200":{"description":"Deletion request accepted","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"202":{"description":"Closure request opened and the account suspended.","content":{"application/json":{"example":{"result":true,"message":"Account deletion was requested and all MiBox sessions were signed out.","data":{"id":42,"status":"pending","requested_at":"2026-09-05T10:00:00+00:00","cancelled_at":null,"completed_at":null,"handled_at":null,"reason":"Moving away","decision_reason":null,"requires_review":true,"withdrawal_token":"one-shot-withdrawal-token"}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"422":{"description":"Invalid request"},"409":{"description":"This account cannot request closure"}}},"delete":{"tags":["Platform Apps"],"summary":"Cancel app account deletion","operationId":"platformAppCancelAccountDeletion","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."}],"responses":{"200":{"description":"Pending deletion request cancelled","content":{"application/json":{"schema":{"type":"object","required":["result"],"properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"401":{"description":"Authentication required"},"403":{"description":"App or Client access is not allowed"},"404":{"description":"Pending request not found"},"422":{"description":"Invalid request"}},"description":"Withdraws the pending closure request while a session still exists. Once the request has taken the session away, use POST /v1/apps/{appCode}/account-closure/withdraw with the one-shot token instead."}},"/v1/apps/{appCode}/auth/google":{"post":{"tags":["Platform Apps"],"summary":"Sign in to an app with Google with automatic service-provider matching","description":"Verifies the global Google identity, derives the linked Customer service provider, verifies that provider has enabled this app and sign-in method, and returns the resolved Client context. No Client code is accepted.","operationId":"platformAppAutomaticGoogleLogin","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id_token","device_id","device_platform"],"properties":{"id_token":{"type":"string","description":"**Required.**\n\nGoogle (or other IdP) ID token to exchange for a Superroute session.\n\n**Details:** Type `string`."},"device_id":{"type":"string","maxLength":191,"description":"**Required.**\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Type `string` · maxLength `191`."},"device_platform":{"type":"string","enum":["ios","android"],"description":"**Required.**\n\nNative client platform for app session / device binding.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Type `string`.","x-enumDescriptions":["Apple iOS","Google Android"]},"app_version":{"type":["string","null"],"description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Type `string` · Nullable."}}},"example":{"id_token":"google-signed-id-token","device_id":"0f3d1c43-7f53-4c16-ae90-62a2bc921812","device_platform":"ios","app_version":"1.0.0"}}}},"responses":{"200":{"description":"App session issued","content":{"application/json":{"example":{"result":true,"access_token":"passport-access-token","token_type":"Bearer","expires_at":"2026-07-30 12:00:00","expires_timestamp":1785436800,"user":{"id":1001,"name":"MiBox Customer","email":"customer@example.com"},"app_context":{"app_code":"mibox","client_code":"n4x7q2g8w9r3k6m1p5t0z8ab","client_name":"Mili Express","configuration_version":3}}}}},"401":{"description":"Invalid Google ID token or identity"},"403":{"description":"The account is not an allowed Customer, the sign-in method is disabled, or the Customer service provider has not enabled this app","content":{"application/json":{"example":{"result":false,"code":"APP_NOT_ENABLED_FOR_PROVIDER","message":"Your service provider has not enabled this service."}}}},"409":{"description":"Registration is required or the Google binding conflicts"},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/auth/email":{"post":{"tags":["Platform Apps"],"summary":"Sign in to an app with email with automatic service-provider matching","description":"Authenticates the global Superroute account, derives its service provider from the Customer record, verifies that provider has enabled this app and sign-in method, and returns the resolved Client context. No Client code is accepted.","operationId":"platformAppAutomaticEmailLogin","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","device_id","device_platform"],"properties":{"email":{"type":"string","format":"email","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email`."},"password":{"type":"string","format":"password","description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string`, format `password`."},"device_id":{"type":"string","maxLength":191,"description":"**Required.**\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Type `string` · maxLength `191`."},"device_platform":{"type":"string","enum":["ios","android"],"description":"**Required.**\n\nNative client platform for app session / device binding.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Type `string`.","x-enumDescriptions":["Apple iOS","Google Android"]},"app_version":{"type":["string","null"],"description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Type `string` · Nullable."}}},"example":{"email":"customer@example.com","password":"account-password","device_id":"0f3d1c43-7f53-4c16-ae90-62a2bc921812","device_platform":"android","app_version":"1.0.0"}}}},"responses":{"200":{"description":"App session issued; response matches Google login"},"401":{"description":"Invalid credentials"},"403":{"description":"The account is not an allowed Customer, the sign-in method is disabled, or the Customer service provider has not enabled this app","content":{"application/json":{"example":{"result":false,"code":"APP_NOT_ENABLED_FOR_PROVIDER","message":"Your service provider has not enabled this service."}}}},"422":{"description":"Invalid request"}}}},"/v1/apps/{appCode}/auth/config":{"get":{"tags":["Platform Apps"],"summary":"Get public app login configuration","description":"Returns app-level identity-provider identifiers and available login methods before a Customer service provider is known. Client-specific enablement is enforced only after identity verification.","operationId":"platformAppLoginConfiguration","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."}],"responses":{"200":{"description":"Public app login configuration","content":{"application/json":{"example":{"result":true,"data":{"app":{"code":"mibox","name":"MiBox","type":"customer"},"methods":{"google":true,"email":true},"google":{"server_client_id":"shared-web-oauth-client.apps.googleusercontent.com"},"provider_resolution":"customer_membership","registration_requires_provider_context":true}}}}},"404":{"description":"The app is not active or does not exist"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-locations/{locationId}/preference":{"put":{"tags":["Platform Apps"],"summary":"Update a customer SmartLocker preference","description":"Idempotently favorites or unfavorites a SmartLocker and records customer visits for recent and frequently used location ranking. Preference data is scoped by App assignment, Client and customer.","operationId":"platformAppUpdateLockerPreference","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`.","examples":["n4x7q2g8w9r3k6m1p5t0z8ab"]},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`.\n\n**Example:** `n4x7q2g8w9r3k6m1p5t0z8ab`."},{"name":"locationId","in":"path","required":true,"schema":{"type":"integer","description":"Location id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`.\n\n**Example:** `81`.","examples":[81]},"description":"Location id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`.\n\n**Example:** `81`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"favorite":{"type":"boolean","description":"Favorite. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"viewed":{"type":"boolean","description":"Viewed. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"anyOf":[{"required":["favorite"]},{"required":["viewed"]}]},"example":{"favorite":true,"viewed":true}}}},"responses":{"200":{"description":"Updated locker preference","content":{"application/json":{"example":{"result":true,"data":{"location_id":81,"is_favorite":true,"view_count":4,"last_viewed_at":"2026-07-25T00:30:00-04:00"}}}}},"401":{"description":"Invalid or expired app session"},"403":{"description":"The App, Client, role or required capability is not available"},"404":{"description":"SmartLocker location not found"},"422":{"description":"Invalid request"},"503":{"description":"Preference storage migration is not available yet"}}}},"/v1/dispatch/overview":{"get":{"tags":["Dispatch"],"summary":"How the delivery day is going","description":"Signal counts by severity, driver states and stop progress for one day. predictive_signals_available is currently false and is stated explicitly: the board reports what has happened, not what is about to. See docs/LIVE-ETA-BACKTEST-FINDINGS.md.","operationId":"dispatchOverview","security":[{"passport":[]}],"parameters":[{"in":"query","name":"date","required":false,"schema":{"type":"string","format":"date","description":"The delivery day to read, as YYYY-MM-DD. Defaults to today. A date that cannot be read is refused with 422 rather than answered as an empty day, because an empty day reads as \"nothing was planned then\" and a dispatcher may act on it.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`.\n\n**Example:** `2026-07-25`.","examples":["2026-07-25"]},"description":"The delivery day to read, as YYYY-MM-DD. Defaults to today. A date that cannot be read is refused with 422 rather than answered as an empty day, because an empty day reads as \"nothing was planned then\" and a dispatcher may act on it.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`.\n\n**Example:** `2026-07-25`."}],"responses":{"200":{"description":"Overview of the day.","content":{"application/json":{"example":{"result":true,"data":{"date":"2026-07-25","signals":{"critical":64,"warning":31,"info":2},"drivers":{"total":43,"not_started":4,"in_progress":30,"finished":9},"stops":{"total":812,"delivered":517,"failed":64},"last_scan_at":"2026-07-25 09:15:02","predictive_signals_available":false}}}}},"422":{"description":"The date could not be read.","content":{"application/json":{"example":{"message":"The date must be in Y-m-d format.","errors":{"date":["The date must be in Y-m-d format."]}}}}}}}},"/v1/dispatch/signals":{"get":{"tags":["Dispatch"],"summary":"List dispatch signals, worst first","description":"Scoped to the caller's business, and to their territories when they are not a client admin. Business-wide signals such as the planning backlog carry no territory and are visible to everyone who can see the board. available_types lists only the types the scan actually produces.","operationId":"dispatchSignals","security":[{"passport":[]}],"parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["active","all","open","acked","resolved","ignored","expired"],"default":"active","description":"active means open or acknowledged — what still needs someone.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `all` · `open` · `acked` · `resolved` · `ignored` · `expired`.\n\n**Details:** Type `string` · Default: `active`."},"description":"active means open or acknowledged — what still needs someone.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `all` · `open` · `acked` · `resolved` · `ignored` · `expired`.\n\n**Details:** Type `string` · Default: `active`."},{"in":"query","name":"type","schema":{"type":"string","enum":["driver_not_started","driver_offline","delivery_failed","order_unassigned","geo_missing","abnormal_scan","third_party_alert","pod_anomaly"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\nType discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `driver_not_started` · `driver_offline` · `delivery_failed` · `order_unassigned` · `geo_missing` · `abnormal_scan` · `third_party_alert` · `pod_anomaly`.\n\n**Details:** Type `string`."},"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\nType discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `driver_not_started` · `driver_offline` · `delivery_failed` · `order_unassigned` · `geo_missing` · `abnormal_scan` · `third_party_alert` · `pod_anomaly`.\n\n**Details:** Type `string`."},{"in":"query","name":"severity","schema":{"type":"string","enum":["critical","warning","info"],"description":"Allowed values: `critical` · `warning` · `info`.\n\n**Details:** Type `string`."},"description":"Allowed values: `critical` · `warning` · `info`.\n\n**Details:** Type `string`."},{"in":"query","name":"driver_id","schema":{"type":"integer","description":"Driver id.\n\n**Details:** Type `integer`."},"description":"Driver id.\n\n**Details:** Type `integer`."},{"in":"query","name":"route_id","schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · min `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · min `1`."},{"in":"query","name":"per_page","schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `50` · min `1` · max `200`."},"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `50` · min `1` · max `200`."},{"in":"query","name":"suggested_replan","schema":{"type":"string","enum":["1","true"],"description":"When set, only signals where Live Replan is the recommended recovery (type in recovery set and route_id set).\n\nAllowed values: `1` · `true`.\n\n**Details:** Type `string`."},"description":"When set, only signals where Live Replan is the recommended recovery (type in recovery set and route_id set).\n\nAllowed values: `1` · `true`.\n\n**Details:** Type `string`."}],"responses":{"200":{"description":"Signals plus severity counts.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"type":{"type":"string","enum":["driver_not_started","driver_offline","delivery_failed","order_unassigned","geo_missing","abnormal_scan","third_party_alert","pod_anomaly"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `driver_not_started` · `driver_offline` · `delivery_failed` · `order_unassigned` · `geo_missing` · `abnormal_scan` · `third_party_alert` · `pod_anomaly`.\n\n**Details:** Type `string`."},"severity":{"type":"string","enum":["critical","warning","info"],"description":"Allowed values: `critical` · `warning` · `info`.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["open","acked","resolved","ignored","expired"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `open` · `acked` · `resolved` · `ignored` · `expired`.\n\n**Details:** Type `string`."},"subject_type":{"type":"string","enum":["route","driver","order"],"description":"Allowed values: `route` · `driver` · `order`.\n\n**Details:** Type `string`."},"subject_id":{"type":["integer","null"],"description":"Subject id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"route_id":{"type":["integer","null"],"description":"Route id (`routes.id`).\n\n**Details:** Type `integer` · Nullable."},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable."},"payload":{"type":"object","description":"Facts specific to the signal type, e.g. ref, stop_number, reason, late_minutes, silent_minutes, count.\n\n**Details:** Type `object`."},"resolve_reason":{"type":["string","null"],"description":"Resolve reason. Free-text note.\n\n**Details:** Type `string` · Nullable."},"first_seen_at":{"type":["string","null"],"description":"First seen at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"last_seen_at":{"type":["string","null"],"description":"Last seen at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"resolved_at":{"type":["string","null"],"description":"Resolved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"suggested_action":{"type":["string","null"],"description":"live_replan when recovery replan is recommended and route_id is set; otherwise null.\n\n**Details:** Type `string` · Nullable."},"replan_strategies":{"type":["array","null"],"items":{"type":"string","description":"Replan strategies. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Preferred strategy order for replan/generate when suggested_action is live_replan.\n\n**Details:** Type `array`, items `string` · Nullable."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"meta":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page. Field in the JSON request body.\n\n**Details:** Type `integer`."},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"last_page":{"type":"integer","description":"Last page. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Meta. Field in the JSON request body.\n\n**Details:** Type `object`."},"counts":{"type":"object","properties":{"critical":{"type":"integer","description":"Critical. Field in the JSON request body.\n\n**Details:** Type `integer`."},"warning":{"type":"integer","description":"Warning. Field in the JSON request body.\n\n**Details:** Type `integer`."},"info":{"type":"integer","description":"Info. Field in the JSON request body.\n\n**Details:** Type `integer`."},"replan_recommended":{"type":"integer","description":"Active signals recommended for Live Replan\n\n**Details:** Type `integer`."}},"description":"Counts. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"available_types":{"type":"array","items":{"type":"string","description":"Available types. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"description":"Available types. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `array`, items `string`."}}},"example":{"result":true,"data":[{"id":4821,"type":"delivery_failed","severity":"critical","status":"open","subject_type":"order","subject_id":918273,"route_id":23565,"driver_id":557,"order_id":918273,"territory_id":12,"payload":{"ref":"R164-260720-00014","stop_number":4,"reason":"Recipient not in"},"resolve_reason":null,"first_seen_at":"2026-07-25 01:56:04","last_seen_at":"2026-07-25 09:12:11","resolved_at":null,"suggested_action":"live_replan","replan_strategies":["rebalance","sla_protect","min_change"]}],"meta":{"current_page":1,"per_page":50,"total":97,"last_page":2},"counts":{"critical":64,"warning":31,"info":2,"replan_recommended":12},"available_types":["driver_not_started","driver_offline","delivery_failed","order_unassigned","geo_missing","abnormal_scan","third_party_alert","pod_anomaly"]}}}}}}},"/v1/dispatch/signals/{signalId}/acknowledge":{"post":{"tags":["Dispatch"],"summary":"Mark a signal as being worked on","description":"Acknowledging says \"I am on it\", not \"it is over\": the signal stays on the board and carries no resolution time.","operationId":"dispatchAcknowledgeSignal","security":[{"passport":[]}],"parameters":[{"in":"path","name":"signalId","required":true,"schema":{"type":"integer","description":"Signal id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Signal id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"reason":{"type":"string","maxLength":191,"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · maxLength `191`."}}}}}},"responses":{"200":{"description":"The updated signal.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"type":{"type":"string","enum":["driver_not_started","driver_offline","delivery_failed","order_unassigned","geo_missing","abnormal_scan","third_party_alert","pod_anomaly"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `driver_not_started` · `driver_offline` · `delivery_failed` · `order_unassigned` · `geo_missing` · `abnormal_scan` · `third_party_alert` · `pod_anomaly`.\n\n**Details:** Type `string`."},"severity":{"type":"string","enum":["critical","warning","info"],"description":"Allowed values: `critical` · `warning` · `info`.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["open","acked","resolved","ignored","expired"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `open` · `acked` · `resolved` · `ignored` · `expired`.\n\n**Details:** Type `string`."},"subject_type":{"type":"string","enum":["route","driver","order"],"description":"Allowed values: `route` · `driver` · `order`.\n\n**Details:** Type `string`."},"subject_id":{"type":["integer","null"],"description":"Subject id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"route_id":{"type":["integer","null"],"description":"Route id (`routes.id`).\n\n**Details:** Type `integer` · Nullable."},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable."},"payload":{"type":"object","description":"Facts specific to the signal type, e.g. ref, stop_number, reason, late_minutes, silent_minutes, count.\n\n**Details:** Type `object`."},"resolve_reason":{"type":["string","null"],"description":"Resolve reason. Free-text note.\n\n**Details:** Type `string` · Nullable."},"first_seen_at":{"type":["string","null"],"description":"First seen at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"last_seen_at":{"type":["string","null"],"description":"Last seen at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"resolved_at":{"type":["string","null"],"description":"Resolved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"id":4821,"type":"delivery_failed","severity":"critical","status":"open","subject_type":"order","subject_id":918273,"route_id":23565,"driver_id":557,"order_id":918273,"territory_id":12,"payload":{"ref":"R164-260720-00014","stop_number":4,"reason":"Recipient not in"},"resolve_reason":null,"first_seen_at":"2026-07-25 01:56:04","last_seen_at":"2026-07-25 09:12:11","resolved_at":null}}}}},"403":{"description":"Account may not use the dispatch API."},"404":{"description":"No such signal in the caller's business and territories."}}}},"/v1/dispatch/signals/{signalId}/resolve":{"post":{"tags":["Dispatch"],"summary":"Close a signal","description":"The condition has been dealt with.","operationId":"dispatchResolveSignal","security":[{"passport":[]}],"parameters":[{"in":"path","name":"signalId","required":true,"schema":{"type":"integer","description":"Signal id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Signal id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"reason":{"type":"string","maxLength":191,"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · maxLength `191`."}}}}}},"responses":{"200":{"description":"The updated signal.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"type":{"type":"string","enum":["driver_not_started","driver_offline","delivery_failed","order_unassigned","geo_missing","abnormal_scan","third_party_alert","pod_anomaly"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `driver_not_started` · `driver_offline` · `delivery_failed` · `order_unassigned` · `geo_missing` · `abnormal_scan` · `third_party_alert` · `pod_anomaly`.\n\n**Details:** Type `string`."},"severity":{"type":"string","enum":["critical","warning","info"],"description":"Allowed values: `critical` · `warning` · `info`.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["open","acked","resolved","ignored","expired"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `open` · `acked` · `resolved` · `ignored` · `expired`.\n\n**Details:** Type `string`."},"subject_type":{"type":"string","enum":["route","driver","order"],"description":"Allowed values: `route` · `driver` · `order`.\n\n**Details:** Type `string`."},"subject_id":{"type":["integer","null"],"description":"Subject id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"route_id":{"type":["integer","null"],"description":"Route id (`routes.id`).\n\n**Details:** Type `integer` · Nullable."},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable."},"payload":{"type":"object","description":"Facts specific to the signal type, e.g. ref, stop_number, reason, late_minutes, silent_minutes, count.\n\n**Details:** Type `object`."},"resolve_reason":{"type":["string","null"],"description":"Resolve reason. Free-text note.\n\n**Details:** Type `string` · Nullable."},"first_seen_at":{"type":["string","null"],"description":"First seen at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"last_seen_at":{"type":["string","null"],"description":"Last seen at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"resolved_at":{"type":["string","null"],"description":"Resolved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"id":4821,"type":"delivery_failed","severity":"critical","status":"open","subject_type":"order","subject_id":918273,"route_id":23565,"driver_id":557,"order_id":918273,"territory_id":12,"payload":{"ref":"R164-260720-00014","stop_number":4,"reason":"Recipient not in"},"resolve_reason":null,"first_seen_at":"2026-07-25 01:56:04","last_seen_at":"2026-07-25 09:12:11","resolved_at":null}}}}},"403":{"description":"Account may not use the dispatch API."},"404":{"description":"No such signal in the caller's business and territories."}}}},"/v1/dispatch/signals/{signalId}/ignore":{"post":{"tags":["Dispatch"],"summary":"Dismiss a signal, with a reason","description":"A reason is mandatory. \"Why did nobody act on this\" is the question asked after a bad day, and it cannot be answered later if nobody wrote it down.","operationId":"dispatchIgnoreSignal","security":[{"passport":[]}],"parameters":[{"in":"path","name":"signalId","required":true,"schema":{"type":"integer","description":"Signal id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Signal id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","maxLength":191,"description":"**Required.**\n\nHuman-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · maxLength `191`."}}}}}},"responses":{"200":{"description":"The updated signal.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"type":{"type":"string","enum":["driver_not_started","driver_offline","delivery_failed","order_unassigned","geo_missing","abnormal_scan","third_party_alert","pod_anomaly"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\nAllowed values: `driver_not_started` · `driver_offline` · `delivery_failed` · `order_unassigned` · `geo_missing` · `abnormal_scan` · `third_party_alert` · `pod_anomaly`.\n\n**Details:** Type `string`."},"severity":{"type":"string","enum":["critical","warning","info"],"description":"Allowed values: `critical` · `warning` · `info`.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["open","acked","resolved","ignored","expired"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `open` · `acked` · `resolved` · `ignored` · `expired`.\n\n**Details:** Type `string`."},"subject_type":{"type":"string","enum":["route","driver","order"],"description":"Allowed values: `route` · `driver` · `order`.\n\n**Details:** Type `string`."},"subject_id":{"type":["integer","null"],"description":"Subject id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"route_id":{"type":["integer","null"],"description":"Route id (`routes.id`).\n\n**Details:** Type `integer` · Nullable."},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable."},"payload":{"type":"object","description":"Facts specific to the signal type, e.g. ref, stop_number, reason, late_minutes, silent_minutes, count.\n\n**Details:** Type `object`."},"resolve_reason":{"type":["string","null"],"description":"Resolve reason. Free-text note.\n\n**Details:** Type `string` · Nullable."},"first_seen_at":{"type":["string","null"],"description":"First seen at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"last_seen_at":{"type":["string","null"],"description":"Last seen at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"resolved_at":{"type":["string","null"],"description":"Resolved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"id":4821,"type":"delivery_failed","severity":"critical","status":"open","subject_type":"order","subject_id":918273,"route_id":23565,"driver_id":557,"order_id":918273,"territory_id":12,"payload":{"ref":"R164-260720-00014","stop_number":4,"reason":"Recipient not in"},"resolve_reason":null,"first_seen_at":"2026-07-25 01:56:04","last_seen_at":"2026-07-25 09:12:11","resolved_at":null}}}}},"403":{"description":"Account may not use the dispatch API."},"404":{"description":"No such signal in the caller's business and territories."},"422":{"description":"A reason is required when ignoring a signal."}}}},"/v1/dispatch/live":{"get":{"tags":["Dispatch"],"summary":"Where the drivers who are out right now actually are","description":"Merges hardware trackers with the driver app's own points. position is null rather than a placeholder coordinate when a driver cannot be located, so nobody is drawn somewhere plausible but wrong. Points arrive when the driver records work rather than on a timer, so staleness_seconds is often large.","operationId":"dispatchLivePositions","security":[{"passport":[]}],"parameters":[{"in":"query","name":"date","schema":{"type":"string","format":"date","description":"The delivery day to read, as YYYY-MM-DD. Defaults to today. A date that cannot be read is refused with 422 rather than answered as an empty day, because an empty day reads as \"nothing was planned then\" and a dispatcher may act on it.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`.\n\n**Example:** `2026-07-25`.","examples":["2026-07-25"]},"description":"The delivery day to read, as YYYY-MM-DD. Defaults to today. A date that cannot be read is refused with 422 rather than answered as an empty day, because an empty day reads as \"nothing was planned then\" and a dispatcher may act on it.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`.\n\n**Example:** `2026-07-25`."}],"responses":{"200":{"description":"One entry per driver who has started a route.","content":{"application/json":{"example":{"result":true,"data":[{"driver_id":557,"driver_name":"Asim","driver_alias":"v1a","route_id":23565,"territory_id":12,"stops":20,"delivered":13,"position":{"lat":53.4808,"lng":-2.2426,"heading":41,"speed":12.5,"recorded_at":"2026-07-25 09:11:40","source":"app","staleness_seconds":322}}]}}}},"422":{"description":"The date could not be read.","content":{"application/json":{"example":{"message":"The date must be in Y-m-d format.","errors":{"date":["The date must be in Y-m-d format."]}}}}}}}},"/v1/dispatch/scan":{"post":{"tags":["Dispatch"],"summary":"Rebuild the board now","description":"Re-runs the signal scan instead of waiting for the schedule. Idempotent: a condition already on the board is refreshed rather than raised again, and a condition that has gone away is closed automatically.","operationId":"dispatchScanSignals","security":[{"passport":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"The delivery day to rebuild signals for. Defaults to today. Refused with 422 if it cannot be read, rather than scanning an empty day and reporting nothing found.\n\n**Details:** Type `string`, format `date`.\n\n**Example:** `2026-07-25`.","examples":["2026-07-25"]}}}}}},"responses":{"200":{"description":"What the scan changed.","content":{"application/json":{"example":{"result":true,"data":{"created":3,"updated":94,"expired":6}}}}},"422":{"description":"The date could not be read.","content":{"application/json":{"example":{"message":"The date must be in Y-m-d format.","errors":{"date":["The date must be in Y-m-d format."]}}}}}}}},"/v1/dispatch/realtime":{"get":{"tags":["Dispatch"],"summary":"Credentials for the dispatch live feed","description":"MQTT-over-WebSocket credentials scoped to the caller's business subtree, or enabled:false with a poll interval when push is unavailable. Territory scoping is NOT expressed in the broker ACL — payloads carry territory_id and the HTTP API remains the authority on what an account may act on.","operationId":"dispatchRealtime","security":[{"passport":[]}],"responses":{"200":{"description":"Credentials, or a polling fallback.","content":{"application/json":{"example":{"result":true,"data":{"enabled":true,"ws_url":"wss://api.example.com/mqtt","username":"dispatch-995-995","password":"<short-lived HS256 JWT, presented as the MQTT password>","topics":{"signals":"sr/dispatch/995/signals","positions":"sr/dispatch/995/positions","routes":"sr/dispatch/995/routes/+"}}}}}}}}},"/v1/dispatch/capabilities":{"get":{"tags":["Dispatch"],"summary":"What the signed-in account may do","description":"Permissions and territory scope, so a client can hide what it cannot do. The server still enforces each of these on every request — this is for the interface, not the gate. signal_types lists only the types the scan produces, so a filter never has an empty option behind it. Additive: `features` — the per-client planning switches (road_preferences, planning_rules, exclusion_zones, recurring_pickups, scheduled_planning); a client renders those blocks only when the switch is on.","operationId":"dispatchCapabilities","security":[{"passport":[]}],"responses":{"200":{"description":"Capabilities for this account.","content":{"application/json":{"example":{"result":true,"data":{"business_id":995,"group":"client","can_create_route":true,"is_broker":false,"sees_all_territories":true,"territory_ids":[],"signal_types":["driver_not_started","driver_offline","delivery_failed","order_unassigned","geo_missing","abnormal_scan","third_party_alert","pod_anomaly"],"features":{"road_preferences":false,"planning_rules":false,"exclusion_zones":false,"recurring_pickups":false,"scheduled_planning":false}}}}}}}}},"/v1/dispatch/routes":{"get":{"tags":["Dispatch"],"summary":"Routes for a delivery day, with progress","description":"One entry per driver on each route. Brokers see only their own routes. Times are the working window as configured and as actually worked.","operationId":"dispatchRoutes","security":[{"passport":[]}],"parameters":[{"in":"query","name":"date","schema":{"type":"string","format":"date","description":"The delivery day to read, as YYYY-MM-DD. Defaults to today. A date that cannot be read is refused with 422 rather than answered as an empty day, because an empty day reads as \"nothing was planned then\" and a dispatcher may act on it.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`.\n\n**Example:** `2026-07-25`.","examples":["2026-07-25"]},"description":"The delivery day to read, as YYYY-MM-DD. Defaults to today. A date that cannot be read is refused with 422 rather than answered as an empty day, because an empty day reads as \"nothing was planned then\" and a dispatcher may act on it.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`.\n\n**Example:** `2026-07-25`."}],"responses":{"200":{"description":"Routes with per-driver progress.","content":{"application/json":{"example":{"result":true,"data":[{"route_id":23565,"route_name":"A-260722-02","date":"2026-07-25","territory_id":12,"driver_id":557,"driver_name":"Asim","driver_alias":"v1a","driver_status":1,"planned_start":"08:00","planned_end":"18:00","actual_start":"07:52","actual_end":null,"stops":20,"delivered":13,"failed":1}]}}}},"422":{"description":"The date could not be read.","content":{"application/json":{"example":{"message":"The date must be in Y-m-d format.","errors":{"date":["The date must be in Y-m-d format."]}}}}}}}},"/v1/dispatch/route-list":{"get":{"tags":["Dispatch"],"summary":"The account's routes, one row per route","description":"The console's Route List: one row per route, with the vehicles on it and how the day is going. This is deliberately not the same list as /v1/dispatch/routes, which answers \"which drivers still have work\" and returns one row per driver — clients already read that one that way, so both are kept.\n\nOmitting date lists every route this account has, newest day first, exactly as the console's list behaves — a dispatcher opening it after midnight would otherwise find yesterday's work gone. Pass date to narrow to one day.\n\nAlways paged: the largest accounts have five figures of routes. meta carries the page, the true total and has_more, so a short answer is never mistaken for the whole list; per_page above the maximum is answered with the maximum rather than taken literally. A vehicle nobody has crewed yet is counted in awaiting_drivers rather than being hidden, and has_unassigned_stops says whether the route is carrying stops that belong to no vehicle. delivery_rate is a percentage of the route's own stops, so a route with no stops reads 0 rather than being left out.\n\nsearch narrows the whole account before the paging, not the page that came back: it matches a route's name, its number (exactly — 12 finds route 12, not 120), or the name or alias of a driver on it. meta.search echoes the term as the server understood it.\n\nplan_failure_code and plan_failure_reason (added after every earlier field) say why a route failed to plan: the stored code (no_orders, no_drivers, no_valid_coordinates, engine_error or no_routes) and its text in the language of the request. Both are null unless status is 4 (Failed).","operationId":"dispatchRouteList","security":[{"passport":[]}],"parameters":[{"in":"query","name":"date","schema":{"type":"string","format":"date","description":"Y-m-d. Omit for every route, newest first.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`."},"description":"Y-m-d. Omit for every route, newest first.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`."},{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1` · min `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer` · Default: `1` · min `1`."},{"in":"query","name":"per_page","schema":{"type":"integer","default":50,"maximum":200,"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `50` · max `200`."},"description":"Number of items returned per page.\n\n**Details:** Type `integer` · Default: `50` · max `200`."},{"in":"query","name":"search","schema":{"type":"string","maxLength":100,"description":"Route name, route number, or a driver's name. Applied before paging.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string` · maxLength `100`."},"description":"Route name, route number, or a driver's name. Applied before paging.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string` · maxLength `100`."}],"responses":{"200":{"description":"A page of routes, newest day first.","content":{"application/json":{"example":{"result":true,"data":[{"route_id":23565,"route_name":"A-260722-02","date":"2026-07-26","status":3,"status_label":"Success","territory_id":12,"territory_name":"Manchester Central","routing_engine":1,"broker_id":null,"operation_mode":1,"vehicles":4,"drivers":3,"awaiting_drivers":1,"driver_names":["S. Ahmed","J. Novak","P. Dubois"],"stops":62,"delivered":41,"failed":2,"remaining":19,"delivery_rate":66.13,"started":true,"driver_status_counts":[1,2,0],"has_unassigned_stops":false,"can_delete":false,"plan_failure_code":null,"plan_failure_reason":null},{"route_id":23571,"route_name":"A-260726-05","date":"2026-07-26","status":4,"status_label":"Failed","territory_id":12,"territory_name":"Manchester Central","routing_engine":1,"broker_id":null,"operation_mode":1,"vehicles":0,"drivers":0,"awaiting_drivers":0,"driver_names":[],"stops":0,"delivered":0,"failed":0,"remaining":0,"delivery_rate":0,"started":false,"driver_status_counts":[0,0,0],"has_unassigned_stops":false,"can_delete":false,"plan_failure_code":"no_drivers","plan_failure_reason":"This route has no drivers or vehicles to plan with. Its orders were returned to the order pool."}],"meta":{"date":null,"search":null,"page":1,"per_page":50,"total":407,"has_more":true}}}}},"401":{"description":"Not authenticated."}}}},"/v1/dispatch/routes/{routeId}":{"get":{"tags":["Dispatch"],"summary":"One route: its settings, the day's totals and its vehicles","description":"Everything the Route Edit screen needs in one answer: the route's own settings, totals for the whole route, and one entry per vehicle with that vehicle's own progress. A vehicle awaiting a driver reports awaiting_driver true and carries no driver_id or name rather than a placeholder. can_add_orders says whether the route's status still lets stops be put on it, so a client can hide the action instead of discovering the refusal. first_actual_start and last_actual_end come from the vehicles' own records, not from the plan — drivers routinely set off well away from the planned time. route.plan_failure_code and route.plan_failure_reason (added after every earlier field) say why the route failed to plan: the stored code and its text in the language of the request, both null unless route.status is 4 (Failed). route.plan_explanation (added after every earlier field, including the failure fields) is what the latest sRoute 2T planning run reported about the plan, or null when no sRoute 2T solve has explained it: planned_at, replan, solve_id, engine_version, score; score_breakdown (rule id => {hard, medium, soft}, e.g. travelTime, unassignedVisit, overtimeCost, familiarZone); routes (driver_id with that driver's overtime in seconds and score_breakdown); overtime_total (seconds); must_serve_unmet (order ids of must-serve stops left out); unassigned (order_id, reason such as time_window, shift_end or deferred, and the planner's explanation in English, at most 500 rows) and unassigned_total. The route carries pickup_route_template_id (the recurring pickup template it was generated from, null otherwise), allow_adhoc_pickups and allow_deliveries (its two switches, 1 for every other route).","operationId":"dispatchRouteDetail","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The route, its totals and its vehicles.","content":{"application/json":{"example":{"result":true,"data":{"route":{"route_id":23565,"route_name":"A-260722-02","date":"2026-07-26","status":3,"status_label":"Success","territory_id":12,"territory_name":"Manchester Central","routing_engine":1,"broker_id":null,"operation_mode":1,"notify_at":8,"notification_enabled":true,"advance_notification_enabled":false,"can_add_orders":true,"can_delete":false,"plan_failure_code":null,"plan_failure_reason":null,"plan_explanation":{"version":1,"planned_at":"2026-07-26T06:02:11+00:00","replan":false,"solve_id":"b3f0c2d1","engine_version":"1.0.10","score":"0hard/-1000medium/-7320soft","score_breakdown":{"unassignedVisit":{"hard":0,"medium":-1000,"soft":0},"travelTime":{"hard":0,"medium":0,"soft":-6120},"overtimeCost":{"hard":0,"medium":0,"soft":-1200}},"routes":[{"driver_id":557,"overtime":1200,"score_breakdown":{"travelTime":{"hard":0,"medium":0,"soft":-3010},"overtimeCost":{"hard":0,"medium":0,"soft":-1200}}}],"overtime_total":1200,"must_serve_unmet":[],"unassigned":[{"order_id":918273,"reason":"deferred","explanation":"Deferrable stop (sroute2t.deferrable): dropped first when not every stop fits. No vehicle reaches it within its time windows; closest: vehicle 557, 140 s late."}],"unassigned_total":1},"pickup_route_template_id":null,"allow_adhoc_pickups":1,"allow_deliveries":1},"stats":{"stops":62,"delivered":41,"failed":2,"remaining":19,"delivery_rate":66.13,"vehicles":4,"drivers":3,"awaiting_drivers":1,"started":true,"first_actual_start":"07:12","last_actual_end":null},"drivers":[{"slot_id":88411,"driver_id":557,"driver_name":"S. Ahmed","driver_alias":"SA","awaiting_driver":false,"broker_id":null,"vehicle_type":2,"capacity":120,"region_group_id":4,"region_group_name":"North","planned_start":"08:00","planned_end":"17:00","actual_start":"07:12","actual_end":null,"driver_status":1,"driver_status_label":"On Route","stops":20,"delivered":14,"failed":1,"remaining":5,"delivery_rate":70},{"slot_id":88412,"driver_id":null,"driver_name":null,"driver_alias":null,"awaiting_driver":true,"broker_id":null,"vehicle_type":1,"capacity":60,"region_group_id":null,"region_group_name":null,"planned_start":"08:00","planned_end":"17:00","actual_start":null,"actual_end":null,"driver_status":null,"driver_status_label":null,"stops":0,"delivered":0,"failed":0,"remaining":0,"delivery_rate":0}]}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account.","content":{"application/json":{"example":{"result":false,"message":"Route not found."}}}}}},"put":{"tags":["Dispatch"],"summary":"Change a route's own settings","description":"Renames a route, moves it to another date, changes its operation mode or its customer notifications. Only the fields actually sent are written, so a client may send one of them without having to echo the rest. A yes/no may be sent as true/false or as the words \"true\"/\"false\" — a client that spells its own switch out is no longer told its own value is not a boolean. Sending nothing to change is refused rather than reported as a save. Every accepted change is recorded against the route as an operation event, so a route that moved date says who moved it and what it read before.","operationId":"dispatchUpdateRoute","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":50,"description":"Human-readable name.\n\n**Details:** Type `string` · maxLength `50`."},"date":{"type":"string","format":"date","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`."},"operation_mode":{"type":"integer","description":"Operation mode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `integer`."},"notify_at":{"type":["integer","null"],"minimum":0,"maximum":23,"description":"Hour of the day the customer notification goes out.\n\n**Details:** Type `integer` · Nullable · min `0` · max `23`."},"notification_enabled":{"type":"boolean","description":"Notification enabled. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"advance_notification_enabled":{"type":"boolean","description":"Advance notification enabled. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}},"example":{"date":"2026-07-27","notification_enabled":true,"notify_at":8}}}},"responses":{"200":{"description":"The route's settings as they now read.","content":{"application/json":{"example":{"result":true,"data":{"route_id":23565,"route_name":"A-260722-02","date":"2026-07-27","status":3,"status_label":"Success","territory_id":12,"territory_name":"Manchester Central","routing_engine":1,"broker_id":null,"operation_mode":1,"notify_at":8,"notification_enabled":true,"advance_notification_enabled":false,"can_add_orders":true}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account.","content":{"application/json":{"example":{"result":false,"message":"Route not found."}}}},"422":{"description":"Nothing to change, or the route is past the point of being changed.","content":{"application/json":{"example":{"result":false,"message":"Nothing to change."}}}}}},"delete":{"tags":["Dispatch"],"summary":"Delete a cancelled route","description":"Removes the route for good, with its crewing rows and whatever stop rows the cancellation left behind.\n\nOnly a cancelled route may be deleted — the same rule the console's route list applies, and the reason for it is that cancelling is what unplans the stops and hands the orders back. A route in any other status is refused with `not_deletable` and its current status, so an interface can say why rather than offering a button that fails; `can_delete` on the route list and on the route detail says the same thing in advance. A contractor is answered 403, as for cancelling.\n\nThe deletion is written to the route history before the row goes, because afterwards there is no route left to ask about.","operationId":"dispatchDeleteRoute","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"example":{"result":true,"data":{"route_id":23565}}}}},"401":{"description":"Not authenticated."},"403":{"description":"A contractor cannot delete a route."},"404":{"description":"No such route, or it belongs to another account."},"422":{"description":"The route is not cancelled, so it may not be deleted.","content":{"application/json":{"example":{"result":false,"code":"not_deletable","message":"Only a cancelled route can be deleted. Cancel it first.","data":{"route_status":3}}}}}}}},"/v1/dispatch/routes/{routeId}/addable-orders":{"get":{"tags":["Dispatch"],"summary":"Orders that could still go on this route","description":"The day's orders that are not already planned and could be put on this route, so a dispatcher picks from a list instead of typing order numbers. Searchable by reference, order code, name, company or address. The list is capped; total and truncated always say whether you have all of it. A route whose status no longer takes stops answers 422 with code route_not_open rather than an empty list, so the reason is not mistaken for there being nothing to add.","operationId":"dispatchAddableOrders","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"search","schema":{"type":"string","description":"Matches reference, order code, name, company or address.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string`."},"description":"Matches reference, order code, name, company or address.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string`."},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `integer` · Default: `50` · max `200`."},"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `integer` · Default: `50` · max `200`."}],"responses":{"200":{"description":"Orders that can still be added, with the day they belong to.","content":{"application/json":{"example":{"result":true,"data":[{"order_id":918273,"ref":"R164-260720-00014","order_code":"SR918273","name":"A. Khan","company_name":null,"address":"12 Oxford Road Manchester M1 5QA","scheduled_date":"2026-07-26","order_type":"D","orders_status_id":2,"latitude":53.4749,"longitude":-2.2361}],"meta":{"date":"2026-07-26","total":37,"truncated":false}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account.","content":{"application/json":{"example":{"result":false,"message":"Route not found."}}}},"422":{"description":"The route's status no longer accepts stops.","content":{"application/json":{"example":{"result":false,"code":"route_not_open","message":"This route is not accepting more stops."}}}}}}},"/v1/dispatch/routes/{routeId}/add-orders":{"post":{"tags":["Dispatch"],"summary":"Put orders on one of the route's drivers","description":"Adds one or more of the day's orders to a named driver on the route. Orders that could not be added come back named in skipped rather than being counted as added, so a partial result is never read as a whole one — added and skipped together account for everything that was sent. A recurring pickup route only takes what its switches allow: an ad-hoc pickup while allow_adhoc_pickups is 0, or a delivery while allow_deliveries is 0, is refused with 422 and error_code recurring_pickups.adhoc_pickups_off or recurring_pickups.deliveries_off (the translated reason is in message / errors.order_ids).","operationId":"dispatchAddOrdersToRoute","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["driver_id","order_ids"],"properties":{"driver_id":{"type":"integer","description":"**Required.**\n\nA driver already on this route.\n\n**Details:** Type `integer`."},"order_ids":{"type":"array","minItems":1,"items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nList of Superroute order ids.\n\n**Details:** Type `array`, items `integer` · minItems `1`."},"after_stop_number":{"type":["integer","null"],"minimum":0,"description":"Insert the orders after this stop number on that driver's run instead of appending them at the end; 0 puts them first, and every stop behind the position is renumbered. Omit the field to append after the driver's last stop, which is what this endpoint has always done. This is the only way to add a stop to a route that is already being driven: once its orders leave 'waiting to plan' the route cannot be re-solved, so re-planning it would produce a route holding only the new stop. A position before a stop the driver has already attempted is refused.\n\n**Details:** Type `integer` · Nullable · min `0`."}}},"example":{"driver_id":557,"order_ids":[918273,918274],"after_stop_number":13}}}},"responses":{"200":{"description":"What was added, and what was not.","content":{"application/json":{"example":{"result":true,"data":{"route_id":23565,"driver_id":557,"added":[918273],"skipped":[918274],"inserted_after_stop_number":13}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account.","content":{"application/json":{"example":{"result":false,"message":"Route not found."}}}},"422":{"description":"The orders cannot go on this route.","content":{"application/json":{"example":{"result":false,"message":"Those orders cannot be added to this route.","errors":{"order_ids":"No orders given."}}}}}}}},"/v1/dispatch/routes/{routeId}/available-drivers":{"get":{"tags":["Dispatch"],"summary":"Drivers who could still be put on this route","description":"Active drivers of the business who are not already on the route. A route contracted to a broker offers only that broker's drivers, and a broker sees only his own whatever the route says — so a picker built from this can never offer someone the add would refuse. `brokers` maps broker id to name so the list can be grouped into own drivers and a contractor's.","operationId":"dispatchAvailableDrivers","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"search","schema":{"type":"string","description":"Matches alias, name or telephone.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string`."},"description":"Matches alias, name or telephone.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string`."},{"in":"query","name":"slot_id","schema":{"type":"integer","description":"Restrict to the drivers allowed on one reserved vehicle.\n\n**Details:** Type `integer`."},"description":"Restrict to the drivers allowed on one reserved vehicle.\n\n**Details:** Type `integer`."}],"responses":{"200":{"description":"Drivers still available, and the brokers they belong to.","content":{"application/json":{"example":{"result":true,"data":{"drivers":[{"driver_id":557,"alias":"SA","name":"S. Ahmed","telephone":"+441612345678","broker_id":null,"work_from":"08:00:00","work_to":"17:00:00","start_address_id":88,"end_address_id":88}],"brokers":{"412":"Northern Couriers Ltd"}}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account."}}}},"/v1/dispatch/routes/{routeId}/vehicles":{"post":{"tags":["Dispatch"],"summary":"Add vehicles to a route","description":"Puts one or more drivers on the route as new vehicles. This is not the same as assign-driver, which crews a vehicle the route already has — this is the second van, wanted after the plan was made. Every driver sent is dealt with on its own: the ones added come back in `added` with their new slot id, the ones passed over in `skipped` with why (`already_on_route`, `driver_not_found`, `driver_not_allowed_on_route`). Nothing added at all is a 422 rather than a success with an empty list.","operationId":"dispatchAddRouteVehicles","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["driver_ids","work_from","work_to"],"properties":{"driver_ids":{"type":"array","minItems":1,"items":{"type":"integer","description":"Driver ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nDriver ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer` · minItems `1`."},"work_from":{"type":"string","description":"**Required.**\n\nWork from. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `08:00:00`.","examples":["08:00:00"]},"work_to":{"type":"string","description":"**Required.**\n\nWork to. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `17:00:00`.","examples":["17:00:00"]},"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."}}},"example":{"driver_ids":[557,558],"work_from":"08:00:00","work_to":"17:00:00","start_address_id":88}}}},"responses":{"200":{"description":"What was added, and what was passed over.","content":{"application/json":{"example":{"result":true,"data":{"added":[{"slot_id":88413,"driver_id":557,"alias":"SA"}],"skipped":[{"driver_id":558,"reason":"already_on_route"}]}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account."},"422":{"description":"No vehicle could be added; every driver's reason is in skipped.","content":{"application/json":{"example":{"result":false,"message":"No vehicles were added.","data":{"added":[],"skipped":[{"driver_id":557,"reason":"already_on_route"}]}}}}}}}},"/v1/dispatch/routes/{routeId}/work-locations":{"get":{"tags":["Dispatch"],"summary":"Where a driver on this route may start and end","description":"The depots and work locations the account may use, grouped as the console groups them — its own warehouses first, then the ones it is allowed to use belonging to others.","operationId":"dispatchRouteWorkLocations","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Selectable locations, grouped.","content":{"application/json":{"example":{"result":true,"data":{"groups":[{"group":"My Warehouse","locations":[{"address_id":88,"name":"Manchester Depot","address":"Unit 4 Trafford Park, Manchester, M17 1AB"}]}]}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account."}}}},"/v1/dispatch/routes/{routeId}/drivers/{driverId}/locations":{"put":{"tags":["Dispatch"],"summary":"Move where one driver starts and ends the day","description":"Changes the vehicle's start and end location and then re-solves that driver's run, so the stop order matches the new endpoints rather than the old ones. Both blank is refused — the solver would have nothing to anchor either end of the day to. `reoptimised` says whether the re-solve actually ran: the locations are saved either way, and a solver that could not be reached is reported rather than being read as nothing having changed.","operationId":"dispatchUpdateDriverLocations","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"driverId","required":true,"schema":{"type":"integer","description":"Driver id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Driver id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."}}},"example":{"start_address_id":88,"end_address_id":91}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"example":{"result":true,"data":{"reoptimised":true}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or that driver is not on it."},"422":{"description":"Both locations were blank.","content":{"application/json":{"example":{"result":false,"code":"both_blank","message":"A start or an end location is required."}}}}}}},"/v1/dispatch/routes/{routeId}/drivers/{driverId}/load-plan":{"get":{"tags":["Dispatch"],"summary":"How to load one driver's van","description":"Advisory only, and never changes planning: the packages assigned to the vehicle's cargo zones in reverse delivery order, with total weight and volume and the warnings the console shows — a package too long for any zone, a zone over its volume, a load over the vehicle's weight. A driver whose vehicle has no cargo zones configured gets the plan with that stated rather than an error.","operationId":"dispatchRouteLoadPlan","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"driverId","required":true,"schema":{"type":"integer","description":"Driver id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Driver id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The advisory load plan.","content":{"application/json":{"example":{"result":true,"data":{"vehicle_model":"Mercedes Sprinter L2H2","total_weight":412.5,"total_volume":3.84,"warnings":[],"zones":[{"zone":"A","packages":[{"package_id":44821,"order_id":918273,"stop_number":20}]}]}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or that driver is not on it."}}}},"/v1/dispatch/routes/{routeId}/drivers/{driverId}/cancel-remaining":{"post":{"tags":["Dispatch"],"summary":"Cancel what a driver did not deliver","description":"Cancels delivery for every stop still outstanding on a finished run: each becomes Needs Rescheduling, and each gets its own operation event and a failure tracking event with the reason \"Delivery Cancelled\" — so the record reads the same as stops failed one at a time. Offered only once the run is closed; on a driver still working it is refused with `run_not_completed`, because cancelling under a working driver would race that driver's own app. A finished run with nothing outstanding answers `nothing_to_cancel` rather than reporting a successful cancellation of nothing.","operationId":"dispatchCancelRemainingStops","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"driverId","required":true,"schema":{"type":"integer","description":"Driver id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Driver id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The stops that were cancelled.","content":{"application/json":{"example":{"result":true,"data":{"cancelled":[918273,918274],"count":2}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account."},"422":{"description":"The run is not finished, or nothing on it is outstanding.","content":{"application/json":{"example":{"result":false,"code":"run_not_completed","message":"This is only available once the driver has finished the run."}}}}}}},"/v1/dispatch/routes/{routeId}/drivers/{driverId}/status":{"post":{"tags":["Dispatch"],"summary":"Set a driver's run status","description":"Moves one driver's run on a route between **0 waiting**, **1 on route** and **2 completed** — the same write the console's route list makes from its per-driver status dropdown, so a dispatcher on a phone and one at a desk cannot leave a run in two different states.\n\nThe stops still outstanding on that run move with it: back to *Already Planned* when the run returns to waiting, to *Out for Delivery* — or *Out for Pickup*, when the order started as a pickup — when it starts, and to *Needs Rescheduling* when it is marked finished. Stops already delivered or failed are never touched.\n\nBusinesses with strict start/end enabled have rules about when a run may start or end: everything scanned, and no other run already open for that driver. A refusal comes back as `strict_start` or `strict_end` carrying the sentence the console shows, which is meant to be displayed as it is rather than translated into a guess.","operationId":"dispatchSetDriverRunStatus","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"driverId","required":true,"schema":{"type":"integer","description":"Driver id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Driver id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"integer","enum":[0,1,2],"description":"**Required.**\n\n0 waiting, 1 on route, 2 completed.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `0` · `1` · `2`.\n\n**Details:** Type `integer`."}}},"example":{"status":1}}}},"responses":{"200":{"description":"The run's new state, and how many stops moved with it.","content":{"application/json":{"example":{"result":true,"data":{"route_id":23816,"driver_id":4471,"driver_status":1,"driver_status_label":"On Route","orders_updated":18}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, no such driver on it, or it belongs to another account."},"422":{"description":"An unknown status, or the business's strict start/end rules refused the change.","content":{"application/json":{"example":{"result":false,"code":"strict_start","message":"This driver has already started another route."}}}}}}},"/v1/dispatch/routes/{routeId}/approve":{"post":{"tags":["Dispatch"],"summary":"Approve a planned route","description":"Moves the route on and records against every stop that it is now planned. That event is what a recipient's tracking page reads, so approving from a phone writes exactly what approving from the console writes.","operationId":"dispatchApproveRoute","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Approved.","content":{"application/json":{"example":{"result":true}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account."},"422":{"description":"The route could not be approved."}}}},"/v1/dispatch/routes/{routeId}/cancel":{"post":{"tags":["Dispatch"],"summary":"Cancel a route, or some of its drivers","description":"Cancels the whole route, or only the drivers named in driver_ids. A route with stops already delivered is refused with `has_delivered_stops` rather than partly unwound. A contractor may crew and work his own vehicles but never cancel the route itself, and is answered 403.","operationId":"dispatchCancelRoute","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"driver_ids":{"type":"array","items":{"type":"integer","description":"Driver ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Cancel only these drivers' runs. Omit to cancel the route.\n\n**Details:** Type `array`, items `integer`."}}},"example":{"driver_ids":[557]}}}},"responses":{"200":{"description":"Cancelled.","content":{"application/json":{"example":{"result":true,"data":{"route_status":5,"remaining_stops":0}}}}},"401":{"description":"Not authenticated."},"403":{"description":"A contractor cannot cancel a route."},"404":{"description":"No such route, or it belongs to another account."},"422":{"description":"Already cancelled, or stops are already delivered.","content":{"application/json":{"example":{"result":false,"code":"has_delivered_stops","message":"This route cannot be cancelled because some stops are already delivered."}}}}}}},"/v1/dispatch/routes/{routeId}/replay":{"get":{"tags":["Dispatch"],"summary":"Replay the day a route was worked","description":"Each driver's recorded track, their stops and the events along the way, plus the window the whole day fits in as epoch milliseconds. Where a driver's phone never reported, `has_gps_data` is false and the track is built from the stops themselves — every point carries `source` (`gps`, `order` or `interpolated`) so a reconstructed track is never presented as a recorded one.","operationId":"dispatchRouteReplay","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"driver_id","schema":{"type":"integer","description":"One driver instead of every driver on the route.\n\nDriver id.\n\n**Details:** Type `integer`."},"description":"One driver instead of every driver on the route.\n\nDriver id.\n\n**Details:** Type `integer`."}],"responses":{"200":{"description":"The route, its drivers' tracks and the timeline.","content":{"application/json":{"example":{"result":true,"data":{"route":{"id":23565,"name":"A-260722-02","date":"2026-07-26"},"drivers":[{"id":557,"name":"S. Ahmed","alias":"SA","color":"#2f6fed","has_gps_data":true,"gps_points":[{"lat":53.4749,"lng":-2.2361,"timestamp":1785484800000,"time":"2026-07-26 08:00:00","source":"gps"}],"orders":[],"events":[]}],"timeline":{"start":1785484800000,"end":1785517200000}}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account."}}}},"/v1/dispatch/routes/{routeId}/reorder":{"post":{"tags":["Dispatch"],"summary":"Put a route's stops in a new order","description":"Submits the whole target state — every driver's ordered stop list — and queues the rebuild that applies it, the same job the console's route map uses. Stops dragged off the drivers travel in the same submission: `unassigned_order_ids` are left on no driver, and `new_order_queue_ids` are handed to the rebuild to place itself. Sending a queue clears the fixed sequences, because pinning each driver to what they already had would leave the queued stops nowhere to go. Omitting either list means this submission says nothing about that pool, which is not the same as sending an empty one. The reply carries a job id: a rebuild is queued work, and a client that assumes it has finished will show the old order.","operationId":"dispatchReorderStops","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["driver_orders"],"properties":{"driver_orders":{"type":"object","description":"**Required.**\n\nDriver id => ordered order ids.\n\n**Details:** Type `object`.","additionalProperties":{"type":"array","items":{"type":"integer","description":"Driver orders. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Driver orders. Element of a list or map in the request/response payload.\n\n**Details:** Type `array`, items `integer`."}},"unassigned_order_ids":{"type":"array","items":{"type":"integer","description":"Unassigned order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Unassigned order ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"new_order_queue_ids":{"type":"array","items":{"type":"integer","description":"New order queue ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"New order queue ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."}}},"example":{"driver_orders":{"557":[918273,918274]},"unassigned_order_ids":[918275],"new_order_queue_ids":[918276]}}}},"responses":{"200":{"description":"The rebuild was queued.","content":{"application/json":{"example":{"result":true,"data":{"job_id":"0b5b8b3e-6f6a-4a5a-9a0e-2f4d6d1f9c11"}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such route, or it belongs to another account."},"409":{"description":"Someone else is already rebuilding this route.","content":{"application/json":{"example":{"result":false,"message":"This route is already being rebuilt.","data":{"job_id":"0b5b8b3e-6f6a-4a5a-9a0e-2f4d6d1f9c11"}}}}}}}},"/v1/dispatch/orders/{orderId}/files":{"get":{"tags":["Dispatch"],"summary":"Photos and signatures captured at a stop","description":"The files a driver captured against the order. `distance` is how far in metres the phone was from the address when the file was taken, which is what tells a dispatcher whether a proof-of-delivery photo was taken at the door or from the road; it is null where the capture had no position.","operationId":"dispatchOrderFiles","security":[{"passport":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The order's files.","content":{"application/json":{"example":{"result":true,"data":{"total":1,"files":[{"id":9912,"path":"/storage/pod/918273-1.jpg","filename":"918273-1.jpg","file_type":"image/jpeg","latitude":"53.47488","longitude":"-2.23604","distance":11.42,"created_at":"2026-07-25 10:12:33"}]}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such order, or it belongs to another account."}}}},"/v1/dispatch/orders/{orderId}/coordinates":{"get":{"tags":["Dispatch"],"summary":"Where a stop sits on the map","description":"The delivery and pickup halves separately, so a wrong pin can be seen before it is moved. A pickup-type order has only the one address and it is the pickup one; an order with a separate origin keeps that origin's position rather than the delivery one.","operationId":"dispatchOrderCoordinates","security":[{"passport":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The order's positions.","content":{"application/json":{"example":{"result":true,"data":{"order_id":918273,"order_type":"D","delivery":{"lat":"53.474900","lng":"-2.236100","address":"12 Oxford Road , Manchester, Greater Manchester M1 5QA"},"pickup":null}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such order, or it belongs to another account."}}},"put":{"tags":["Dispatch"],"summary":"Correct a stop's position","description":"Moves the pin — typically from a phone standing in front of the address. Only the half actually sent is written, so correcting a delivery pin cannot blank a pickup one, and a value identical to what is stored is saved without being recorded as a correction. Every correction is logged, recorded as an operation event against the order, and the order's distance is re-derived in the background, because distance is what the order is priced and planned on. A coordinate off the earth is refused rather than stored.","operationId":"dispatchUpdateOrderCoordinates","security":[{"passport":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delivery_lat":{"type":["number","null"],"description":"Delivery lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"delivery_lng":{"type":["number","null"],"description":"Delivery lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"pickup_lat":{"type":["number","null"],"description":"Pickup lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"pickup_lng":{"type":["number","null"],"description":"Pickup lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"correction_source":{"type":"string","description":"Recorded on the correction, e.g. manual or dispatch_app.\n\n**Details:** Type `string`."}}},"example":{"delivery_lat":53.4751,"delivery_lng":-2.2359,"correction_source":"dispatch_app"}}}},"responses":{"200":{"description":"Which halves were changed.","content":{"application/json":{"example":{"result":true,"data":{"changed":["delivery"]}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such order, or it belongs to another account."},"422":{"description":"Nothing was sent, or a coordinate is not a place on earth.","content":{"application/json":{"example":{"result":false,"code":"invalid_delivery_coordinates","message":"Those coordinates are not a place on earth."}}}}}}},"/v1/dispatch/orders/{orderId}/operation-history":{"get":{"tags":["Dispatch"],"summary":"Everything that has happened to a stop","description":"The order's operation events in order, each with who did it, what the status read before and after, and any files captured at that moment — the same history the console's operation-history page shows.","operationId":"dispatchOrderOperationHistory","security":[{"passport":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The order's operation history.","content":{"application/json":{"example":{"result":true,"data":{"total":1,"events":[{"id":55123,"operation_category":3,"operation_type":3028,"operation_name":"dispatcher edited route settings","before_status":null,"after_status":null,"route_id":23565,"user_id":991,"user_name":"K. Byrne","created_at":"2026-07-25 09:14:02","files":[]}]}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such order, or it belongs to another account."}}}},"/v1/dispatch/routes/{routeId}/timeline":{"get":{"tags":["Dispatch"],"summary":"Stops on a route, planned order and what actually happened","description":"One driver's run on a route, or the whole route if no driver is named. completed_at comes from the delivery attempt's own record and matches what the route map on the web shows for the same stop. orders_routes holds one row per attempt, so a stop that failed here carries no completed_at even when the order was delivered on a later route; order_current_status is the order's status today, which for a re-planned stop will already read as delivered. planned_arrival is the plan's own wall clock and is deliberately not differenced against completed_at: drivers routinely set off well away from the planned time, so that gap measures when the driver started rather than whether the stop was late. It is null for routes planned before that seeding was fixed. A route worked by a whole fleet can hold hundreds of stops, so a single response is capped; total_stops and truncated always say whether you have the whole route.","operationId":"dispatchRouteTimeline","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"driver_id","schema":{"type":"integer","description":"Limit to one driver on a route worked by several.\n\nDriver id.\n\n**Details:** Type `integer`."},"description":"Limit to one driver on a route worked by several.\n\nDriver id.\n\n**Details:** Type `integer`."}],"responses":{"200":{"description":"Route header and its stops.","content":{"application/json":{"example":{"result":true,"data":{"route":{"route_id":23565,"route_name":"A-260722-02","date":"2026-07-25","territory_id":12,"status":3,"total_stops":20,"truncated":false,"stop_limit":500},"stops":[{"order_id":918273,"driver_id":557,"stop_number":4,"ref":"R164-260720-00014","recipient":"A. Khan","telephone":"+441612345678","address":"12 Oxford Road Manchester M1 5QA","latitude":53.4749,"longitude":-2.2361,"delivery_status":1,"failure_reason":null,"promised_from":"2026-07-25 09:00:00","promised_to":"2026-07-25 12:00:00","planned_arrival":"2026-07-25 09:47:00","completed_at":"2026-07-25 10:12:33","order_current_status":8}]}}}}},"404":{"description":"No such route in the caller's business and territories."}}}},"/v1/dispatch/routes/{routeId}/preview/move":{"post":{"tags":["Dispatch"],"summary":"What moving these stops would do","description":"Writes nothing. Only outstanding stops can move: one already delivered or failed keeps the record of that attempt, and re-planning a failed delivery creates a new one on a later route instead. Stops handed to a third-party carrier are refused too. Anything that cannot move comes back named in `skipped` rather than being dropped silently — a dispatcher pressing a button in a depot has no other way to notice. Apply runs the same loader again, so the two cannot drift.","operationId":"dispatchPreviewMove","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"The route the stops are on now.\n\nRoute id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"The route the stops are on now.\n\nRoute id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to_route_id","to_driver_id","order_ids"],"properties":{"to_route_id":{"type":"integer","description":"**Required.**\n\nRoute to move the stops onto. Must differ from the source route.\n\n**Details:** Type `integer`."},"to_driver_id":{"type":"integer","description":"**Required.**\n\nA driver already assigned to the destination route.\n\n**Details:** Type `integer`."},"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"minItems":1,"description":"**Required.**\n\nList of Superroute order ids.\n\n**Details:** Type `array`, items `integer` · minItems `1`."}}}}}},"responses":{"200":{"description":"What would move, and what would not.","content":{"application/json":{"example":{"result":true,"data":{"ok":true,"error":null,"from_route_id":23565,"to_route_id":23566,"to_driver_id":562,"moving":[{"order_id":918273,"ref":"R164-0014","recipient":"A. Khan","where":"Manchester M1 5QA"}],"skipped":[{"order_id":918280,"ref":"R164-0021","recipient":"J. Doe","where":"Manchester M2 3AB"}],"destination":{"driver_id":562,"driver_name":"Usman","driver_alias":"v2","driver_status":1,"stops":14,"outstanding":5}}}}}},"404":{"description":"A route outside the caller's business or territories."},"422":{"description":"The move was refused, or nothing in the list can move."}}}},"/v1/dispatch/routes/{routeId}/apply/move":{"post":{"tags":["Dispatch"],"summary":"Carry out a previewed move","description":"Held under the same lock the route optimiser uses, on both routes, so a move cannot land in the middle of a re-optimisation and two dispatchers cannot both act on a stale view. The stops are loaded again inside the lock, because one can be delivered between looking and pressing. Each moved stop is recorded on the order’s own operation-event timeline. Only outstanding stops can move: one already delivered or failed keeps the record of that attempt, and re-planning a failed delivery creates a new one on a later route instead. Stops handed to a third-party carrier are refused too. Anything that cannot move comes back named in `skipped` rather than being dropped silently — a dispatcher pressing a button in a depot has no other way to notice.","operationId":"dispatchApplyMove","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to_route_id","to_driver_id","order_ids"],"properties":{"to_route_id":{"type":"integer","description":"**Required.**\n\nRoute to move the stops onto. Must differ from the source route.\n\n**Details:** Type `integer`."},"to_driver_id":{"type":"integer","description":"**Required.**\n\nA driver already assigned to the destination route.\n\n**Details:** Type `integer`."},"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"minItems":1,"description":"**Required.**\n\nList of Superroute order ids.\n\n**Details:** Type `array`, items `integer` · minItems `1`."}}}}}},"responses":{"200":{"description":"What moved.","content":{"application/json":{"example":{"result":true,"data":{"ok":true,"error":null,"from_route_id":23565,"to_route_id":23566,"to_driver_id":562,"moving":[{"order_id":918273,"ref":"R164-0014","recipient":"A. Khan","where":"Manchester M1 5QA"}],"skipped":[{"order_id":918280,"ref":"R164-0021","recipient":"J. Doe","where":"Manchester M2 3AB"}],"destination":{"driver_id":562,"driver_name":"Usman","driver_alias":"v2","driver_status":1,"stops":14,"outstanding":5}}}}}},"404":{"description":"A route outside the caller's business or territories."},"409":{"description":"One of the routes is being changed by something else. Try again."},"422":{"description":"The move was refused, or nothing in the list can move."}}}},"/v1/dispatch/orders/{orderId}/notes":{"get":{"tags":["Dispatch"],"summary":"Notes on a stop","description":"Every note written against the order, oldest first. The matching POST on this path adds one.","operationId":"dispatchOrderNotes","security":[{"passport":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The order's notes.","content":{"application/json":{"example":{"result":true,"data":{"total":1,"notes":[{"id":771,"note":"Gate code 4471","user_name":"K. Byrne","created_at":"2026-07-25 16:04:11"}]}}}}},"401":{"description":"Not authenticated."},"404":{"description":"No such order, or it belongs to another account."}}},"post":{"tags":["Dispatch"],"summary":"Leave a note for the driver","description":"Written where the driver app already reads notes, so it reaches whoever is driving without anything new being built. Recorded on the order’s operation-event timeline alongside the route changes it explains.","operationId":"dispatchAddOrderNote","security":[{"passport":[]}],"parameters":[{"in":"path","name":"orderId","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["notes"],"properties":{"notes":{"type":"string","maxLength":2000,"description":"**Required.**\n\nFree-text notes.\n\n**Details:** Type `string` · maxLength `2000`."}}}}}},"responses":{"200":{"description":"The stored note.","content":{"application/json":{"example":{"result":true,"data":{"id":5512,"order_id":918273,"ref":"R164-0014","route_id":23565,"driver_id":557,"notes":"Buzzer is broken, call on arrival."}}}}},"404":{"description":"An order outside the caller's business or territories."},"422":{"description":"A note cannot be empty."}}}},"/v1/dispatch/routes/{routeId}/replacement-candidates":{"get":{"tags":["Dispatch"],"summary":"Drivers who could take over this route","description":"Anyone already on the route is left out, because the replace refuses them — offering a choice that will be rejected is worse than not offering it. Placeholder slots are left out too: they are vacancies, not people. A broker sees only their own drivers.\n\nOrdered by name, and nothing is suggested. Ranking was tried and removed: the only dimension the data supports is whether a driver is rostered that day, and being rostered does not mean being able to take more work. A hint that is right sometimes is worse than none, because it gets trusted.\n\nCapped and searchable by driver name or alias. total and truncated always say whether you have the whole roster; search re-queries the server rather than filtering what was already sent, because the driver being looked for may never have been in it.","operationId":"dispatchReplacementCandidates","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"search","schema":{"type":"string","maxLength":100,"description":"Driver name or alias.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string` · maxLength `100`."},"description":"Driver name or alias.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string` · maxLength `100`."},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":25,"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `integer` · Default: `25` · min `1` · max `200`."},"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Type `integer` · Default: `25` · min `1` · max `200`."}],"responses":{"200":{"description":"Eligible drivers.","content":{"application/json":{"example":{"result":true,"data":[{"driver_id":562,"driver_name":"Aisha","driver_alias":"v2","vehicle_type":"van"},{"driver_id":618,"driver_name":"Usman","driver_alias":"v8","vehicle_type":"van"}],"total":109,"truncated":true}}}}}}},"/v1/dispatch/routes/{routeId}/preview/replace-driver":{"post":{"tags":["Dispatch"],"summary":"What replacing this driver would do","description":"Writes nothing. Only outstanding stops change hands: what has already been delivered or failed stays recorded against the driver who did it. The incoming driver’s run is re-optimised, so their stop order will not be the old one — do not show the previous sequence afterwards.","operationId":"dispatchPreviewReplaceDriver","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from_driver_id","to_driver_id"],"properties":{"from_driver_id":{"type":"integer","description":"**Required.**\n\nThe driver currently on the route.\n\n**Details:** Type `integer`."},"to_driver_id":{"type":"integer","description":"**Required.**\n\nTheir replacement. Must not already be on this route.\n\n**Details:** Type `integer`."}}}}}},"responses":{"200":{"description":"What would change hands.","content":{"application/json":{"example":{"result":true,"data":{"ok":true,"error":null,"route_id":23565,"from_driver_id":557,"to_driver_id":562,"transferring":7,"already_delivered":12,"already_failed":1,"reoptimises":true}}}}},"404":{"description":"The route, the driver on it, or the replacement was not found for this caller."},"422":{"description":"The replacement is already on the route, or the driver has nothing outstanding left to hand over."}}}},"/v1/dispatch/routes/{routeId}/apply/replace-driver":{"post":{"tags":["Dispatch"],"summary":"Carry out a previewed replacement","description":"Held under the same lock the route optimiser uses: the replace re-optimises the incoming driver’s run, so doing it while another optimisation is in flight would leave two solvers writing the same stop numbers. Recorded on the route’s own operation-event timeline. Only outstanding stops change hands: what has already been delivered or failed stays recorded against the driver who did it. The incoming driver’s run is re-optimised, so their stop order will not be the old one — do not show the previous sequence afterwards.","operationId":"dispatchApplyReplaceDriver","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from_driver_id","to_driver_id"],"properties":{"from_driver_id":{"type":"integer","description":"**Required.**\n\nThe driver currently on the route.\n\n**Details:** Type `integer`."},"to_driver_id":{"type":"integer","description":"**Required.**\n\nTheir replacement. Must not already be on this route.\n\n**Details:** Type `integer`."}}}}}},"responses":{"200":{"description":"What changed hands.","content":{"application/json":{"example":{"result":true,"data":{"ok":true,"error":null,"route_id":23565,"from_driver_id":557,"to_driver_id":562,"transferring":7,"already_delivered":12,"already_failed":1,"reoptimises":true}}}}},"404":{"description":"The route, the driver on it, or the replacement was not found for this caller."},"409":{"description":"The route is being changed by something else. Try again."},"422":{"description":"The replacement is already on the route, or nothing is outstanding."}}}},"/v1/dispatch/routes/{routeId}/optimise":{"post":{"tags":["Dispatch"],"summary":"Re-solve a route’s remaining stops","description":"Queues the same run the web console queues, under the same lock, so the two cannot end up with different ideas about who is optimising what. There is no preview: the solver decides the order, and asking it twice would cost as much as doing it once. Poll /v1/dispatch/optimise-status/{jobId} for progress.","operationId":"dispatchOptimiseRoute","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"driver_id":{"type":"integer","description":"Limit to one driver on the route. Omit for all.\n\n**Details:** Type `integer`."}}}}}},"responses":{"200":{"description":"Queued.","content":{"application/json":{"example":{"result":true,"data":{"ok":true,"error":null,"route_id":23565,"driver_id":null,"job_id":"9f1c…","outstanding":7}}}}},"404":{"description":"A route outside the caller's business or territories."},"409":{"description":"That route is already being solved. The response names the run in flight."},"422":{"description":"Nothing outstanding to re-solve."}}}},"/v1/dispatch/routes/{routeId}/slots":{"get":{"tags":["Dispatch"],"summary":"The vehicles on a route and who is on each","description":"One entry per vehicle. A vehicle awaiting a driver reports awaiting_driver true and carries no driver_id or name. broker_id is the contractor the vehicle is reserved for. fleet_id, node and can_act (added after every earlier field) say where the vehicle sits in client -> contractor -> fleet: fleet_id is the fleet it is dispatched to, or the fleet of the driver on it (null at an owner directly); node is \"\" for the client, \"o:<contractor user id>\" (the contractor as a whole), \"d:<contractor user id>\" (its direct fleet: drivers in no fleet) or \"f:<fleet id>\"; can_act is whether the caller may crew or dispatch it (the client reaches every vehicle, a contractor those in his own branch, a fleet captain those dispatched to the fleets he leads).","operationId":"dispatchRouteSlots","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The route and its vehicles.","content":{"application/json":{"example":{"result":true,"data":{"route":{"route_id":23565,"name":"A-260722-02","date":"2026-07-26","status":3},"slots":[{"slot_id":88412,"driver_id":null,"driver_name":null,"awaiting_driver":true,"broker_id":41,"work_from":"08:00","work_end":"17:00","capacity":null,"vehicle_type":1,"stops":12,"delivered":0,"fleet_id":7,"node":"f:7","can_act":true}]}}}}},"404":{"description":"The route, or the vehicle on it, is not one the caller can reach.","content":{"application/json":{"example":{"result":false,"message":"Route not found."}}}}}}},"/v1/dispatch/routes/{routeId}/assign-driver":{"post":{"tags":["Dispatch"],"summary":"Crew one of a route's vehicles","description":"Puts a driver on a vehicle the route already has. The vehicle then sits at that driver's contractor and fleet. A vehicle takes only drivers of the node it sits at — a fleet: that fleet's drivers; a contractor's direct fleet: its drivers in no fleet; a contractor: any of its drivers; the client: any driver of the business — whoever asks (dispatch it first to give it to anyone else); a contractor only his own drivers on vehicles in his own branch; a fleet captain only his fleet's drivers on vehicles dispatched to his fleet. A wholly contracted route takes that contractor's drivers only. Answers with the route's vehicles as they now stand.","operationId":"dispatchAssignDriverToSlot","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slot_id","driver_id"],"properties":{"slot_id":{"type":"integer","description":"**Required.**\n\nSlot id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `88412`.","examples":[88412]},"driver_id":{"type":"integer","description":"**Required.**\n\nDriver id.\n\n**Details:** Type `integer`.\n\n**Example:** `558`.","examples":[558]}}}}}},"responses":{"200":{"description":"The route's vehicles after the change.","content":{"application/json":{"example":{"result":true,"data":{"route":{"route_id":23565,"name":"A-260722-02","date":"2026-07-26","status":3},"slots":[{"slot_id":88412,"driver_id":null,"driver_name":null,"awaiting_driver":true,"broker_id":41,"work_from":"08:00","work_end":"17:00","capacity":null,"vehicle_type":1,"stops":12,"delivered":0,"fleet_id":7,"node":"f:7","can_act":true}]}}}}},"404":{"description":"The route or the driver is not one the caller can reach.","content":{"application/json":{"example":{"result":false,"message":"Driver not found."}}}},"422":{"description":"The driver cannot take this vehicle.","content":{"application/json":{"example":{"result":false,"message":"This seat has not been dispatched to you"}}}}}}},"/v1/dispatch/routes/{routeId}/slots/{slotId}/dispatch":{"post":{"tags":["Dispatch"],"summary":"Dispatch one of a route's vehicles to the client's own drivers, a contractor or a fleet","description":"Moves a vehicle down client -> contractor -> fleet. node is \"\" for the client, \"o:<contractor user id>\" for a contractor as a whole (any of its fleets), \"d:<contractor user id>\" for that contractor's direct fleet (its drivers in no fleet), or \"f:<fleet id>\" for a fleet (a fleet brings its owner). The client may send a vehicle to any node; a contractor only within his own branch and never back to the client; a fleet captain may not dispatch. A driver already on the vehicle stays when he belongs to the new node, otherwise the vehicle goes back to awaiting a driver with its stops kept. A vehicle then takes only drivers of the node it sits at (a fleet: that fleet; a contractor's direct fleet: its drivers in no fleet; a contractor: any of its drivers; the client: any driver); to give it to anyone else, dispatch it there first. A started vehicle cannot move. The contractor and the fleet captain the vehicle moves to are notified. Answers with the vehicle's new node and the route's vehicles as they now stand.","operationId":"dispatchRouteSeat","security":[{"passport":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"path","name":"slotId","required":true,"schema":{"type":"integer","description":"Slot id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Slot id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["node"],"properties":{"node":{"type":"string","description":"**Required.**\n\n\"\" for the client, \"o:<contractor user id>\", \"d:<contractor user id>\" (that contractor's direct fleet) or \"f:<fleet id>\".\n\n**Details:** Type `string`.\n\n**Example:** `f:7`.","examples":["f:7"]}}}}}},"responses":{"200":{"description":"The vehicle's new node and the route's vehicles.","content":{"application/json":{"example":{"result":true,"node":"f:7","data":{"route":{"route_id":23565,"name":"A-260722-02","date":"2026-07-26","status":3},"slots":[{"slot_id":88412,"driver_id":null,"driver_name":null,"awaiting_driver":true,"broker_id":41,"work_from":"08:00","work_end":"17:00","capacity":null,"vehicle_type":1,"stops":12,"delivered":0,"fleet_id":7,"node":"f:7","can_act":true}]}}}}},"404":{"description":"The route, or the vehicle on it, is not one the caller can reach.","content":{"application/json":{"example":{"result":false,"message":"Route not found."}}}},"422":{"description":"code invalid_node: the node names nothing of this business. code refused: the caller may not move this vehicle there.","content":{"application/json":{"example":{"result":false,"code":"refused","message":"This seat has not been dispatched to you"}}}}}}},"/v1/dispatch/optimise-status/{jobId}":{"get":{"tags":["Dispatch"],"summary":"Progress of a queued optimisation","description":"Reads the same entry the web console polls. The entry ages out about an hour after the run, so a 404 here means \"finished a while ago\", not \"failed\".","operationId":"dispatchOptimiseStatus","security":[{"passport":[]}],"parameters":[{"in":"path","name":"jobId","required":true,"schema":{"type":"string","description":"Job id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `string`."},"description":"Job id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Current state.","content":{"application/json":{"example":{"result":true,"data":{"status":"pending","route_id":23565,"queued_at":"2026-07-25T14:03:11+00:00"}}}}},"404":{"description":"No such job, or its entry has expired."}}}},"/v1/dispatch/routes/{routeId}/replan/generate":{"post":{"tags":["Dispatch"],"summary":"Generate Live Replan multi-plans (what-if on sRoute 2 or sRoute 2T, no writes)","operationId":"dispatchReplanGenerate","parameters":[{"name":"routeId","in":"path","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Authorization. HTTP request header value.\n\n**Details:** Required · Type `string`."},"description":"Authorization. HTTP request header value.\n\n**Details:** Required · Type `string`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"driver_id":{"type":"integer","description":"Driver id.\n\n**Details:** Type `integer`."},"strategies":{"type":"array","items":{"type":"string","description":"Strategies. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Strategies. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"max_plans":{"type":"integer","default":3,"description":"Max plans. Field in the JSON request body.\n\n**Details:** Type `integer` · Default: `3`."},"engine":{"type":"string","enum":["sroute2","sroute2t","2","3"],"description":"Optional replan engine (slug or id). Must be allowed for the business; default is the route's engine when allowed, else the first allowed replan engine. Businesses with no replan engine allowed use sroute2.\n\nAllowed values: `sroute2` · `sroute2t` · `2` · `3`.\n\n**Details:** Type `string`.","examples":["sroute2t"]}}},"example":{"strategies":["min_change","rebalance","sla_protect"],"max_plans":3,"engine":"sroute2t"}}}},"responses":{"200":{"description":"session_id + ranked plans (each with plan_id, preset, label, score, summary, diff). Localised message on errors. The what-if carries the route's planning rules (solver_rules) the engine reads there: sRoute 2 1.2.15 or later receives solve_time, balance_strength, preferred drivers, keep assignments and driver breaks; sRoute 2T 1.0.8 or later receives the objective, solve_time, balance_strength, lateness tolerance, preferred drivers and driver breaks, from 1.0.10 overtime, VIP must-serve and deferrable stops, from 1.0.16 breaks_during_wait, and from 1.0.19 order_groups, goods_class_separation, deliveries_before_pickups, waiting_cost, use_all_vehicles and the drivers' vehicle model EV range. Additive: each unassigned_orders entry carries reason and reason_label when the engine named a reason (sRoute 2T 1.0.19 or later, sRoute 2 1.2.16 or later). Additive: a plan carries `meta` only when the engine reported one for it (sRoute 2 1.2.15 does when a rule was sent: ortools_time_limit, balance_strength, vehicle_preferences_applied).","content":{"application/json":{"example":{"result":true,"session_id":"uuid","route_id":123,"engine":"sroute2t","engine_id":3,"expires_in":600,"outstanding":42,"plans":[{"plan_id":"sla_protect","preset":"sla_protect","label":"Protect delivery windows","score":{"total":1200.5},"summary":{"moves":2,"unassigned":0},"diff":[],"explanations":["Strategy 'sla_protect'"],"meta":{"ortools_time_limit":5,"balance_strength":2,"vehicle_preferences_applied":true}}]}}}},"422":{"description":"nothing outstanding / solver unavailable / engine_not_allowed (the requested engine is not enabled for the business). Additive on every error: `messages` (object of reason key => localised reason; empty when there is nothing more to say than `message`).","content":{"application/json":{"example":{"result":false,"ok":false,"error":"engine_not_allowed","message":"This routing engine is not enabled for your business","messages":[]}}}},"503":{"description":"The chosen engine is allowed but not configured or not reachable (e.g. sroute2t_unavailable)","content":{"application/json":{"example":{"result":false,"ok":false,"error":"sroute2t_unavailable","engine":"sroute2t","engine_id":3,"message":"sRoute 2T routing service is not available"}}}}}}},"/v1/dispatch/replan/apply":{"post":{"tags":["Dispatch"],"summary":"Apply a Live Replan plan","operationId":"dispatchReplanApply","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Authorization. HTTP request header value.\n\n**Details:** Required · Type `string`."},"description":"Authorization. HTTP request header value.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id","plan_id"],"properties":{"session_id":{"type":"string","description":"**Required.**\n\nSession id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"plan_id":{"type":"string","description":"**Required.**\n\nPlan id. Identifier referencing the related record.\n\n**Details:** Type `string`."}}},"example":{"session_id":"uuid","plan_id":"min_change"}}}},"responses":{"200":{"description":"moves applied, optimise queued where needed; open replan-recommended signals on touched routes are auto-acknowledged. Reassignments between drivers of the same route are applied in one transaction: each stop moves to its new driver's run, every run the plan changed is put in the stop order the plan gives for that driver (stops that were not part of the plan keep their place) and renumbered without gaps, and the route is re-optimised. If the route's stops changed after the plan was generated, the moved stops are appended to their new runs instead. Additive: `messages` (object; empty on success unless a note applies, e.g. `stop_order` when the plan's stop order could not be used) and `stop_order` (`plan` = runs follow the plan's order, `appended` = moved stops were added at the end of their new runs, null = no same-route move).","content":{"application/json":{"example":{"result":true,"data":{"ok":true,"error":null,"mode":"reassign","plan_id":"sla_protect","preset":"sla_protect","engine":"sroute2t","engine_id":3,"message":"Plan applied","moved_orders":2,"acked_signals":{"count":1,"ids":[4821]},"applied_moves":[{"ok":true,"error":null,"from_route_id":27639,"to_route_id":27639,"to_driver_id":3,"from_driver_ids":[2],"moving":[{"order_id":912345,"ref":"SR-1001","recipient":"Jane Doe","where":"Toronto M5V 2T6"}],"skipped":[]}],"failed_moves":[],"optimise":[{"ok":true,"route_id":27639,"job_id":"9f1c…"}],"messages":[],"stop_order":"plan"}}}}},"422":{"description":"The plan could not be applied (`error`: rejected / nothing_to_move; cross_route_move when the plan would move stops to another route). Other refusals keep their status: failed / partial_apply 400, route_busy 409, session_expired / plan_not_found / not_found 404. Additive: `messages` is an object of reason key => localised reason text explaining why (for example a destination driver that is no longer on the route, or stops that have already been attempted); `failed_moves` carries the refused move with the same `messages`. Existing keys (`result`, `ok`, `error`, `mode`, `applied_moves`, `plan_id`, `engine`, `engine_id`, `message`) are unchanged.","content":{"application/json":{"example":{"result":false,"ok":false,"error":"rejected","mode":"reassign","plan_id":"rebalance","preset":"rebalance","engine":"sroute2","engine_id":2,"message":"The plan could not be applied","moved_orders":0,"applied_moves":[],"failed_moves":[{"ok":false,"error":"rejected","messages":{"to_driver_id.3":"Driver #3 is no longer on this route"}}],"messages":{"to_driver_id.3":"Driver #3 is no longer on this route"}}}}},"404":{"description":"session expired or not found (additive `messages`: {})"},"409":{"description":"route_busy: the route is being optimised or edited right now (additive `messages`: {})"}}}},"/v1/dispatch/devices":{"post":{"tags":["Dispatch"],"summary":"Register this phone for notifications","description":"Keyed on the app’s own install identifier, so signing in on a replacement handset does not leave the old one being notified. Re-registering updates the same row and revives a device that was signed out of. delivery_available says whether notifications can actually arrive for this platform, so a client does not wait for something that cannot come: iOS needs only a topic, because the APNs signing key is team-scoped and shared by every Superroute app; Android never registers here: that app keeps the dispatch live channel open with a foreground service and raises its own notifications from the board, so delivery_available is false for it by design rather than for want of a credential. Only critical signals reach a phone, and only ones newly raised — a phone that buzzes for everything gets silenced, and then the one that mattered is missed too. The payload carries only enough to open the right screen; the app fetches the detail from the API, which is the authority on what an account may see.","operationId":"dispatchRegisterDevice","security":[{"passport":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_id","platform"],"properties":{"device_id":{"type":"string","maxLength":128,"description":"**Required.**\n\nThe app’s own install identifier, stable across launches.\n\n**Details:** Type `string` · maxLength `128`."},"platform":{"type":"string","enum":["ios","android"],"description":"**Required.**\n\nClient platform for bootstrap / capability negotiation.\n\nEnum values (from deployed code):\n- `ios` — Apple iOS\n- `android` — Google Android\n\n**Details:** Type `string`.","x-enumDescriptions":["Apple iOS","Google Android"]},"push_token":{"type":["string","null"],"maxLength":512,"description":"Push token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string` · Nullable · maxLength `512`."},"locale":{"type":"string","maxLength":8,"description":"Superroute’s own code (en, chs, cht, …), not a locale code.\n\n**Details:** Type `string` · maxLength `8`."},"app_version":{"type":"string","maxLength":32,"description":"Semantic version of the client application (e.g. `1.0.0`).\n\n**Details:** Type `string` · maxLength `32`."},"enabled":{"type":"boolean","description":"Enabled. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."}}}}}},"responses":{"200":{"description":"Registered.","content":{"application/json":{"example":{"result":true,"data":{"device_id":"a3f1…","platform":"ios","enabled":true,"delivery_available":true}}}}}}}},"/v1/dispatch/devices/{deviceId}":{"delete":{"tags":["Dispatch"],"summary":"Stop notifying this phone","description":"Called on sign-out, so the next person to hold the handset is not notified. Idempotent — signing out twice is not an error worth showing anybody. The row is marked rather than deleted, so a device that comes back keeps its identity and \"why did this phone stop getting alerts\" stays answerable.","operationId":"dispatchRevokeDevice","security":[{"passport":[]}],"parameters":[{"in":"path","name":"deviceId","required":true,"schema":{"type":"string","description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."},"description":"Device id (locker, kiosk, edge device, etc.).\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Done.","content":{"application/json":{"example":{"result":true}}}}}}},"/v1/dispatch/plan/pool":{"get":{"tags":["Dispatch"],"security":[{"passport":[]}],"summary":"Orders available to plan for a day","operationId":"dispatchPlanPool","description":"The orders that could go on a route for a day. Exactly the pool the web planner draws from — status, scheduling, multi-leg transfer rules, broker rules, territory and the third-party guard all come from one shared service, so the two surfaces never disagree about what counts as unplanned.\n\nCapped at 300 rows; total and truncated always say whether you have the whole day, because a shortened list otherwise reads as a quiet one. latitude and longitude are null rather than 0 when an order has no coordinates — such an order cannot be planned, and 0,0 would draw it in the Gulf of Guinea. The build screen's filters may be sent to narrow it; all are optional and sending none returns the whole pool.","parameters":[{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Delivery day, YYYY-MM-DD. Defaults to today. Refused with 422 if unreadable.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`.\n\n**Example:** `2026-07-26`.","examples":["2026-07-26"]},"description":"Delivery day, YYYY-MM-DD. Defaults to today. Refused with 422 if unreadable.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`.\n\n**Example:** `2026-07-26`."},{"name":"territory_id","in":"query","required":false,"schema":{"type":"integer","description":"Narrow to one territory. A territory belonging to another business yields an empty pool, not an unfiltered one.\n\nTerritory id.\n\n**Details:** Optional · Type `integer`."},"description":"Narrow to one territory. A territory belonging to another business yields an empty pool, not an unfiltered one.\n\nTerritory id.\n\n**Details:** Optional · Type `integer`."},{"name":"include_transfer_orders","in":"query","required":false,"schema":{"type":"boolean","default":false,"description":"Let multi-leg transfer children into the pool. A no-op when the client’s multi-leg switch is off.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},"description":"Let multi-leg transfer children into the pool. A no-op when the client’s multi-leg switch is off.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},{"name":"order_batch[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Order batches. \"N/A\" selects the orders with no batch.\n\n**Details:** Optional · Type `array`, items `string`."},"description":"Order batches. \"N/A\" selects the orders with no batch.\n\n**Details:** Optional · Type `array`, items `string`."},{"name":"sorting_code[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Sorting codes. \"N/A\" selects the orders with none.\n\n**Details:** Optional · Type `array`, items `string`."},"description":"Sorting codes. \"N/A\" selects the orders with none.\n\n**Details:** Optional · Type `array`, items `string`."},{"name":"customers[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Customer ids. \"DIRECT\" selects the orders with no customer behind them.\n\n**Details:** Optional · Type `array`, items `string`."},"description":"Customer ids. \"DIRECT\" selects the orders with no customer behind them.\n\n**Details:** Optional · Type `array`, items `string`."},{"name":"channel[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer"},"description":"Order channel ids. -1 selects the orders with no channel.\n\n**Details:** Optional · Type `array`, items `integer`."},"description":"Order channel ids. -1 selects the orders with no channel.\n\n**Details:** Optional · Type `array`, items `integer`."},{"name":"order_type[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"D, DD, DP, P or P2P. Left out, the account's supported types apply.\n\n**Details:** Optional · Type `array`, items `string`."},"description":"D, DD, DP, P or P2P. Left out, the account's supported types apply.\n\n**Details:** Optional · Type `array`, items `string`."},{"name":"related_order_type[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Related order types. \"NONE\" selects the orders with none.\n\n**Details:** Optional · Type `array`, items `string`."},"description":"Related order types. \"NONE\" selects the orders with none.\n\n**Details:** Optional · Type `array`, items `string`."},{"name":"order_source[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer"},"description":"Order sources.\n\n**Details:** Optional · Type `array`, items `integer`."},"description":"Order sources.\n\n**Details:** Optional · Type `array`, items `integer`."},{"name":"regions[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer"},"description":"Region ids.\n\n**Details:** Optional · Type `array`, items `integer`."},"description":"Region ids.\n\n**Details:** Optional · Type `array`, items `integer`."},{"name":"signature_status","in":"query","required":false,"schema":{"type":"string","enum":["","0","1"],"description":"Empty for all, 1 for signature required, 0 for not.\n\nAllowed values: `` · `0` · `1`.\n\n**Details:** Optional · Type `string`."},"description":"Empty for all, 1 for signature required, 0 for not.\n\nAllowed values: `` · `0` · `1`.\n\n**Details:** Optional · Type `string`."},{"name":"warehouse_id","in":"query","required":false,"schema":{"type":"integer","description":"The depot this pool is being read for. Left out, the account's current work location is used, which is what this endpoint has always done. Send it once you are mid-plan and keep sending the same value: the work location is a single account-wide setting, so a colleague on the same account, another tab, or the console on a phone can move it between two of your calls, and the pool would then be filtered for a different warehouse than the one you started planning from. Within a territory, an order stocked at another warehouse is excluded, and when the warehouse is not the territory's default fulfillment center, so is every order with no warehouse of its own.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"description":"The depot this pool is being read for. Left out, the account's current work location is used, which is what this endpoint has always done. Send it once you are mid-plan and keep sending the same value: the work location is a single account-wide setting, so a colleague on the same account, another tab, or the console on a phone can move it between two of your calls, and the pool would then be filtered for a different warehouse than the one you started planning from. Within a territory, an order stocked at another warehouse is excluded, and when the warehouse is not the territory's default fulfillment center, so is every order with no warehouse of its own.\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"The pool.","content":{"application/json":{"example":{"result":true,"data":{"data":[{"order_id":8815234,"ref":"SR-90231","latitude":45.5019,"longitude":-73.5674,"address":"1200 Rue Sainte-Catherine Montreal QC H3B","order_type":"D","orders_status_id":2}],"total":412,"truncated":true,"date":"2026-07-26"}}}}},"422":{"description":"The date could not be read.","content":{"application/json":{"example":{"message":"The date must be in Y-m-d format.","errors":{"date":["The date must be in Y-m-d format."]}}}}}}}},"/v1/dispatch/plan/anchors":{"post":{"tags":["Dispatch"],"security":[{"passport":[]}],"summary":"Assign orders to anchors without writing anything","operationId":"dispatchPlanAnchors","description":"Where each order lands, given where the anchors were dropped. One anchor is one vehicle. Writes nothing: a dispatcher moves anchors around many times before accepting an arrangement, and none of those attempts should leave a trace.\n\nOrders are scoped to the caller’s business inside the planner, so ids from elsewhere simply do not appear in the result. At most 40 anchors.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["anchors","order_ids"],"properties":{"anchors":{"type":"array","maxItems":40,"items":{"type":"object","required":["lat","lng"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"**Required.**\n\nLat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · min `-90` · max `90`."},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"**Required.**\n\nLng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · min `-180` · max `180`."},"driver_id":{"type":["integer","null"],"description":"The driver this anchor stands for, if chosen yet.\n\n**Details:** Type `integer` · Nullable."}}},"description":"**Required.**\n\nAnchors. Field in the JSON request body.\n\n**Details:** Type `array`, items `object` · maxItems `40`."},"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nList of Superroute order ids.\n\n**Details:** Type `array`, items `integer`."},"settings":{"type":"object","description":"Planner settings — service_time, capacity, routing_engine and the rest, as the web planner sends them. Optional road preferences, applied to every anchor unless the anchor sets its own: route_avoid_tolls, route_avoid_highways and route_avoid_ferries (0 or 1), route_optimize_for (0 fastest, 1 balanced, 2 shortest), route_residential_access (0 free, 1 moderate, 2 standard, 3 avoid). Optional exclusion_zone_set_ids (array of set ids) with route_date (Y-m-d, default today): the plan drives around the zones in force that day, orders inside a zone come back unassigned, and sets that cannot be used or zones over the limit answer 422. Road preferences apply only while Road Preferences is enabled for the account, and exclusion zones only while Exclusion Zones is enabled (both set by the platform administrator); otherwise those settings are ignored.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"Where each order landed.","content":{"application/json":{"example":{"result":true,"data":{"assignments":[{"anchor_index":0,"driver_id":3312,"order_ids":[8815234,8815240],"distance":18400,"duration":3120}],"unassigned":[8815299]}}}}},"422":{"description":"Too many anchors, or an anchor off the globe."}}}},"/v1/dispatch/plan/build":{"post":{"tags":["Dispatch"],"security":[{"passport":[]}],"summary":"Build a route from an accepted plan","operationId":"dispatchPlanBuild","description":"Accept a plan and build the route it describes. One route holding every anchor, which is how this planner has always worked and what the web screen produces from the same input — the two share the builder.\n\nAn order belonging to another business is refused with 422 rather than dropped: a plan that quietly loses a stop is worse than one that fails, because the dispatcher believes the order is on a van. Recorded on the same operation-event timeline as every other dispatcher action.\n\nAdditive since 8.57.20: `settings` accepts `name` and `serve_time` (the names every other build uses; `route_name_prefix` and `service_time` still win when both arrive — `service_time` is minutes), `exclusion_zone_set_ids`, `solver_rules` and `route_advanced_options`, persisted as the magnetic screen's save persists them. The response additionally carries `rule_notices`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assignments","route_date"],"properties":{"assignments":{"type":"array","items":{"type":"object","required":["order_ids"],"properties":{"driver_id":{"type":["integer","null"],"description":"No driver means no driver row is created; the anchor still contributes its stops.\n\n**Details:** Type `integer` · Nullable."},"order_ids":{"type":"array","items":{"type":"integer","description":"Order ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nList of Superroute order ids.\n\n**Details:** Type `array`, items `integer`."},"start_time":{"type":"string","description":"Start time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`.\n\n**Example:** `09:00`.","examples":["09:00"]},"end_time":{"type":"string","description":"End time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`.\n\n**Example:** `17:00`.","examples":["17:00"]},"step_details":{"type":"object","description":"Per-order distance and duration from the anchors call, keyed by order id.\n\n**Details:** Type `object`."}}},"description":"**Required.**\n\nAssignments. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"route_date":{"type":"string","format":"date","description":"**Required.**\n\nRoute date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date`.\n\n**Example:** `2026-07-26`.","examples":["2026-07-26"]},"settings":{"type":"object","description":"The route settings: name (or route_name_prefix), serve_time (or service_time, minutes), pickup_time, package_pickup_time, package_processing_time, capacity_type, load_check, routing_engine, balance_mode, balance_tolerance, balance_preset, the route-level road preferences, solver_rules, route_advanced_options, exclusion_zone_set_ids, pending.\n\n**Details:** Type `object`."},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable."}}}}}},"responses":{"200":{"description":"The route that was built.","content":{"application/json":{"example":{"result":true,"data":{"route_id":23988,"drivers":4,"orders":96,"rule_notices":[]}}}}},"422":{"description":"An order that may not be planned, or an account that may not create routes.","content":{"application/json":{"example":{"result":false,"message":"Orders not belonging to this business cannot be planned: 771203"}}}}}}},"/v1/dispatch/plan/drivers":{"get":{"tags":["Dispatch"],"security":[{"passport":[]}],"summary":"Drivers available to take an anchor","operationId":"dispatchPlanDrivers","description":"Drivers who could take an anchor. The same rules the web planner applies: the account’s business, active users only, the chosen territory (drivers with no territory are always included), and a broker sees only their own.\n\nPlaceholder slots are left out and no pool is grown — creating rows to answer a read is a side effect a GET should not have, and leaving an anchor without a driver already means \"decide later\".\n\nOrdered by name and searchable by name or alias; nothing is suggested. Whether a driver is free today is not something this data can answer, and a hint that is right sometimes is worse than none because it gets trusted. total and truncated always say whether you have the whole roster. Each driver carries their own vehicle and shift — vehicle type, capacity, maximum distance, working hours, start and end depot, region group and skills — so a vehicle nobody configures is planned as that driver's vehicle rather than as a default.","parameters":[{"name":"territory_id","in":"query","required":false,"schema":{"type":"integer","description":"Narrow to a territory. Drivers with no territory are still included.\n\nTerritory id.\n\n**Details:** Optional · Type `integer`."},"description":"Narrow to a territory. Drivers with no territory are still included.\n\nTerritory id.\n\n**Details:** Optional · Type `integer`."},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":64,"description":"Match on driver name or alias. Re-queries the server rather than filtering what was already sent, because the driver being looked for may never have been in it.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Optional · Type `string` · maxLength `64`."},"description":"Match on driver name or alias. Re-queries the server rather than filtering what was already sent, because the driver being looked for may never have been in it.\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Optional · Type `string` · maxLength `64`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":25,"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `25` · min `1` · max `200`."},"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `25` · min `1` · max `200`."}],"responses":{"200":{"description":"The roster.","content":{"application/json":{"example":{"result":true,"data":{"data":[{"driver_id":12,"driver_name":"Ana Ruiz","driver_alias":"AR-04","vehicle_type":2,"capacity":55,"max_distance":180,"start_time":"06:30","end_time":"16:30","start_address":91,"end_address":91,"region_group_id":5,"skills":[3,8]}],"total":1,"truncated":false}}}}},"422":{"description":"A limit outside the allowed range."}}}},"/v1/dispatch/plan/methods":{"get":{"tags":["Dispatch"],"security":[{"passport":[]}],"summary":"Ways of planning a day","operationId":"dispatchPlanMethods","description":"Every way this account can plan, each saying what it needs. takes is groupings for the methods that offer a list to choose from (street, postcode, order batch), orders for those that carry an explicit selection, and anchors for magnetic planning.\n\nAdvertised rather than assumed on purpose: a client that hard-codes which method behaves how goes stale the moment one is added or withdrawn.\n\nAdditive: `auto_cluster` (planning_method 19, takes `orders`; its own settings are listed under `parameters` and sent in `plan.global`: drivers_per_group, max_group_size, max_routes, balance_groups, route_name_prefix) and `multi_region` (planning_method 17, takes `regions` — region cards under `plan.regions` instead of `plan.routes`; `modes` lists the optimisation modes and `default_mode` the console's default). Both are listed after the original entries so a client that knows only those still reads the same list first. `takes` may now also be `regions`.","responses":{"200":{"description":"The ways of planning.","content":{"application/json":{"example":{"result":true,"data":[{"method":"anchors","name":"Magnetic anchors","takes":"anchors","description":"Put a vehicle where its work is; orders fall to the nearest."},{"method":"street","planning_method":4,"name":"By street","takes":"groupings"},{"method":"multi_route","planning_method":2,"name":"Several routes at once","takes":"orders"},{"method":"auto_cluster","planning_method":19,"name":"Auto-cluster","takes":"orders","description":"The orders are cut into geographic groups, one route per group.","parameters":[{"key":"drivers_per_group","type":"integer","min":1,"default":1},{"key":"max_group_size","type":"integer","min":1,"default":null},{"key":"max_routes","type":"integer","min":1,"default":null},{"key":"balance_groups","type":"boolean","default":false},{"key":"route_name_prefix","type":"string","default":"Auto Group"}]},{"method":"multi_region","planning_method":17,"name":"Multi-region","takes":"regions","description":"One route built from several region cards, each with its own vehicles.","modes":[{"value":"by_region","name":"By region"},{"value":"cross_region","name":"Across regions"},{"value":"per_region","name":"Choose per region"}],"default_mode":"by_region","max_regions":50}]}}}}}}},"/v1/dispatch/plan/groupings":{"get":{"tags":["Dispatch"],"security":[{"passport":[]}],"summary":"Groups of waiting orders to plan","operationId":"dispatchPlanGroupings","description":"What a grouped method offers to choose from — streets, postcodes or order batches — busiest first, each with how many orders are waiting in it. Exactly what the matching web screen lists, including its two conditions: an order needs coordinates to be planned, and a street can only be read from an address that has a house number in front of it.\n\nA method that carries its own orders is refused with 422 rather than answered with an empty list, because an empty list reads as \"nothing waiting today\" — a different and wrong answer. Filters narrow the orders the groups are worked out from, so the groups themselves change — not just which are shown.","parameters":[{"name":"planning_method","in":"query","required":true,"schema":{"type":"integer","enum":[4,5,6],"description":"4 street, 5 postcode, 6 order batch.\n\nAllowed values: `4` · `5` · `6`.\n\n**Details:** Required · Type `integer`.","examples":[4]},"description":"4 street, 5 postcode, 6 order batch.\n\nAllowed values: `4` · `5` · `6`.\n\n**Details:** Required · Type `integer`."},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`.\n\n**Example:** `2026-07-26`.","examples":["2026-07-26"]},"description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`.\n\n**Example:** `2026-07-26`."},{"name":"include_transfer_orders","in":"query","required":false,"schema":{"type":"boolean","default":false,"description":"Include transfer orders. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},"description":"Include transfer orders. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},{"name":"order_batch[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Order batches.\n\n**Details:** Optional · Type `array`, items `string`."},"description":"Order batches.\n\n**Details:** Optional · Type `array`, items `string`."},{"name":"order_source[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer"},"description":"Order sources.\n\n**Details:** Optional · Type `array`, items `integer`."},"description":"Order sources.\n\n**Details:** Optional · Type `array`, items `integer`."},{"name":"related_order_type[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"description":"Related order types. \"NONE\" selects the orders with none.\n\n**Details:** Optional · Type `array`, items `string`."},"description":"Related order types. \"NONE\" selects the orders with none.\n\n**Details:** Optional · Type `array`, items `string`."},{"name":"region[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer"},"description":"Region ids.\n\n**Details:** Optional · Type `array`, items `integer`."},"description":"Region ids.\n\n**Details:** Optional · Type `array`, items `integer`."},{"name":"region_group[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer"},"description":"Region group ids.\n\n**Details:** Optional · Type `array`, items `integer`."},"description":"Region group ids.\n\n**Details:** Optional · Type `array`, items `integer`."}],"responses":{"200":{"description":"The groups.","content":{"application/json":{"example":{"result":true,"data":{"data":[{"name":"River Rd","city":"Richmond","province":"BC","country":"CA","orders_count":29}],"total":35,"orders":72,"date":"2026-07-26"}}}}},"422":{"description":"That way of planning does not offer groupings, or the date could not be read."}}}},"/v1/dispatch/plan/routes":{"post":{"tags":["Dispatch"],"security":[{"passport":[]}],"summary":"Build routes from chosen groupings or orders","operationId":"dispatchPlanRoutes","description":"Builds exactly what the matching web screen builds from the same plan — the same route settings, the same driver rows, the same order handling, the same handover to the planner. Orders the planner has no usable coordinates for are dropped and marked for correction, and a route with neither a driver nor a pending vehicle is skipped, both as the screens have always done.\n\nRecorded as planned from the API, so a route built on a phone can be told apart from one built at a desk.\n\nAdditive since 8.57.20. `plan.global` also accepts what the console's build screens post: `balance_tolerance` (modes 4–7), `balance_preset` (engines 2 and 3), the route-level road preferences (`route_avoid_tolls`, `route_avoid_highways`, `route_avoid_ferries`, `route_prefer_shortest`, `route_optimize_for`, `route_residential_access`, `route_advanced_options`), `solver_rules` (the planning rules object, keys from /plan/options `planning_rules`), `exclusion_zone_set_ids` and `order_number`; each is ignored while the business lacks the matching feature, and an exclusion zone set that cannot be used answers 422 before anything is built. `driver_configs[<driverId>]` also accepts `shifts` and the six per-driver road preference fields, which reach the planner the way the web form's `route_avoid_tolls_<driverId>` do. `planning_method` 19 (auto-cluster) reads its parameters from `plan.global` and the vehicles and optional `orders` from `plan.routes[0]` (without `orders` the pool narrowed by `plan.global.filters` is clustered); `planning_method` 17 (multi-region) takes `plan.regions` — cards of {name, region_ids, region_group_ids, added_orders, removed_orders, drivers, driver_configs, pending, locked} — plus `plan.global.route_name` and `plan.global.mode`, and builds one route. The response additionally carries `rule_notices`: the planning rules the chosen engine cannot apply (empty when none or while Planning Rules is off).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["planning_method","plan"],"properties":{"planning_method":{"type":"integer","description":"**Required.**\n\nFrom /plan/methods.\n\n**Details:** Type `integer`.\n\n**Example:** `4`.","examples":[4]},"plan":{"type":"object","required":["routes"],"properties":{"global":{"type":"object","description":"Settings shared by every route in this plan — date, service times, capacity type, routing engine, balance mode / tolerance / preset, road preferences, solver_rules, exclusion_zone_set_ids, order_number, and the auto-cluster or multi-region parameters.\n\n**Details:** Type `object`."},"routes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"date":{"type":"string","format":"date","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`."},"drivers":{"type":"array","items":{"type":"integer","description":"Drivers. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Drivers. Field in the JSON request body.\n\n**Details:** Type `array`, items `integer`."},"driver_configs":{"type":"object","description":"Per driver id: capacity, max_distance, vehicle_type, skills, start_address, end_address, start_time, end_time, region_group_id, shifts, and the per-driver road preferences route_avoid_tolls / route_avoid_highways / route_avoid_ferries / route_prefer_shortest / route_optimize_for / route_residential_access.\n\n**Details:** Type `object`."},"pending":{"type":"array","description":"Pending. Field in the JSON request body.\n\n**Details:** Type `array`."},"streets":{"type":"array","description":"For street planning; from /plan/groupings.\n\n**Details:** Type `array`."},"postcodes":{"type":"array","description":"Postcodes. Stable machine-readable code.\n\n**Details:** Type `array`."},"batches":{"type":"array","description":"Batches. Field in the JSON request body.\n\n**Details:** Type `array`."},"orders":{"type":"array","items":{"type":"integer","description":"Orders. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"For the methods that carry their own orders.\n\n**Details:** Type `array`, items `integer`."}}},"description":"**Required.**\n\nRoutes. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"regions":{"type":"array","description":"Multi-region (planning_method 17) only: the region cards. Required for that method, ignored by the others.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"region_ids":{"type":"array","items":{"type":"integer","description":"Region ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Region ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"region_group_ids":{"type":"array","items":{"type":"integer","description":"Region group ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Region group ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"added_orders":{"type":"array","items":{"type":"integer","description":"Added orders. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Added orders. Field in the JSON request body.\n\n**Details:** Type `array`, items `integer`."},"removed_orders":{"type":"array","items":{"type":"integer","description":"Removed orders. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Removed orders. Field in the JSON request body.\n\n**Details:** Type `array`, items `integer`."},"drivers":{"type":"array","items":{"type":"integer","description":"Drivers. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Drivers. Field in the JSON request body.\n\n**Details:** Type `array`, items `integer`."},"driver_configs":{"type":"object","description":"Driver configs. Field in the JSON request body.\n\n**Details:** Type `object`."},"pending":{"type":"array","description":"Pending. Field in the JSON request body.\n\n**Details:** Type `array`."},"locked":{"type":"boolean","description":"Locked. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}}}},"description":"**Required.**\n\nLoading / packing plan id or plan payload (see endpoint schema).\n\n**Details:** Type `object`."},"include_transfer_orders":{"type":"boolean","default":false,"description":"Include transfer orders. Field in the JSON request body.\n\n**Details:** Type `boolean` · Default: `false`."}}}}}},"responses":{"200":{"description":"What was built.","content":{"application/json":{"example":{"result":true,"data":{"route_ids":[23991],"orders":96,"skipped":1,"planning_started":true,"rule_notices":[]}}}}},"422":{"description":"The account may not create routes, or the plan was unusable."}}}},"/v1/dispatch/plan/route-sets":{"get":{"tags":["Dispatch"],"security":[{"passport":[]}],"summary":"Saved route sets to plan from","operationId":"dispatchPlanRouteSets","description":"Planning from a set is planning with an explicit order selection plus a note of which set it came from, so this list is needed before that method can be offered at all. Only active sets, in the order the business arranged them.","parameters":[{"name":"territory_id","in":"query","required":false,"schema":{"type":"integer","description":"Territory id.\n\n**Details:** Optional · Type `integer`."},"description":"Territory id.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"The sets.","content":{"application/json":{"example":{"result":true,"data":[{"route_set_id":12,"name":"Weekday north","code":"WN","description":"Mon–Fri north of the river","territory_id":41}]}}}}}}},"/v1/dispatch/plan/options":{"get":{"tags":["Dispatch"],"summary":"Planning options","security":[{"passport":[]}],"description":"Every choice the console's planning screens offer: the settings a route is built with, and the filters that decide which orders are planned at all. Batches, sorting codes and the region lists are read off the orders actually waiting, so the territory and the day change the answer. `choices.routing_engines[].name` is a display label (`sRoute`, `sRoute 2`, `sRoute 2T`; earlier versions returned `SROUTE`, `SROUTE 2`, `SROUTE 2T`) — match engines on `value` (1, 2, 3), never on `name`.\n\nAdditive since 8.57.20 (the dispatch app alignment): `features` says which optional planning blocks this business has (road_preferences, planning_rules, exclusion_zones, recurring_pickups, scheduled_planning); `road_preferences` lists the route-level road preference fields (each naming the `choices` list it is rendered from) and the advanced Valhalla options; `planning_rules` is every planning rule as data — key, name, help, type (select | integer | switch | breaks | merge_stops | reload | goods_class_overrides), options or min/max, and `engines` (the engine values that honour it, `approx_engines` those that approximate it) — so a client shows a rule only for the selected engine; `choices.balance_presets` are the presets the router-API engines (sRoute 2 = 2, sRoute 2T = 3) balance by, each with `applies_to_engine`; `choices.exclusion_zone_sets` the active no-go sets; `choices.multi_region_modes` the multi-region optimisation modes; `settings.routing_engine` the account's own default engine, and `settings.route_*` / `settings.solver_rules` the Route Settings defaults for the road preferences and planning rules. A switched-off block reads `enabled: false` with empty lists, and the server ignores it on a build.","parameters":[{"name":"territory_id","in":"query","required":false,"schema":{"type":"integer","description":"Regions, region groups and label codes only exist inside a territory.\n\nTerritory id.\n\n**Details:** Optional · Type `integer`."},"description":"Regions, region groups and label codes only exist inside a territory.\n\nTerritory id.\n\n**Details:** Optional · Type `integer`."},{"name":"date","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Which day the batch and sorting-code counts are read from. Defaults to tomorrow.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Which day the batch and sorting-code counts are read from. Defaults to tomorrow.\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`, format `date`."}],"responses":{"200":{"description":"The settings, and the values behind every control.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"settings":{"type":"object","description":"Defaults from this business's route settings.\n\n**Details:** Type `object`."},"choices":{"type":"object","description":"Each control's values as {value, name}, plus orders where the server counts them.\n\n**Details:** Type `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"settings":{"serve_time":5,"pickup_time":1,"capacity_type":"package","balance_mode":1,"max_drivers_per_route":10,"routing_engine":1,"route_avoid_tolls":null,"route_optimize_for":1,"solver_rules":{"objective":"balanced"}},"choices":{"balance_modes":[{"value":1,"name":"Balance on number of orders","short_code":"NUM"},{"value":3,"name":"Without Balance","short_code":"OFF"},{"value":4,"name":"Balanced within tolerance","short_code":"TOL"},{"value":5,"name":"Balanced by zone","short_code":"ZONE"},{"value":6,"name":"Working hours within tolerance","short_code":"HRS"}],"balance_tolerances":[{"value":10,"name":"Tight (10%)","applies_to_balance_mode":4,"applies_to_balance_modes":[4,5,6,7]},{"value":15,"name":"Standard (15%)","applies_to_balance_mode":4,"applies_to_balance_modes":[4,5,6,7]},{"value":25,"name":"Relaxed (25%)","applies_to_balance_mode":4,"applies_to_balance_modes":[4,5,6,7]},{"value":40,"name":"Loose (40%)","applies_to_balance_mode":4,"applies_to_balance_modes":[4,5,6,7]}],"routing_engines":[{"value":1,"name":"sRoute"},{"value":2,"name":"sRoute 2"},{"value":3,"name":"sRoute 2T"}],"order_types":[{"value":"DD","name":"Delivery (Delivery Step)"},{"value":"P","name":"Pickup"}],"customers":[{"value":"DIRECT","name":"Direct"},{"value":88,"name":"Northside Bakery"}],"channels":[{"value":-1,"name":"None"}],"order_batches":[{"value":"N/A","name":"N/A","orders":42}],"sorting_codes":[{"value":"A1","name":"A1","orders":17}],"balance_presets":[{"value":"balanced","name":"Balanced","description":"time, orders","applies_to_engine":2},{"value":"balanced","name":"Balanced","description":"time, orders","applies_to_engine":3}],"road_flag_options":[{"value":"","name":"Follow the vehicle setting"},{"value":1,"name":"On"},{"value":0,"name":"Off"}],"optimize_for_options":[{"value":"","name":"Follow the vehicle setting"},{"value":0,"name":"Fastest"},{"value":1,"name":"Balanced"},{"value":2,"name":"Shortest"}],"residential_access_options":[{"value":"","name":"Follow the vehicle setting"},{"value":2,"name":"Standard"}],"exclusion_zone_sets":[{"value":41,"name":"Downtown works","color":"#d9534f","zones":[{"name":"Bridge closure","from":"2026-09-01","until":"2026-10-15"}]}],"multi_region_modes":[{"value":"by_region","name":"By region","help":"Each region's orders are served only by that region's vehicles."},{"value":"cross_region","name":"Across regions","help":"Any driver may serve any region's orders."},{"value":"per_region","name":"Choose per region","help":"Locked regions keep their own drivers."}]},"features":{"road_preferences":true,"planning_rules":true,"exclusion_zones":true,"recurring_pickups":false,"scheduled_planning":false},"road_preferences":{"enabled":true,"fields":[{"key":"route_avoid_tolls","name":"Avoid tolls","type":"flag","options_key":"road_flag_options"},{"key":"route_optimize_for","name":"Optimise for","type":"select","options_key":"optimize_for_options"}],"driver_fields":["route_avoid_tolls","route_avoid_highways","route_avoid_ferries","route_prefer_shortest","route_optimize_for","route_residential_access"],"advanced":{"key":"route_advanced_options","seconds":[{"key":"gate_penalty","name":"Gate penalty","default":300,"min":0,"max":43200}],"switches":[{"key":"exclude_unpaved","name":"Exclude unpaved roads"}]}},"planning_rules":{"enabled":true,"rules":[{"key":"objective","name":"Plan Objective","help":"What the plan keeps as low as possible.","type":"select","options":[{"value":"balanced","name":"Balanced"},{"value":"fastest","name":"Fastest"}],"engines":[1,2,3],"approx_engines":[],"companion_of":null},{"key":"lateness_tolerance_minutes","name":"Lateness Tolerance (minutes)","help":"Minutes a stop may run past its window.","type":"integer","min":0,"max":120,"default":null,"engines":[3],"approx_engines":[],"companion_of":null},{"key":"breaks","name":"Driver Breaks","type":"breaks","max_items":3,"minutes_min":5,"minutes_max":240,"skip_policies":[{"value":"","name":"Never skip"}],"engines":[1,2,3],"approx_engines":[],"companion_of":null}],"engine_versions":{"1":null,"2":"1.2.11","3":"1.0.22"},"depot_options":[{"value":512,"name":"Main warehouse"}],"place_options":[],"breaks_max":3,"break_places_max":10,"reload_depots_max":10}}}}}},"401":{"description":"Not authenticated."}}}},"/v1/dispatch/plan/settings":{"get":{"tags":["Dispatch"],"summary":"Planning settings","security":[{"passport":[]}],"description":"The settings a route is built with, defaulted the way this business has configured them — the same values the console preloads into its planning screens. Additive: `routing_engine` (the account's own default engine, 1 sRoute / 2 sRoute 2 / 3 sRoute 2T), the Route Settings defaults for the route-level road preferences (`route_avoid_tolls`, `route_avoid_highways`, `route_avoid_ferries`, `route_optimize_for`, `route_residential_access`, `route_advanced_options`; null = follow the vehicle model) and `solver_rules` (the business's default planning rules). Each reads null while the matching feature switch is off.","responses":{"200":{"description":"Defaults, plus the limits that are the business's rule rather than a per-route choice.","content":{"application/json":{"example":{"result":true,"data":{"pickup_time":1,"serve_time":5,"package_pickup_time":30,"package_processing_time":30,"capacity_type":"package","balance_mode":1,"balance_tolerance":null,"load_check":0,"work_from":"09:00","work_end":"20:00","max_drivers_per_route":10,"route_approval_type":0,"max_orders_per_vehicle":300,"routing_engine":1,"route_avoid_tolls":null,"route_avoid_highways":null,"route_avoid_ferries":null,"route_optimize_for":null,"route_residential_access":null,"route_advanced_options":null,"solver_rules":null}}}}},"401":{"description":"Not authenticated."}}}},"/v1/dispatch/plan/context":{"get":{"tags":["Dispatch"],"summary":"Working context","security":[{"passport":[]}],"description":"Where this account is working: which territory, and which depot within it, plus the lists to choose from. Both are account-wide on the console rather than per-plan — the territory decides the drivers, regions and orders; the depot decides which of that territory's stock a route is loaded from.","parameters":[{"name":"territory_id","in":"query","required":false,"schema":{"type":"integer","description":"Ask as if this territory were selected. A territory this account cannot reach is answered as none.\n\nTerritory id.\n\n**Details:** Optional · Type `integer`."},"description":"Ask as if this territory were selected. A territory this account cannot reach is answered as none.\n\nTerritory id.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"The current territory and depot, and what may be chosen.","content":{"application/json":{"example":{"result":true,"data":{"territories":[{"value":3,"name":"Greater Toronto"}],"territory_id":3,"can_view_all_territories":false,"work_locations":[{"value":91,"name":"Etobicoke DC","address":"12 Judson St"}],"work_location_id":91,"default_fulfillment_center_id":91}}}}},"401":{"description":"Not authenticated."}}}},"/v1/dispatch/plan/work-location":{"post":{"tags":["Dispatch"],"summary":"Set work location","security":[{"passport":[]}],"description":"Change which depot this account works from. Writes the same setting the console's Change Location page writes, so the two never disagree about where somebody is — moving depot on a phone moves it at the desk as well.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"work_location_id":{"type":["integer","null"],"description":"An address belonging to this business. Null clears it, which falls back to the territory's default fulfilment centre.\n\n**Details:** Type `integer` · Nullable."}}},"example":{"work_location_id":91}}}},"responses":{"200":{"description":"The working context after the change.","content":{"application/json":{"example":{"result":true,"data":{"territory_id":3,"work_location_id":91,"default_fulfillment_center_id":91}}}}},"422":{"description":"That location does not belong to this business."},"401":{"description":"Not authenticated."}}}},"/v1/third-party-delivery/locker-scope-locations":{"get":{"tags":["ThirdPartyDelivery"],"summary":"List eligible locker locations for a grant or partner scope","description":"Returns every locker location currently available to the authenticated third-party delivery provider. Omit both scope ids to list the full ceiling (union of active platform grants, or every eligible location when no grants exist). Pass platform_scope_group_id and/or partner_scope_group_id to narrow the list. Each location includes id, unique code, name, address_1, address_2, city, province, country, postcode, latitude/longitude, locker_count, and the platform grants that cover it. Requires locker delivery access (generate codes or manage partner scopes). mock=true counts only the provider's mock cabinets. online_only defaults to true: cabinets the provider reports as offline are not counted, and a location whose every cabinet is offline is left out of the listing — pass online_only=false to list every eligible cabinet and skip the device-state lookup entirely. A cabinet whose provider cannot be reached at all is unknown, not offline, and stays listed. include_lockers=true adds a lockers[] array to each location naming its cabinets and their state; online_locker_count/offline_locker_count/unknown_locker_count are null when neither option asked for device state.","operationId":"partnerLockerScopeLocations","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Third-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"platform_scope_group_id","required":false,"schema":{"type":"integer","description":"Limit to one active platform grant.\n\n**Details:** Optional · Type `integer`."},"description":"Limit to one active platform grant.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"partner_scope_group_id","required":false,"schema":{"type":"integer","description":"Limit to one active partner sub-scope (parent grant is resolved automatically when omitted).\n\n**Details:** Optional · Type `integer`."},"description":"Limit to one active partner sub-scope (parent grant is resolved automatically when omitted).\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"mock","required":false,"schema":{"type":"boolean","default":false,"description":"Return sandbox locations instead of production ones. A location is only listed when it holds a cabinet of the matching kind, so the ids returned here are exactly the ids a delivery created with the same mock value can use.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},"description":"Return sandbox locations instead of production ones. A location is only listed when it holds a cabinet of the matching kind, so the ids returned here are exactly the ids a delivery created with the same mock value can use.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},{"in":"query","name":"online_only","required":false,"schema":{"type":"boolean","default":true,"description":"Only count cabinets the platform can currently reach. Default true: an offline cabinet cannot take a parcel, and a location whose every cabinet is offline is left out of the listing entirely. Pass false to list every eligible cabinet regardless of device state (and to skip the device-state lookup). A cabinet whose provider cannot be reached at all is 'unknown', not offline, and stays listed.\n\n**Details:** Optional · Type `boolean` · Default: `true`."},"description":"Only count cabinets the platform can currently reach. Default true: an offline cabinet cannot take a parcel, and a location whose every cabinet is offline is left out of the listing entirely. Pass false to list every eligible cabinet regardless of device state (and to skip the device-state lookup). A cabinet whose provider cannot be reached at all is 'unknown', not offline, and stays listed.\n\n**Details:** Optional · Type `boolean` · Default: `true`."},{"in":"query","name":"include_lockers","required":false,"schema":{"type":"boolean","default":false,"description":"Add a lockers[] array to every location listing the cabinets it holds (shelf_id, device_id, name, status, online, mock, compartment_count). Off by default because it needs a device-state lookup.\n\n**Details:** Optional · Type `boolean` · Default: `false`."},"description":"Add a lockers[] array to every location listing the cabinets it holds (shelf_id, device_id, name, status, online, mock, compartment_count). Off by default because it needs a device-state lookup.\n\n**Details:** Optional · Type `boolean` · Default: `false`."}],"responses":{"200":{"description":"Eligible locations listed.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`.\n\n**Example:** `OK`.","examples":["OK"]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"count":{"type":"integer","description":"Count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`.\n\n**Example:** `2`.","examples":[2]},"filter":{"type":"object","properties":{"platform_scope_group_id":{"type":["integer","null"],"description":"Platform scope group id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"partner_scope_group_id":{"type":["integer","null"],"description":"Partner scope group id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"mock":{"type":"boolean","description":"Mock. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"online_only":{"type":"boolean","description":"Online only. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"include_lockers":{"type":"boolean","description":"Include lockers. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Filter. Field in the JSON request body.\n\n**Details:** Type `object`."},"locations":{"type":"array","items":{"$ref":"#/components/schemas/PartnerLockerScopeLocation","description":"Locations. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `PartnerLockerScopeLocation`."},"description":"Locations. Field in the JSON request body.\n\n**Details:** Type `array`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"code":"OK","message":"Locker scope locations listed.","data":{"count":1,"filter":{"platform_scope_group_id":12,"partner_scope_group_id":null,"mock":false,"online_only":true,"include_lockers":false},"locations":[{"id":101,"name":"Downtown Locker","code":"LOC-A1B2C3","address_1":"100 Front St W","address_2":"Unit 5","city":"Toronto","province":"ON","country":"Canada","postcode":"M5J 1E3","latitude":43.6426,"longitude":-79.3871,"locker_count":2,"platform_scope_group_ids":[12],"online_locker_count":2,"offline_locker_count":0,"unknown_locker_count":0}]}}}}},"403":{"description":"Locker access disabled or provider not permitted."},"404":{"description":"Named platform grant or partner scope not found."}}}},"/v1/third-party-delivery/carrier-profile":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Carrier warehouse-intake profile","description":"Who the carrier is to this client, which identification mode it operates in (M1 member-number only / M2 tracking-number only / M3 either / M4 neither), which fields are required on submission, which endpoint families are open, and the rate limit. Member numbers are matched case-insensitively and are never rewritten.","operationId":"carrierProfile","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Carrier profile","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Carrier profile loaded.","data":{"provider":{"id":50,"name":"Test Provider"},"carrier":{"id":910,"code":"test_carrier","name":"Test Carrier","is_active":true},"identification":{"mode":"M3","has_member_number":true,"has_tracking_number":true,"member_number_required":false,"tracking_number_required":false,"one_of_required":["member_number","carrier_reference_number"],"case_sensitive":false},"requirements":{"recipient_contact_required":true,"ref_unique_scope":"warehouse"},"capabilities":["warehouse_intake_read","locker_delivery","members"],"limits":{"rate_limit_per_minute":60,"packages_max_per_page":200}}}}}},"403":{"description":"CARRIER_INTAKE_DISABLED (warehouse intake not enabled for this provider) or LOCKER_PERMISSION_DENIED"},"409":{"description":"CARRIER_NOT_LINKED — the provider has no carrier_settings row linked yet"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/carrier-intake-locations":{"get":{"tags":["ThirdPartyDelivery"],"summary":"List the client's active receiving locations","description":"Active warehouses and pickup points of the client this carrier delivers to, with address and coordinates.","operationId":"carrierIntakeLocations","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"q","required":false,"schema":{"type":"string","description":"Search by name, code, city or postcode\n\n**Details:** Optional · Type `string`."},"description":"Search by name, code, city or postcode\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"page","required":false,"schema":{"type":"integer","description":"Page number, with per_page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Page number, with per_page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","description":"Rows per page, 1-200. Omitted, the whole list is returned as before; count is always the number of matching rows\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"Rows per page, 1-200. Omitted, the whole list is returned as before; count is always the number of matching rows\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Receiving locations","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Receiving locations listed.","data":{"scope":"business_active_locations","count":1,"locations":[{"warehouse_id":700,"name":"Main Warehouse","code":"MW-1","address":{"street_number":100,"street_name":"King St","apt":null,"city":"Montreal","province":"QC","country":"CA","postcode":"H3B1A1"},"telephone":"+15145550000","coordinates":{"lat":45.5017,"lng":-73.5673},"is_warehouse":true,"is_point":false}],"page":1,"per_page":null,"total_pages":1}}}}},"403":{"description":"CARRIER_INTAKE_DISABLED (warehouse intake not enabled for this provider) or LOCKER_PERMISSION_DENIED"},"409":{"description":"CARRIER_NOT_LINKED — the provider has no carrier_settings row linked yet"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/carrier-receiving-warehouses":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Warehouses where this carrier may hand pre-advised packages over","description":"The client's active warehouses this carrier may hand pre-advised packages over at (staging area, staff shelving). When the client restricted the carrier to a list in its locker settings only those are returned (`scope` = `restricted`); otherwise every active warehouse of the business (`scope` = `business_warehouses`). Destinations — where a package may be pre-advised to and where the recipient collects — are a different list: see carrier-intake-locations. A handover scanned at a warehouse outside this list is refused by the warehouse.","operationId":"carrierReceivingWarehouses","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"q","required":false,"schema":{"type":"string","description":"Search by name, code, city or postcode\n\n**Details:** Optional · Type `string`."},"description":"Search by name, code, city or postcode\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"page","required":false,"schema":{"type":"integer","description":"Page number, with per_page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Page number, with per_page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","description":"Rows per page, 1-200. Omitted, the whole list is returned as before; count is always the number of matching rows\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"Rows per page, 1-200. Omitted, the whole list is returned as before; count is always the number of matching rows\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Receiving warehouses","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Receiving warehouses listed.","data":{"scope":"restricted","count":1,"warehouses":[{"warehouse_id":700,"name":"Main Warehouse","code":"MAIN","address":{"street_number":100,"street_name":"Rue Sainte-Catherine","apt":null,"city":"Montreal","province":"QC","country":"CA","postcode":"H2X 1Z4"},"telephone":null,"coordinates":{"lat":45.5075,"lng":-73.5605}}],"page":1,"per_page":null,"total_pages":1}}}}},"403":{"description":"CARRIER_INTAKE_DISABLED (warehouse intake not enabled for this provider) or LOCKER_PERMISSION_DENIED"},"409":{"description":"CARRIER_NOT_LINKED — the provider has no carrier_settings row linked yet"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/carrier-packages":{"get":{"tags":["ThirdPartyDelivery"],"summary":"List this carrier's packages in the client's warehouses","description":"Held packages (in_staging / shelved) plus already collected ones (picked_up). A confirmed pickup deletes the inventory row, so collected packages are read from the pickup history. Recipient reachability is reported as booleans only — no phone or email is ever returned. Each held package also reports `group`: null for a package entered on its own, otherwise the multi-package pickup group it belongs to — group_id, status, the shared pickup_code that collects the whole order (withheld while the group is pending), this package's sequence, package_count and picked_up_count. Picked-up packages report null. Each held package also reports `received`: null while the carrier still has it, otherwise where and when the warehouse took physical delivery (warehouse_id, warehouse_name, at). Handover is a step inside in_staging, not a status: the package stays in_staging until shelved. `location` is the pickup location the carrier named — the destination where the recipient collects — not where the package was handed over. Each package also carries `claimed_by`: the carrier's own live locker delivery task that will deposit it (`{delivery_no}`), or null when staff will shelve it. Additive: `distribution` describes the run from the receiving warehouse to the named location when the package rides on a distribution order (status pending_route, routed, in_transit, delivered or shelved, with the route date and the loaded/delivered/shelved times); null otherwise.","operationId":"carrierPackages","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"status","required":false,"schema":{"type":"string","description":"in_staging | shelved | picked_up\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},"description":"in_staging | shelved | picked_up\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"warehouse_id","required":false,"schema":{"type":"integer","description":"Restrict to one receiving location\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},"description":"Restrict to one receiving location\n\nWarehouse id used as the location / stock context.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"member_number","required":false,"schema":{"type":"string","description":"Exact match, case-insensitive\n\n**Details:** Optional · Type `string`."},"description":"Exact match, case-insensitive\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"carrier_reference_number","required":false,"schema":{"type":"string","description":"Exact match\n\n**Details:** Optional · Type `string`."},"description":"Exact match\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"carrier_order_id","required":false,"schema":{"type":"string","description":"Exact match\n\n**Details:** Optional · Type `string`."},"description":"Exact match\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"batch","required":false,"schema":{"type":"string","description":"Exact match\n\n**Details:** Optional · Type `string`."},"description":"Exact match\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"ref","required":false,"schema":{"type":"string","description":"Exact match\n\n**Details:** Optional · Type `string`."},"description":"Exact match\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"stocked_in_from","required":false,"schema":{"type":"string","description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`."},"description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"stocked_in_to","required":false,"schema":{"type":"string","description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`."},"description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`."},{"in":"query","name":"received","required":false,"schema":{"type":"boolean","description":"true: handed over at a warehouse and not yet shelved; false: pre-advised, not handed over yet; omitted: both\n\n**Details:** Optional · Type `boolean`."},"description":"true: handed over at a warehouse and not yet shelved; false: pre-advised, not handed over yet; omitted: both\n\n**Details:** Optional · Type `boolean`."},{"in":"query","name":"page","required":false,"schema":{"type":"integer","description":"Defaults to 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Defaults to 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","description":"Defaults to 50, capped at 200\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"Defaults to 50, capped at 200\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Carrier packages","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Carrier packages listed.","data":{"count":1,"page":1,"per_page":50,"filters":{"status":null,"warehouse_id":null,"member_number":null,"carrier_reference_number":null,"carrier_order_id":null,"batch":null,"ref":null,"stocked_in_from":null,"stocked_in_to":null,"sequence":null,"received":null},"packages":[{"package_no":"910-1","status":"shelved","member_number":"A001","carrier_reference_number":"TN1","carrier_order_id":null,"batch":"B-1","ref":null,"pickup_code":"PICK01","group":{"group_id":50,"status":"ready","pickup_code":"GRP050","sequence":1,"package_count":2,"picked_up_count":0},"recipient":{"bound":true,"contact_on_file":false},"location":{"warehouse_id":700,"warehouse_name":"Main Warehouse","shelf_code":"SH-1","grid_code":"A-01"},"received":{"warehouse_id":700,"warehouse_name":"Main Warehouse","at":"2026-08-01 09:30:00"},"claimed_by":null,"stocked_in_at":"2026-08-01 10:00:00","picked_up_at":null,"distribution":{"order_id":9002,"order_ref":"DIST-276-703-20260920-1","status":"in_transit","route_date":"2026-09-20","loaded_at":"2026-09-20 10:12:00","delivered_at":null,"shelved_at":null}}]}}}}},"403":{"description":"CARRIER_INTAKE_DISABLED (warehouse intake not enabled for this provider) or LOCKER_PERMISSION_DENIED"},"409":{"description":"CARRIER_NOT_LINKED — the provider has no carrier_settings row linked yet"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/carrier-packages/{packageNo}":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Get one carrier package","description":"package_no is \"{carrier_setting_id}-{sequence}\"; the bare sequence is also accepted. A package_no carrying another carrier's id never resolves. Each held package also reports `group`: null for a package entered on its own, otherwise the multi-package pickup group it belongs to — group_id, status, the shared pickup_code that collects the whole order (withheld while the group is pending), this package's sequence, package_count and picked_up_count. Picked-up packages report null. Each held package also reports `received`: null while the carrier still has it, otherwise where and when the warehouse took physical delivery (warehouse_id, warehouse_name, at). Handover is a step inside in_staging, not a status: the package stays in_staging until shelved. `location` is the pickup location the carrier named — the destination where the recipient collects — not where the package was handed over.","operationId":"carrierPackage","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"packageNo","required":true,"schema":{"type":"string","description":"e.g. 910-1 or 1\n\n**Details:** Required · Type `string`."},"description":"e.g. 910-1 or 1\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Carrier package"},"404":{"description":"CARRIER_PACKAGE_NOT_FOUND"},"403":{"description":"CARRIER_INTAKE_DISABLED (warehouse intake not enabled for this provider) or LOCKER_PERMISSION_DENIED"},"409":{"description":"CARRIER_NOT_LINKED — the provider has no carrier_settings row linked yet"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/carrier-packages/{packageNo}/reset-pickup-code":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Reset a carrier package's pickup code","description":"Retires the package's current pickup code and mints a replacement. The old code stops resolving immediately at every pickup entry point — codes are read from the central registry at use time, never cached. A carrier may only reset packages it submitted; package_no is \"{carrier_setting_id}-{sequence}\" and the bare sequence is also accepted. The reset is written to the package activity log as event_type=pickup_code_reset, recording who did it and from which IP, with masked codes only — no full code is ever stored in the log. When the package is already shelved and notify_recipient is true, the recipient is notified again with the new code; a package still in the staging area is never notified, because its code has not been announced yet. A collected package no longer has an inventory row, so it returns CARRIER_PACKAGE_NOT_FOUND — there is no code left to reset.","operationId":"resetCarrierPackagePickupCode","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"packageNo","required":true,"schema":{"type":"string","description":"e.g. 910-1 or 1\n\n**Details:** Required · Type `string`."},"description":"e.g. 910-1 or 1\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notify_recipient":{"type":"boolean","default":true,"description":"Re-notify the recipient with the new code when the package is already shelved. Has no effect on a package still in the staging area.\n\n**Details:** Type `boolean` · Default: `true`."}}},"example":{"notify_recipient":true}}}},"responses":{"200":{"description":"Pickup code reset","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"code":{"type":"string","description":"OK on success.\n\n**Details:** Type `string`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"package_no":{"type":"string","description":"\"{carrier_setting_id}-{sequence}\".\n\n**Details:** Type `string`."},"pickup_code":{"type":"string","description":"The new code. Revealed only here and, when the recipient is notified, in that notification.\n\n**Details:** Type `string`."},"previous_pickup_code_mask":{"type":["string","null"],"description":"The retired code, masked to its last two characters. Null when the package had no code yet.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"string","enum":["in_staging","shelved"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `in_staging` · `shelved`.\n\n**Details:** Type `string`."},"recipient_notified":{"type":"boolean","description":"True only when a notification was actually queued: the package is shelved, notify_recipient was true, and the recipient is reachable (bound member number or a contact captured at upload).\n\n**Details:** Type `boolean`."},"reset_at":{"type":"string","format":"date-time","description":"Reset at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"code":"OK","message":"Pickup code reset.","data":{"package_no":"910-1","pickup_code":"K7Q2ZP","previous_pickup_code_mask":"****01","status":"shelved","recipient_notified":true,"reset_at":"2026-08-23T10:15:00+00:00"}}}}},"404":{"description":"CARRIER_PACKAGE_NOT_FOUND — unknown package, another carrier's package, or one that has already been collected"},"403":{"description":"CARRIER_INTAKE_DISABLED (warehouse intake not enabled for this provider) or LOCKER_PERMISSION_DENIED"},"409":{"description":"CARRIER_NOT_LINKED — the provider has no carrier_settings row linked yet"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/carrier-packages/{packageNo}/cancel":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Cancel a pre-advised carrier package","description":"Withdraws a package the carrier pre-advised but still has: only while it is in the staging area and not yet handed over at a warehouse. The package and its pickup code are removed and the deletion is kept on the client's recycle bin and inventory log. Once the warehouse has received it (`received` non-null) or it sits on a shelf, the request is refused with 409 CARRIER_PACKAGE_NOT_CANCELLABLE (`errors.because` = received | shelved); from then on the client's staff own the parcel. Picked-up packages are not found.","operationId":"cancelCarrierPackage","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"packageNo","required":true,"schema":{"type":"string","description":"e.g. 910-2 or 2\n\n**Details:** Required · Type `string`."},"description":"e.g. 910-2 or 2\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":200,"description":"Free text kept on the audit trail.\n\n**Details:** Type `string` · maxLength `200`."}}},"example":{"reason":"Shipment consolidated"}}}},"responses":{"200":{"description":"Package cancelled","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Carrier package cancelled.","data":{"package_no":"910-2","status":"cancelled","location":{"warehouse_id":700,"warehouse_name":"Main Warehouse"},"cancelled_at":"2026-09-20T14:05:00+00:00"}}}}},"403":{"description":"CARRIER_INTAKE_DISABLED or LOCKER_PERMISSION_DENIED"},"404":{"description":"CARRIER_PACKAGE_NOT_FOUND — no held package of this carrier by that number"},"409":{"description":"CARRIER_PACKAGE_NOT_CANCELLABLE (received or shelved) or CARRIER_NOT_LINKED"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/carrier-packages/{packageNo}/reroute":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Send a pre-advised carrier package to another pickup location","description":"Changes the destination of a package that is not yet shelved — handed over at a warehouse or not. The new destination must be an active warehouse or pickup point of the client, as listed by carrier-intake-locations (a customer account working under upload authorizations is held to them as at stock-in); otherwise 422 CARRIER_DESTINATION_INVALID. The handover record (`received`) is kept and the package is sorted to the new destination; the locker stock-in matches it on the new destination from then on. A package already on a shelf is refused with 409 CARRIER_PACKAGE_NOT_REROUTABLE; a held package of this carrier with the same `ref` at the new destination is refused with 409 CARRIER_REF_CONFLICT. Sending the current destination is a no-op (`changed` = false). A package with declared measurements is also checked against every locker compartment staff could shelve it into at the new destination, exactly as at stock-in: if none could ever hold it, the reroute is refused with 409 LOCKER_CAPACITY_SIZE_EXCEEDED / LOCKER_CAPACITY_WEIGHT_EXCEEDED / LOCKER_CAPACITY_SIZE_AND_WEIGHT_EXCEEDED (errors.because = unfit) and the destination is unchanged. Undeclared packages, destinations without a locker, and compartments without limits pass.","operationId":"rerouteCarrierPackage","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"packageNo","required":true,"schema":{"type":"string","description":"e.g. 910-2 or 2\n\n**Details:** Required · Type `string`."},"description":"e.g. 910-2 or 2\n\n**Details:** Required · Type `string`."},{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["warehouse_id"],"properties":{"warehouse_id":{"type":"integer","description":"**Required.**\n\nNew destination: warehouse_id from carrier-intake-locations.\n\n**Details:** Type `integer`."}}},"example":{"warehouse_id":703}}}},"responses":{"200":{"description":"Package rerouted","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Carrier package rerouted.","data":{"package_no":"910-2","status":"in_staging","changed":true,"location":{"warehouse_id":703,"warehouse_name":"Point B"},"previous_location":{"warehouse_id":700,"warehouse_name":"Main Warehouse"},"received":null,"rerouted_at":"2026-09-20T14:06:00+00:00"}}}}},"403":{"description":"CARRIER_INTAKE_DISABLED or LOCKER_PERMISSION_DENIED"},"404":{"description":"CARRIER_PACKAGE_NOT_FOUND"},"409":{"description":"CARRIER_PACKAGE_NOT_REROUTABLE (shelved), CARRIER_REF_CONFLICT, CARRIER_NOT_LINKED, or LOCKER_CAPACITY_SIZE_EXCEEDED / LOCKER_CAPACITY_WEIGHT_EXCEEDED / LOCKER_CAPACITY_SIZE_AND_WEIGHT_EXCEEDED when the package declared measurements and no locker compartment at the new destination could hold it (errors.because = unfit; the same check as at stock-in, with the same exemptions)"},"422":{"description":"CARRIER_DESTINATION_INVALID or a missing warehouse_id"},"429":{"description":"LOCKER_RATE_LIMITED"}}}},"/v1/customer/register":{"post":{"tags":["Customer"],"summary":"Customer self-registration","description":"Creates a customer account under a business. No authentication: this is the public sign-up door for apps and integrations. The business must be an enabled client and must have Customer Self Registration turned on; otherwise the request is refused and nothing is written. The tracking number prefix is resolved from the business's own settings. Whether the new account can be used right away is then `api_customer_self_registration_review` (separate from the registration page's `customer_self_registration_review`): when that switch is on, the account is created disabled and queued for review, and `pending_review` in the response is true. Rate limited: at most 10 attempts per IP per minute.","operationId":"customerSelfRegister","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email","password","password_confirmation","telephone","business_id"],"properties":{"name":{"type":"string","maxLength":255,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `255`."},"email":{"type":"string","format":"email","maxLength":255,"description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email` · maxLength `255`."},"password":{"type":"string","minLength":6,"description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string` · minLength `6`."},"password_confirmation":{"type":"string","description":"**Required.**\n\nMust match password.\n\n**Details:** Type `string`."},"telephone":{"type":"string","maxLength":255,"description":"**Required.**\n\nPhone number in international or local form accepted by the account locale.\n\n**Details:** Type `string` · maxLength `255`."},"business_id":{"type":"integer","description":"**Required.**\n\nBusiness the customer registers into.\n\n**Details:** Type `integer`."},"address":{"type":["string","null"],"description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"address_2":{"type":["string","null"],"description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string` · Nullable."},"city":{"type":["string","null"],"description":"City / locality.\n\n**Details:** Type `string` · Nullable."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"postcode":{"type":["string","null"],"description":"Postal / ZIP code.\n\n**Details:** Type `string` · Nullable."},"country":{"type":["string","null"],"description":"Defaults to Canada.\n\n**Details:** Type `string` · Nullable."}}}}}},"responses":{"201":{"description":"Registration accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"pending_review":{"type":"boolean","description":"True when the business reviews API registrations; the account cannot sign in until an operator approves it.\n\n**Details:** Type `boolean`."}}},"example":{"result":true,"message":"Registration successful","pending_review":false}}}},"422":{"description":"Validation failed, or the email is already registered.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Email already registered`.","examples":["Email already registered"]}}}}}},"429":{"description":"Too many registration attempts from this IP (limit: 10 per minute). Retry after the delay indicated by the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Too Many Attempts.`.","examples":["Too Many Attempts."]}}}}}}}}},"/v1/customer/wechat-register":{"post":{"tags":["Customer"],"summary":"WeChat customer registration (step 2)","description":"Second step of WeChat mini-program sign-up: creates the account and binds the WeChat openid carried by `openid_token`. The openid is never accepted in the clear. The business must be an enabled client and must have Customer Self Registration turned on; otherwise the request is refused and nothing is written. An account that is active right away is signed in and gets an access token in the same response. Whether the new account can be used right away is then `api_customer_self_registration_review` (separate from the registration page's `customer_self_registration_review`): when that switch is on, the account is created disabled and queued for review, and `pending_review` in the response is true. Rate limited: at most 10 attempts per IP per minute.","operationId":"customerWechatRegister","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["openid_token","name","email","password","password_confirmation","telephone","business_id"],"properties":{"openid_token":{"type":"string","description":"**Required.**\n\nEncrypted openid returned by POST /v1/customer/wechat-login when it answers need_register.\n\n**Details:** Type `string`."},"name":{"type":"string","maxLength":255,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `255`."},"email":{"type":"string","format":"email","maxLength":255,"description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email` · maxLength `255`."},"password":{"type":"string","minLength":6,"description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string` · minLength `6`."},"password_confirmation":{"type":"string","description":"**Required.**\n\nMust match password.\n\n**Details:** Type `string`."},"telephone":{"type":"string","maxLength":255,"description":"**Required.**\n\nPhone number in international or local form accepted by the account locale.\n\n**Details:** Type `string` · maxLength `255`."},"business_id":{"type":"integer","description":"**Required.**\n\nBusiness the customer registers into.\n\n**Details:** Type `integer`."},"address":{"type":["string","null"],"description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"address_2":{"type":["string","null"],"description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string` · Nullable."},"city":{"type":["string","null"],"description":"City / locality.\n\n**Details:** Type `string` · Nullable."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"postcode":{"type":["string","null"],"description":"Postal / ZIP code.\n\n**Details:** Type `string` · Nullable."},"country":{"type":["string","null"],"description":"Defaults to Canada.\n\n**Details:** Type `string` · Nullable."},"tracking_number_prefix":{"type":["string","null"],"description":"Defaults to SR.\n\n**Details:** Type `string` · Nullable."}}}}}},"responses":{"201":{"description":"Registration accepted. An active account is signed in immediately and receives a token; an account awaiting review is not.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"pending_review":{"type":"boolean","description":"Present and true when the account awaits review. No token is issued in that case.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"access_token":{"type":"string","description":"Only for an account that is active right away.\n\n**Details:** Type `string`."},"token_type":{"type":"string","description":"Token type. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`.\n\n**Example:** `Bearer`.","examples":["Bearer"]},"expires_at":{"type":"string","description":"Expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"expires_timestamp":{"type":"integer","description":"Expires timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`."}}},"example":{"result":true,"pending_review":true,"message":"Your registration was received and is waiting for approval. You will get an email once it is reviewed."}}}},"400":{"description":"Invalid openid token."},"422":{"description":"Validation failed, or the email is already registered.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Email already registered`.","examples":["Email already registered"]}}}}}},"429":{"description":"Too many registration attempts from this IP (limit: 10 per minute). Retry after the delay indicated by the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Too Many Attempts.`.","examples":["Too Many Attempts."]}}}}}}}}},"/v1/customer/wechat-login":{"post":{"tags":["Customer"],"summary":"WeChat customer sign-in (step 1)","description":"Trades a WeChat mini-program `code` (from uni.login()) for a session, using the per-business mini-program credentials. A linked and active account is signed in and receives an access token. An openid nobody has claimed yet comes back as `need_register` with an encrypted `openid_token` to carry into POST /v1/customer/wechat-register — the raw openid is never returned. A business with no mini-program credentials configured is refused with 503 before any call to WeChat.","operationId":"customerWechatLogin","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","business_id"],"properties":{"code":{"type":"string","description":"**Required.**\n\nTemporary code from uni.login()\n\n**Details:** Type `string`."},"business_id":{"type":"integer","description":"**Required.**\n\nBusiness id. Identifier referencing the related record.\n\n**Details:** Type `integer`."}}}}}},"responses":{"200":{"description":"Signed in, or told to register.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"need_register":{"type":"boolean","description":"True when this openid is not linked to an account yet.\n\n**Details:** Type `boolean`."},"openid_token":{"type":"string","description":"Encrypted openid; only present with need_register.\n\n**Details:** Type `string`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"access_token":{"type":"string","description":"Only when an account was signed in.\n\n**Details:** Type `string`."},"token_type":{"type":"string","description":"Token type. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`.\n\n**Example:** `Bearer`.","examples":["Bearer"]},"expires_at":{"type":"string","description":"Expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"expires_timestamp":{"type":"integer","description":"Expires timestamp. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"provider_logo":{"type":"string","description":"Provider logo. Field in the JSON request body.\n\n**Details:** Type `string`."},"provider_logo_white":{"type":"string","description":"Provider logo white. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"result":false,"need_register":true,"openid_token":"eyJpdiI6...","message":"WeChat account not linked. Please complete registration."}}}},"401":{"description":"WeChat rejected the code."},"503":{"description":"This business has no WeChat mini-program credentials configured."}}}},"/v1/customer/forgot-password":{"post":{"tags":["Customer"],"summary":"Request a customer password reset code","description":"Emails the customer a 6-digit code, valid for 10 minutes. The response is identical whether or not the address belongs to an account, so this cannot be used to discover who has one. One code per address per 60 seconds.","operationId":"customerForgotPassword","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email`."}}}}}},"responses":{"200":{"description":"Accepted — the same answer for a known and an unknown address.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"If this email is registered, a reset code has been sent."}}}},"429":{"description":"A code was already requested for this address in the last 60 seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Please wait 60 seconds before requesting another code."}}}}}}},"/v1/customer/reset-password":{"post":{"tags":["Customer"],"summary":"Set a new customer password with the reset code","description":"Verifies the 6-digit code from POST /v1/customer/forgot-password and sets the new password. The code is single use and is discarded on success.","operationId":"customerResetPassword","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","code","password","password_confirmation"],"properties":{"email":{"type":"string","format":"email","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`, format `email`."},"code":{"type":"string","minLength":6,"maxLength":6,"description":"**Required.**\n\nStable machine code for this resource.\n\n**Details:** Type `string` · minLength `6` · maxLength `6`."},"password":{"type":"string","minLength":6,"description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string` · minLength `6`."},"password_confirmation":{"type":"string","description":"**Required.**\n\nMust match password.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"Password changed.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Password has been reset successfully."}}}},"404":{"description":"No customer account for this address.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"User not found."}}}},"422":{"description":"The code is wrong or has expired.","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Invalid or expired reset code."}}}}}}},"/v1/inventories/receive-decision":{"post":{"tags":["Inventories"],"summary":"Answer the third-party receive decision left open by an unattended receive","description":"Unattended receives (CSV inventory import, batch receive, API callers that send no third_party_action) keep the carrier and park the order at Waiting Third Party Handover, then raise a receive_decision_pending alert. This endpoint answers it. Idempotent: once the assignment no longer holds the order, the call reports the current state instead of acting again.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignment_no":{"type":"string","description":"Required. Third-party delivery assignment number.\n\n**Details:** Type `string`."},"action":{"type":"string","enum":["continue_handover","withdraw_self"],"description":"Required. continue_handover confirms the parked state; withdraw_self cancels at the carrier and returns the order to self-delivery.\n\nAllowed values: `continue_handover` · `withdraw_self`.\n\n**Details:** Type `string`."},"note":{"type":["string","null"],"description":"Optional note stored on the withdrawal.\n\n**Details:** Type `string` · Nullable."}},"required":["assignment_no","action"]},"example":{"assignment_no":"TPD20260805052757QZVP4E","action":"withdraw_self","note":"Parcel returned to our warehouse"}}},"required":true},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"orders_status_id":{"type":"integer","description":"Order lifecycle status id (`orders.orders_status_id`). Source: `OrdersStatusInput`.\n\nEnum values (from deployed code):\n- `1` — Need Update Address (`need_update_address`)\n- `2` — New Order (`new_order`)\n- `3` — Waiting To Plan (`waiting_to_plan`)\n- `4` — Planning (`planning`)\n- `5` — Already Planned (`already_planned`)\n- `6` — Plan Failed (`plan_failed`)\n- `14` — Already Pickup (`already_pickup`)\n- `8` — Successful (`successful`)\n- `9` — Redelivered Later (`redelivered_later`)\n- `10` — Need Rescheduled (`need_rescheduled`)\n- `11` — Rescheduled (`rescheduled`)\n- `12` — Cancelled (`cancelled`)\n- `16` — Need To Pick Up (`need_to_pick_up`)\n- `7` — Already Pickup (`already_pickup`)\n- `20` — Out For Delivery (`out_for_delivery`)\n- `21` — Out For Pickup (`out_for_pickup`)\n- `17` — Waiting For Self Pickup (`waiting_for_self_pickup`)\n- `19` — Return To Customer (`return_to_customer`)\n- `25` — Hand Off (`hand_off`)\n- `18` — Self Pickup Completed (`self_pickup_completed`)\n- `22` — Partial Received (`partial_received`)\n- `23` — Partial Delivered (`partial_delivered`)\n- `24` — Partial Pickuped (`partial_pickuped`)\n- `26` — Review (`review`)\n- `27` — Destroyed (`destroyed`)\n- `29` — In Transit (`in_transit`)\n- `30` — Package Lost (`package_lost`)\n- `31` — Package Damaged (`package_damaged`)\n- `32` — Waiting Customer Options (`waiting_customer_options`)\n- `33` — Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)\n- `34` — Waiting Batch Pickup (`waiting_batch_pickup`)\n- `28` — Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)\n- `35` — Payment Required (`payment_required`)\n- `36` — Bulk Transshipment Pending (`bulk_transshipment_pending`)\n- `37` — Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)\n- `38` — Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)\n- `39` — Inbound Scan Required (`inbound_scan_required`)\n- `40` — Rejected By Recipient (`rejected_by_recipient`)\n- `41` — Package Outbound (`package_outbound`)\n- `42` — Waiting For Quote (`waiting_for_quote`)\n- `43` — Waiting Third Party Handover (`waiting_third_party_handover`)\n- `44` — Waiting For Assignment (`waiting_for_assignment`)\n- `45` — Start Pickup (`start_pickup`)\n- `46` — Start Delivery (`start_delivery`)\n- `47` — Out Of Delivery Area (`out_of_delivery_area`)\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5,6,14,8,9,10,11,12,16,7,20,21,17,19,25,18,22,23,24,26,27,29,30,31,32,33,34,28,35,36,37,38,39,40,41,42,43,44,45,46,47],"x-enumDescriptions":["Need Update Address (`need_update_address`)","New Order (`new_order`)","Waiting To Plan (`waiting_to_plan`)","Planning (`planning`)","Already Planned (`already_planned`)","Plan Failed (`plan_failed`)","Already Pickup (`already_pickup`)","Successful (`successful`)","Redelivered Later (`redelivered_later`)","Need Rescheduled (`need_rescheduled`)","Rescheduled (`rescheduled`)","Cancelled (`cancelled`)","Need To Pick Up (`need_to_pick_up`)","Already Pickup (`already_pickup`)","Out For Delivery (`out_for_delivery`)","Out For Pickup (`out_for_pickup`)","Waiting For Self Pickup (`waiting_for_self_pickup`)","Return To Customer (`return_to_customer`)","Hand Off (`hand_off`)","Self Pickup Completed (`self_pickup_completed`)","Partial Received (`partial_received`)","Partial Delivered (`partial_delivered`)","Partial Pickuped (`partial_pickuped`)","Review (`review`)","Destroyed (`destroyed`)","In Transit (`in_transit`)","Package Lost (`package_lost`)","Package Damaged (`package_damaged`)","Waiting Customer Options (`waiting_customer_options`)","Handed Over To The Third Party Carrier (`handed_over_to_the_third_party_carrier`)","Waiting Batch Pickup (`waiting_batch_pickup`)","Need Convert To 3rd Party Label (`need_convert_to_3rd_party_label`)","Payment Required (`payment_required`)","Bulk Transshipment Pending (`bulk_transshipment_pending`)","Bulk Transshipment In Transit (`bulk_transshipment_in_transit`)","Bulk Transshipment Pending Inbound (`bulk_transshipment_pending_inbound`)","Inbound Scan Required (`inbound_scan_required`)","Rejected By Recipient (`rejected_by_recipient`)","Package Outbound (`package_outbound`)","Waiting For Quote (`waiting_for_quote`)","Waiting Third Party Handover (`waiting_third_party_handover`)","Waiting For Assignment (`waiting_for_assignment`)","Start Pickup (`start_pickup`)","Start Delivery (`start_delivery`)","Out Of Delivery Area (`out_of_delivery_area`)"]},"assignment_no":{"type":"string","description":"Assignment no. Field in the JSON request body.\n\n**Details:** Type `string`."},"assignment_status":{"type":"string","description":"Assignment status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`."},"applied":{"type":["string","null"],"description":"Null when nothing was left to decide.\n\n**Details:** Type `string` · Nullable."}}},"example":{"result":true,"message":"Third-party receive decision applied.","order_id":1580756,"orders_status_id":2,"assignment_no":"TPD20260805052757QZVP4E","assignment_status":"cancelled","applied":"withdraw_self"}}}},"400":{"description":"Unknown action, missing assignment_no, or the carrier withdrawal failed"},"404":{"description":"Assignment not found for this business"}}}},"/v1/reservations/slots":{"get":{"tags":["Reservations"],"summary":"List bookable slots","description":"Public. Returns start times for a venue slug and date.","security":[],"operationId":"reservationSlots","parameters":[{"name":"slug","in":"query","required":true,"schema":{"type":"string","description":"Slug. Stable machine-readable code.\n\n**Details:** Required · Type `string`.\n\n**Example:** `venue-200`."},"example":"venue-200","description":"Slug. Stable machine-readable code.\n\n**Details:** Required · Type `string`.\n\n**Example:** `venue-200`."},{"name":"date","in":"query","required":true,"schema":{"type":"string","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Required · Type `string`.\n\n**Example:** `2026-08-19`."},"example":"2026-08-19","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Required · Type `string`.\n\n**Example:** `2026-08-19`."},{"name":"party_size","in":"query","required":false,"schema":{"type":"integer","description":"Party size. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `2`."},"example":2,"description":"Party size. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `2`."}],"responses":{"200":{"description":"Slots","content":{"application/json":{"schema":{"type":"object"},"example":{"success":true,"message":null,"reason":null,"date":"2026-08-19","timezone":"America/Toronto","large_party":false,"slots":[{"time":"18:00","available":true,"duration":90},{"time":"18:30","available":false,"duration":90}],"reservation":null}}}}}}},"/v1/reservations/hold":{"post":{"tags":["Reservations"],"summary":"Hold a slot","description":"Public short hold.","security":[],"operationId":"reservationHold","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","date","time"],"properties":{"slug":{"type":"string","description":"**Required.**\n\nSlug. Stable machine-readable code.\n\n**Details:** Type `string`."},"date":{"type":"string","description":"**Required.**\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`."},"time":{"type":"string","description":"**Required.**\n\nTime. Field in the JSON request body.\n\n**Details:** Type `string`."},"party_size":{"type":"integer","description":"Party size. Field in the JSON request body.\n\n**Details:** Type `integer`."}}}}}},"responses":{"201":{"description":"Held"},"422":{"description":"Unavailable"}}}},"/v1/reservations/confirm":{"post":{"tags":["Reservations"],"summary":"Confirm a hold","description":"Public confirm with guest details.","security":[],"operationId":"reservationConfirm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hold_code","name"],"properties":{"hold_code":{"type":"string","description":"**Required.**\n\nHold code. Stable machine-readable code.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`."},"phone":{"type":"string","description":"Phone number used for OTP or contact.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"Confirmed"},"422":{"description":"Rejected"}}}},"/v1/reservations/waitlist":{"post":{"tags":["Reservations"],"summary":"Join waitlist","description":"Public waitlist join.","security":[],"operationId":"reservationWaitlistJoin","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","name","party_size"],"properties":{"slug":{"type":"string","description":"**Required.**\n\nSlug. Stable machine-readable code.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`."},"party_size":{"type":"integer","description":"**Required.**\n\nParty size. Field in the JSON request body.\n\n**Details:** Type `integer`."},"phone":{"type":"string","description":"Phone number used for OTP or contact.\n\n**Details:** Type `string`."}}}}}},"responses":{"201":{"description":"Joined"},"422":{"description":"Rejected"}}}},"/v1/reservations/{code}":{"get":{"tags":["Reservations"],"summary":"Reservation status","description":"Public status by unique code.","security":[],"operationId":"reservationStatus","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."},"description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Found"},"404":{"description":"Not found"}}}},"/v1/reservations/{code}/cancel":{"post":{"tags":["Reservations"],"summary":"Cancel reservation","description":"Guest cancel. Seated/checked-in refused.","security":[],"operationId":"reservationCancel","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."},"description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"Cancelled"},"422":{"description":"Refused"}}}},"/v1/reservations/{code}/reply":{"post":{"tags":["Reservations"],"summary":"Waitlist reply","description":"on_the_way / need_more_time / arrived / cancel.","security":[],"operationId":"reservationReply","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."},"description":"Stable machine code for this resource.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","description":"**Required.**\n\nAction. Field in the JSON request body.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"Updated"},"422":{"description":"Refused"}}}},"/v1/host/venues":{"get":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostVenues","summary":"Venues this staff account may run","description":"The venues the signed-in account can already open in the store console, with the reservation module switched on. The tablet asks for this once, at login.","responses":{"200":{"description":"Venue list"},"401":{"description":"Not signed in"}}}},"/v1/host/{storeId}/waitlist":{"get":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostWaitlistBoard","summary":"Walk-in queue, tables and counters","description":"Everything the host stand paints in one pass: the waiting parties in arrival order, every table with its live state, the counters, and a signature to poll with when MQTT is unavailable. Times are rendered in the venue timezone.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}}],"responses":{"200":{"description":"Board"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"}}},"post":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostWaitlistJoin","summary":"Add a walk-in party","description":"Registers a party standing at the host stand. A number already waiting comes back marked duplicate rather than queued twice.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","party_size"],"properties":{"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`."},"party_size":{"type":"integer","description":"**Required.**\n\nParty size. Field in the JSON request body.\n\n**Details:** Type `integer`."},"phone":{"type":"string","description":"Mobile number for the call-back text\n\n**Details:** Type `string`."},"zone_id":{"type":"integer","description":"Zone id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"notes":{"type":"string","description":"Free-text notes.\n\n**Details:** Type `string`."},"idempotency_key":{"type":"string","description":"Replay key for a write queued offline\n\n**Details:** Type `string`."}}}}}},"responses":{"201":{"description":"Joined (check \"duplicate\")"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"},"422":{"description":"Rejected"}}}},"/v1/host/{storeId}/waitlist/{id}/action":{"post":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostWaitlistEntryAction","summary":"Act on one waiting party","description":"notify_nearly, notify_ready, arrived, seat, delay, late, skip, no_show, complete, cancel, undo. Skip, no-show and cancel need a reason. Seating takes a table: pass resource_id to choose one, or let the first fitting free table be used.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}},{"name":"id","in":"path","required":true,"description":"Waiting party id\n\nResource identifier.\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Waiting party id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["notify_nearly","notify_ready","arrived","seat","delay","late","skip","no_show","complete","cancel","undo","remove"],"description":"**Required.**\n\nAllowed values: `notify_nearly` · `notify_ready` · `arrived` · `seat` · `delay` · `late` · `skip` · `no_show` · `complete` · `cancel` · `undo` · `remove`.\n\n**Details:** Type `string`."},"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."},"resource_id":{"type":"integer","description":"Resource id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"unlock_token":{"type":"string","description":"Optional manager-mode proof for `remove`: the settings-unlock token the tablet holds. Needed when the signed-in account is not a venue manager; venue managers succeed without it.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"New status"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"},"404":{"description":"No such party"},"422":{"description":"Refused (reason given)"}}}},"/v1/host/{storeId}/tables/{resourceId}/action":{"post":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostTableAction","summary":"Act on one table","description":"available, blocked, out_of_service, seat_next or free. seat_next seats the first waiting party that fits; a table an upcoming booking needs is never handed to a walk-in, and when nobody can sit there the call is refused.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}},{"name":"resourceId","in":"path","required":true,"description":"Table (reservation resource) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Table (reservation resource) id\n\n**Details:** Required · Type `integer`."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["available","blocked","out_of_service","seat_next","free"],"description":"**Required.**\n\nAllowed values: `available` · `blocked` · `out_of_service` · `seat_next` · `free`.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"Applied"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"},"404":{"description":"No such table"},"422":{"description":"Refused (reason given)"}}}},"/v1/host/{storeId}/realtime":{"get":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostRealtime","summary":"MQTT credentials for this device","description":"Broker address, a short-lived token and the venue topic the reservation services publish to. The token may only listen to this venue. When the realtime layer is off the credentials are null and the app polls the board every poll_seconds instead.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}}],"responses":{"200":{"description":"Credentials or null + poll interval"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"}}}},"/v1/host/{storeId}/bookings":{"get":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostBookingBoard","summary":"One day of bookings with its counters","description":"The day's bookings and large-party requests in time order, each with the statuses it may move to next, plus the counters and a signature to poll with. Times are rendered in the venue's timezone.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}},{"name":"date","in":"query","required":false,"description":"Venue-local Y-m-d; today at the venue by default\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","description":"Venue-local Y-m-d; today at the venue by default\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Optional · Type `string`."}}],"responses":{"200":{"description":"Board"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"}}},"post":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostBookingCreate","summary":"Take a booking on behalf of a guest","description":"A booking taken over the telephone or at the door: the online lead time and the large-party threshold do not apply, and a table may be pinned. A repeated idempotency key returns the original booking marked duplicate.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date","time","party_size","name"],"properties":{"date":{"type":"string","description":"**Required.**\n\nVenue-local Y-m-d\n\n**Details:** Type `string`."},"time":{"type":"string","description":"**Required.**\n\nVenue-local H:i\n\n**Details:** Type `string`."},"party_size":{"type":"integer","description":"**Required.**\n\nParty size. Field in the JSON request body.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`."},"phone":{"type":"string","description":"Phone number used for OTP or contact.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"service_id":{"type":"integer","description":"Service id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"zone_id":{"type":"integer","description":"Zone id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"resource_id":{"type":"integer","description":"Pin a specific table\n\n**Details:** Type `integer`."},"notes":{"type":"string","description":"Free-text notes.\n\n**Details:** Type `string`."},"occasion":{"type":"string","description":"Occasion. Field in the JSON request body.\n\n**Details:** Type `string`."},"source":{"type":"string","enum":["phone","walk_in","staff"],"description":"Document or data source selector for this developer-center export.\n\nAllowed values: `phone` · `walk_in` · `staff`.\n\n**Details:** Type `string`."},"idempotency_key":{"type":"string","description":"Idempotency key. Stable machine-readable code.\n\n**Details:** Type `string`."}}}}}},"responses":{"201":{"description":"Booking taken (check \"duplicate\")"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"},"422":{"description":"Refused (reason given)"}}}},"/v1/host/{storeId}/bookings/{id}/transition":{"post":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostBookingTransition","summary":"Move one booking to its next status","description":"confirmed (a large-party request takes its tables here), checked_in, seated, completed, no_show or cancelled. Only the statuses listed in the booking's own actions are accepted; cancel and no-show take a reason, and the guest is notified exactly as from the web console.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}},{"name":"id","in":"path","required":true,"description":"Booking id\n\nResource identifier.\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Booking id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["confirmed","checked_in","seated","completed","no_show","cancelled"],"description":"**Required.**\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `confirmed` · `checked_in` · `seated` · `completed` · `no_show` · `cancelled`.\n\n**Details:** Type `string`."},"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"The booking in its new status"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"},"404":{"description":"No such booking"},"422":{"description":"Refused (reason given)"}}}},"/v1/host/{storeId}/search":{"get":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostBookingSearch","summary":"Find bookings by code, name, phone or e-mail","description":"Searches every booking of the venue, past and future. The booking code matches exactly; the phone number is compared digit by digit, so it can be typed any way. Returns at most 50 matches and says when more exist.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}},{"name":"q","in":"query","required":true,"description":"Booking code, guest name, phone number or e-mail\n\n**Details:** Required · Type `string`.","schema":{"type":"string","description":"Booking code, guest name, phone number or e-mail\n\n**Details:** Required · Type `string`."}}],"responses":{"200":{"description":"Matches"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"}}}},"/v1/host/{storeId}/settings":{"get":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostTabletSettings","summary":"What this venue’s tablets show","description":"Which halves — the walk-in queue, the bookings — the SuperBooking tablets at this venue show, together with what the venue is actually capable of, so a device never offers a half the venue does not run. The setting belongs to the venue, so several stands stay in step; it is also returned with every board.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}}],"responses":{"200":{"description":"Settings"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"}}},"post":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostTabletSettingsSave","summary":"Change what the tablets show","description":"Needs an unlock token from the unlock endpoint. At least one half must stay on — a device showing neither is a black screen at the host stand. Every other tablet at the venue is told at once over MQTT.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["unlock_token","show_waitlist","show_bookings"],"properties":{"unlock_token":{"type":"string","description":"**Required.**\n\nUnlock token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."},"show_waitlist":{"type":"boolean","description":"**Required.**\n\nShow waitlist. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"show_bookings":{"type":"boolean","description":"**Required.**\n\nShow bookings. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}}}}},"responses":{"200":{"description":"Saved settings"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"},"422":{"description":"Unlock expired, or both halves switched off"}}}},"/v1/host/{storeId}/settings/unlock":{"post":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostTabletSettingsUnlock","summary":"Open the tablet settings with a manager’s password","description":"The device is already signed in; this asks who is standing at it. Accepts the venue owner's credentials or those of one of that owner's sub-accounts, and returns a short-lived unlock token. A wrong password and an account that may not open these settings are answered identically, and the endpoint is throttled far harder than the rest of this surface.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","description":"**Required.**\n\nAccount email address.\n\n**Details:** Type `string`."},"password":{"type":"string","description":"**Required.**\n\nAccount password (never logged or returned by the API).\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"Unlock token and how long it lasts"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"},"422":{"description":"Refused"},"429":{"description":"Too many attempts"}}}},"/v1/host/{storeId}/waitlist/{id}/position":{"post":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostWaitlistReorder","summary":"Move a waiting party up or down the queue","description":"The position is the zero-based place in the queue as displayed. Joining times are never rewritten, so the waited minutes stay true, and a party who joins afterwards still lands at the back. Returns the reordered board.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}},{"name":"id","in":"path","required":true,"description":"Waiting party id\n\nResource identifier.\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Waiting party id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["position"],"properties":{"position":{"type":"integer","minimum":0,"description":"**Required.**\n\nPosition. Field in the JSON request body.\n\n**Details:** Type `integer` · min `0`."},"unlock_token":{"type":"string","description":"Optional manager-mode proof: the settings-unlock token the tablet holds. Needed when the signed-in account is not a venue manager; venue managers succeed without it.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"The reordered board"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"},"404":{"description":"No such party"}}}},"/v1/host/{storeId}/bookings/{id}/modify":{"post":{"tags":["Reservations"],"security":[{"bearerAuth":[]}],"operationId":"hostBookingModify","summary":"Move a booking to another time and/or table","description":"The same move the timeline makes. An overlap, a blocked table or a party over the table's capacity is refused. A doubtful move answers 409 with needs_confirmation and the reasons; send it again with confirm_anyway and a reason. The guest is told when their time changes.","parameters":[{"name":"storeId","in":"path","required":true,"description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Venue (merchant store) id\n\n**Details:** Required · Type `integer`."}},{"name":"id","in":"path","required":true,"description":"Booking id\n\nResource identifier.\n\n**Details:** Required · Type `integer`.","schema":{"type":"integer","description":"Booking id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","description":"Venue-local Y-m-d; send with time\n\n**Details:** Type `string`."},"time":{"type":"string","description":"Venue-local H:i; send with date\n\n**Details:** Type `string`."},"resource_id":{"type":"integer","description":"Resource id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"confirm_anyway":{"type":"boolean","description":"Confirm anyway. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."},"unlock_token":{"type":"string","description":"Optional manager-mode proof for confirm_anyway: the settings-unlock token the tablet holds. Needed when the signed-in account is not a venue manager; venue managers succeed without it.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"The moved booking"},"409":{"description":"Doubtful move: confirm with a reason"},"401":{"description":"Not signed in"},"403":{"description":"The account may not run this venue"},"404":{"description":"No such booking"},"422":{"description":"Refused, or nothing to change"}}}},"/v1/third-party-delivery/usage/summary":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Usage summary for the authenticated provider","description":"Deliveries created, placed, cancelled, expired and failed, packages placed and collected, door failures and how long parcels occupied a compartment, over the selected period. Reports only this provider's own activity: no occupancy of the operator's lockers, no other provider's volume, and recipient counts are withheld below the privacy threshold (returned as null).","operationId":"partnerLockerUsageSummary","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"date_from","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD. Defaults to 28 days before date_to. Ranges longer than 92 days are clamped to the most recent 92.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"YYYY-MM-DD. Defaults to 28 days before date_to. Ranges longer than 92 days are clamped to the most recent 92.\n\n**Details:** Optional · Type `string`, format `date`."},{"in":"query","name":"date_to","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"YYYY-MM-DD. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},{"in":"query","name":"location_id","required":false,"schema":{"type":"integer","description":"Narrow the report to one locker location.\n\n**Details:** Optional · Type `integer`."},"description":"Narrow the report to one locker location.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Usage summary","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Usage summary retrieved.","data":{"provider_id":5,"summary":{"from":"2026-07-27","to":"2026-08-23","days":28,"locations_used":6,"deliveries_created":420,"deliveries_placed":404,"deliveries_cancelled":9,"deliveries_expired":5,"deliveries_failed":2,"placement_rate_pct":96,"packages_placed":511,"packages_picked_up":488,"collection_rate_pct":95,"door_opens":810,"door_failure_pct":1,"dwell_avg_hours":19.4,"dwell_p90_hours":41,"recipient_visits":377}}}}}},"403":{"description":"LOCKER_PERMISSION_DENIED"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/usage/daily":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Day-by-day usage for the authenticated provider","description":"The same volume broken down by day, each figure counted on the day the thing actually happened. Reports only this provider's own activity: no occupancy of the operator's lockers, no other provider's volume, and recipient counts are withheld below the privacy threshold (returned as null).","operationId":"partnerLockerUsageDaily","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"date_from","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD. Defaults to 28 days before date_to. Ranges longer than 92 days are clamped to the most recent 92.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"YYYY-MM-DD. Defaults to 28 days before date_to. Ranges longer than 92 days are clamped to the most recent 92.\n\n**Details:** Optional · Type `string`, format `date`."},{"in":"query","name":"date_to","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"YYYY-MM-DD. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},{"in":"query","name":"location_id","required":false,"schema":{"type":"integer","description":"Narrow the report to one locker location.\n\n**Details:** Optional · Type `integer`."},"description":"Narrow the report to one locker location.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Daily usage","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Daily usage retrieved.","data":{"provider_id":5,"from":"2026-08-17","to":"2026-08-23","days":[{"date":"2026-08-17","deliveries_created":61,"deliveries_placed":59,"deliveries_failed":0,"packages_placed":74,"packages_picked_up":70,"dwell_avg_hours":18.2}]}}}}},"403":{"description":"LOCKER_PERMISSION_DENIED"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/third-party-delivery/usage/locations":{"get":{"tags":["ThirdPartyDelivery"],"summary":"Usage by locker location for the authenticated provider","description":"Where this provider's parcels went, with each location's name and town, its collection rate, door failures and average dwell. Reports only this provider's own activity: no occupancy of the operator's lockers, no other provider's volume, and recipient counts are withheld below the privacy threshold (returned as null).","operationId":"partnerLockerUsageLocations","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"X-Third-Party-Provider-Id","required":false,"schema":{"type":"integer","description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},"description":"Required when the authenticated account can access multiple providers.\n\nThird-party delivery provider id (header). Identifies which external carrier / partner integration the request is for.\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"date_from","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD. Defaults to 28 days before date_to. Ranges longer than 92 days are clamped to the most recent 92.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"YYYY-MM-DD. Defaults to 28 days before date_to. Ranges longer than 92 days are clamped to the most recent 92.\n\n**Details:** Optional · Type `string`, format `date`."},{"in":"query","name":"date_to","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"YYYY-MM-DD. Defaults to today.\n\n**Details:** Optional · Type `string`, format `date`."}],"responses":{"200":{"description":"Usage by location","content":{"application/json":{"example":{"result":true,"code":"OK","message":"Usage by location retrieved.","data":{"provider_id":5,"from":"2026-07-27","to":"2026-08-23","locations":[{"location_id":88,"name":"Queen Street Point","city":"Toronto","province":"ON","country":"Canada","deliveries_placed":142,"deliveries_failed":1,"packages_placed":180,"packages_picked_up":174,"collection_rate_pct":97,"door_failure_pct":1,"dwell_avg_hours":17.8,"recipient_visits":131},{"location_id":91,"name":"Airport Point","city":"Mississauga","province":"ON","country":"Canada","deliveries_placed":12,"deliveries_failed":0,"packages_placed":14,"packages_picked_up":13,"collection_rate_pct":93,"door_failure_pct":0,"dwell_avg_hours":22.1,"recipient_visits":null}]}}}}},"403":{"description":"LOCKER_PERMISSION_DENIED"},"429":{"description":"LOCKER_RATE_LIMITED; retry after the number of seconds in the Retry-After header"}}}},"/v1/driver/boards":{"get":{"tags":["Driver Route Board"],"summary":"List the Route Boards visible to the driver","description":"Boards of the driver's own pool (own fleet, or their contractor's) that are scheduled, open, filled or closed, dated today or later, and whose eligibility the driver passes. Each row carries the seat counts and the driver's own claims on it. A seat-mode (\"Grab a Seat\") board additionally carries capacity / quota_taken / my_pooled / settled.","responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"title":{"type":"string","description":"Title. Human-readable label.\n\n**Details:** Type `string`."},"date":{"type":"string","format":"date","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`."},"mode":{"type":"string","enum":["route","seat","bid"],"description":"Allowed values: `route` · `seat` · `bid`.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["scheduled","open","filled","closed"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `scheduled` · `open` · `filled` · `closed`.\n\n**Details:** Type `string`."},"opens_at":{"type":["string","null"],"description":"Opens at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"closes_at":{"type":["string","null"],"description":"Closes at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"is_open":{"type":"boolean","description":"Is open. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"seats":{"type":"integer","description":"Seats. Field in the JSON request body.\n\n**Details:** Type `integer`."},"open_seats":{"type":"integer","description":"Open seats. Field in the JSON request body.\n\n**Details:** Type `integer`."},"standby_limit":{"type":"integer","description":"Standby limit. Field in the JSON request body.\n\n**Details:** Type `integer`."},"withdraw_policy":{"type":"string","enum":["allowed","denied","until_cutoff"],"description":"Allowed values: `allowed` · `denied` · `until_cutoff`.\n\n**Details:** Type `string`."},"withdraw_cutoff_hours":{"type":["integer","null"],"description":"Withdraw cutoff hours. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"my_primary":{"type":"integer","description":"My primary. Field in the JSON request body.\n\n**Details:** Type `integer`."},"my_standby":{"type":"integer","description":"My standby. Field in the JSON request body.\n\n**Details:** Type `integer`."},"my_pooled":{"type":"integer","description":"Seat-mode boards: 1 when the caller holds a pooled seat on this board\n\n**Details:** Type `integer`."},"capacity":{"type":["integer","null"],"description":"Seat-mode boards: number of seats that can be grabbed (seats, or seats x (1 + standby_limit) for the over seat type); null in route mode\n\n**Details:** Type `integer` · Nullable."},"quota_taken":{"type":["integer","null"],"description":"Seat-mode boards: pooled seats already taken; null in route mode\n\n**Details:** Type `integer` · Nullable."},"settled":{"type":"boolean","description":"True once the dispatcher has handed out the vehicles (seat mode)\n\n**Details:** Type `boolean`."},"my_bidding":{"type":"integer","description":"Number of my live bids on this board\n\n**Details:** Type `integer`."},"bid_count":{"type":["integer","null"],"description":"Bid mode: number of live bids on the board; null otherwise\n\n**Details:** Type `integer` · Nullable."},"bid_visibility":{"type":["string","null"],"enum":["open","sealed",null],"description":"Allowed values: `open` · `sealed`.\n\n**Details:** Type `string` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"message":"Successful","data":[{"id":12,"title":"Route Board 2026-03-04","date":"2026-03-04","mode":"route","status":"open","opens_at":"2026-03-03T18:00:00+00:00","closes_at":"2026-03-04T05:00:00+00:00","is_open":true,"seats":8,"open_seats":3,"standby_limit":2,"withdraw_policy":"until_cutoff","withdraw_cutoff_hours":12,"my_primary":1,"my_standby":0,"my_pooled":0,"capacity":null,"quota_taken":null,"settled":false},{"id":13,"title":"Saturday pool","date":"2026-03-07","mode":"seat","status":"open","opens_at":"2026-03-06T18:00:00+00:00","closes_at":"2026-03-07T05:00:00+00:00","is_open":true,"seats":6,"open_seats":6,"standby_limit":1,"withdraw_policy":"allowed","withdraw_cutoff_hours":null,"my_primary":0,"my_standby":0,"my_pooled":1,"capacity":12,"quota_taken":7,"settled":false}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"The account has no driver profile","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"No driver profile is linked to this account."}}}}},"security":[{"bearerAuth":[]}]}},"/v1/driver/boards/{id}":{"get":{"tags":["Driver Route Board"],"summary":"Get one Route Board with its seats","description":"The board as this driver sees it: every seat with the queue length, the driver's own claim, whether the driver can claim right now and, if not, why (blocked_reason). A board of another pool answers 404. On a seat-mode (\"Grab a Seat\") board data.board.quota describes the pool (capacity, taken, remaining, the caller's pooled claim and whether it can grab now); the seats are then a read-only preview (claimable false, blocked_reason \"seat_mode\") because vehicles are handed out by the dispatcher when the board closes.","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The board ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The board ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"board":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"title":{"type":"string","description":"Title. Human-readable label.\n\n**Details:** Type `string`."},"date":{"type":"string","format":"date","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`, format `date`."},"mode":{"type":"string","enum":["route","seat","bid"],"description":"Allowed values: `route` · `seat` · `bid`.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["scheduled","open","filled","closed"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `scheduled` · `open` · `filled` · `closed`.\n\n**Details:** Type `string`."},"opens_at":{"type":["string","null"],"description":"Opens at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"closes_at":{"type":["string","null"],"description":"Closes at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"is_open":{"type":"boolean","description":"Is open. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"seats":{"type":"integer","description":"Seats. Field in the JSON request body.\n\n**Details:** Type `integer`."},"open_seats":{"type":"integer","description":"Open seats. Field in the JSON request body.\n\n**Details:** Type `integer`."},"standby_limit":{"type":"integer","description":"Standby limit. Field in the JSON request body.\n\n**Details:** Type `integer`."},"withdraw_policy":{"type":"string","enum":["allowed","denied","until_cutoff"],"description":"Allowed values: `allowed` · `denied` · `until_cutoff`.\n\n**Details:** Type `string`."},"withdraw_cutoff_hours":{"type":["integer","null"],"description":"Withdraw cutoff hours. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"my_primary":{"type":"integer","description":"My primary. Field in the JSON request body.\n\n**Details:** Type `integer`."},"my_standby":{"type":"integer","description":"My standby. Field in the JSON request body.\n\n**Details:** Type `integer`."},"max_primary_per_driver":{"type":"integer","description":"Max primary per driver. Field in the JSON request body.\n\n**Details:** Type `integer`."},"quota":{"type":["object","null"],"description":"Seat-mode boards only; null in route mode\n\n**Details:** Type `object` · Nullable.","properties":{"seat_type":{"type":"string","enum":["exact","over"],"description":"exact = one seat per vehicle; over = seats plus standby places\n\nAllowed values: `exact` · `over`.\n\n**Details:** Type `string`."},"standby_scope":{"type":"string","enum":["global","per_seat"],"description":"Allowed values: `global` · `per_seat`.\n\n**Details:** Type `string`."},"capacity":{"type":"integer","description":"Capacity. Address component used for geocoding and delivery.\n\n**Details:** Type `integer`."},"taken":{"type":"integer","description":"Taken. Field in the JSON request body.\n\n**Details:** Type `integer`."},"remaining":{"type":"integer","description":"Remaining. Field in the JSON request body.\n\n**Details:** Type `integer`."},"seats":{"type":"integer","description":"Vehicles on the board\n\n**Details:** Type `integer`."},"settled":{"type":"boolean","description":"Settled. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"my_claim":{"type":["object","null"],"description":"The caller's pooled / global-standby claim (same shape as a claim row)\n\n**Details:** Type `object` · Nullable."},"claimable":{"type":"boolean","description":"Claimable. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"blocked_reason":{"type":["string","null"],"enum":["full","settled","not_open",null],"description":"Allowed values: `full` · `settled` · `not_open`.\n\n**Details:** Type `string` · Nullable."}}},"bid_visibility":{"type":["string","null"],"enum":["open","sealed",null],"description":"Bid mode only\n\nAllowed values: `open` · `sealed`.\n\n**Details:** Type `string` · Nullable."},"award_method":{"type":["string","null"],"enum":["lowest","manual",null],"description":"Bid mode only\n\nAllowed values: `lowest` · `manual`.\n\n**Details:** Type `string` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `CAD`.","examples":["CAD"]},"settled":{"type":"boolean","description":"Settled. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Board. Field in the JSON request body.\n\n**Details:** Type `object`."},"seats":{"type":"array","items":{"type":"object","properties":{"seat_id":{"type":"integer","description":"Seat id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"status":{"type":"string","enum":["open","filled","locked"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `open` · `filled` · `locked`.\n\n**Details:** Type `string`."},"snapshot":{"type":"object","description":"Publish-time display snapshot of the vehicle slot. start/end/stops are omitted while the board masks previews.\n\n**Details:** Type `object`.","properties":{"route_name":{"type":"string","description":"Route name. Human-readable label.\n\n**Details:** Type `string`."},"date":{"type":"string","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`."},"work_from":{"type":"string","description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string`."},"work_end":{"type":"string","description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string`."},"vehicle_type":{"type":["string","null"],"description":"Vehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string` · Nullable.","enum":[1,2,3,4,5,null],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"]},"distance":{"type":["number","null"],"description":"Distance. Field in the JSON request body.\n\n**Details:** Type `number` · Nullable."},"stops":{"type":["integer","null"],"description":"Stops. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"start":{"type":["string","null"],"description":"Start. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"end":{"type":["string","null"],"description":"End. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}},"primary_taken":{"type":"boolean","description":"Primary taken. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"standby_taken":{"type":"integer","description":"Standby taken. Field in the JSON request body.\n\n**Details:** Type `integer`."},"standby_limit":{"type":"integer","description":"Standby limit. Field in the JSON request body.\n\n**Details:** Type `integer`."},"next_rank":{"type":["integer","null"],"description":"Rank the caller would get by claiming now; null when full\n\n**Details:** Type `integer` · Nullable."},"my_claim":{"type":["object","null"],"properties":{"claim_id":{"type":"integer","description":"Claim id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"board_id":{"type":"integer","description":"Board id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"board_title":{"type":"string","description":"Board title. Human-readable label.\n\n**Details:** Type `string`."},"seat_id":{"type":["integer","null"],"description":"Seat id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"route_name":{"type":"string","description":"Route name. Human-readable label.\n\n**Details:** Type `string`."},"date":{"type":"string","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"work_end":{"type":["string","null"],"description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"rank":{"type":"integer","description":"1 = driver, 2.. = standby position + 1\n\n**Details:** Type `integer`."},"status":{"type":"string","enum":["pooled","primary","standby","withdrawn","vetoed","replaced","displaced","skipped","expired","completed","bidding","lost"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pooled` · `primary` · `standby` · `withdrawn` · `vetoed` · `replaced` · `displaced` · `skipped` · `expired` · `completed` · `bidding` · `lost`.\n\n**Details:** Type `string`."},"is_active":{"type":"boolean","description":"Is active. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."},"claimed_at":{"type":"string","description":"Claimed at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"decided_at":{"type":["string","null"],"description":"Decided at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"can_withdraw":{"type":"boolean","description":"Can withdraw. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"withdraw_blocker":{"type":["string","null"],"description":"Lang key explaining why withdrawing is refused\n\n**Details:** Type `string` · Nullable."},"withdraw_deadline":{"type":["string","null"],"description":"Y-m-d H:i, only for a primary claim under the until_cutoff policy\n\n**Details:** Type `string` · Nullable."},"is_pooled":{"type":"boolean","description":"True for a seat-mode pooled claim (no vehicle yet)\n\n**Details:** Type `boolean`."},"global_standby":{"type":"boolean","description":"True for a standby claim that waits for any vehicle (seat mode, global standby scope)\n\n**Details:** Type `boolean`."},"is_bid":{"type":"boolean","description":"True while the claim is a live bid (status bidding) on a bid-mode board\n\n**Details:** Type `boolean`."},"bid_price":{"type":["number","null"],"description":"Bid mode: the price the driver named\n\n**Details:** Type `number` · Nullable."},"awarded_price":{"type":["number","null"],"description":"Bid mode: the price the route was awarded at (primary claims)\n\n**Details:** Type `number` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `CAD`.","examples":["CAD"]}},"description":"My claim. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"claimable":{"type":"boolean","description":"Claimable. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"blocked_reason":{"type":["string","null"],"enum":["time_conflict","max_primary","full","locked","not_open","seat_mode","bid_mode",null],"description":"Why the caller cannot claim this seat right now; seat_mode = read-only preview on a Grab-a-Seat board; bid_mode = the seat is auctioned, use POST /v1/driver/boards/{id}/bid\n\nAllowed values: `time_conflict` · `max_primary` · `full` · `locked` · `not_open` · `seat_mode` · `bid_mode`.\n\n**Details:** Type `string` · Nullable."},"bid":{"type":["object","null"],"description":"Bid mode only (null on route / seat boards): the reverse-auction state of this seat for the caller.\n\n**Details:** Type `object` · Nullable.","properties":{"visibility":{"type":"string","enum":["open","sealed"],"description":"open = the current lowest bid (not who) is shown; sealed = only the bid count\n\nAllowed values: `open` · `sealed`.\n\n**Details:** Type `string`."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `CAD`.","examples":["CAD"]},"reference_price":{"type":["number","null"],"description":"The dispatcher's reference pay for this route\n\n**Details:** Type `number` · Nullable."},"ceiling_price":{"type":["number","null"],"description":"Highest accepted bid; a bid above it is refused (422)\n\n**Details:** Type `number` · Nullable."},"instant_price":{"type":["number","null"],"description":"A bid at or under this price wins the route immediately\n\n**Details:** Type `number` · Nullable."},"bid_count":{"type":"integer","description":"Bid count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"lowest":{"type":["number","null"],"description":"Current lowest bid; only on open boards, null when sealed or no bids\n\n**Details:** Type `number` · Nullable."},"my_bid":{"type":["number","null"],"description":"My bid. Identifier referencing the related record.\n\n**Details:** Type `number` · Nullable."},"my_claim_id":{"type":["integer","null"],"description":"My claim id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"my_position":{"type":["integer","null"],"description":"1 = my bid is the lowest; only on open boards\n\n**Details:** Type `integer` · Nullable."},"allow_rebid":{"type":"boolean","description":"Whether a placed bid may be lowered again\n\n**Details:** Type `boolean`."},"min_bid_step":{"type":"number","description":"A lowered bid must be at least this much under the previous one\n\n**Details:** Type `number`."},"can_bid":{"type":"boolean","description":"Can bid. Identifier referencing the related record.\n\n**Details:** Type `boolean`."},"blocked_reason":{"type":["string","null"],"enum":["settled","not_open","awarded","rebid_denied",null],"description":"Allowed values: `settled` · `not_open` · `awarded` · `rebid_denied`.\n\n**Details:** Type `string` · Nullable."}}}}},"description":"Seats. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"message":"Successful","data":{"board":{"id":12,"title":"Route Board 2026-03-04","date":"2026-03-04","mode":"route","status":"open","is_open":true,"opens_at":"2026-03-03T18:00:00+00:00","closes_at":"2026-03-04T05:00:00+00:00","standby_limit":2,"withdraw_policy":"until_cutoff","withdraw_cutoff_hours":12,"max_primary_per_driver":1,"my_primary":0,"quota":null},"seats":[{"seat_id":41,"route_id":9001,"status":"open","snapshot":{"route_name":"East-3","date":"2026-03-04","work_from":"07:00","work_end":"15:00","vehicle_type":"Van","distance":68,"stops":42,"start":"Scarborough","end":"Markham"},"primary_taken":false,"standby_taken":0,"standby_limit":2,"next_rank":1,"my_claim":null,"claimable":true,"blocked_reason":null},{"seat_id":42,"route_id":9002,"status":"filled","snapshot":{"route_name":"East-5","date":"2026-03-04","work_from":"07:30","work_end":"15:30","vehicle_type":"Van","distance":55,"stops":38,"start":"Scarborough","end":"Markham"},"primary_taken":true,"standby_taken":1,"standby_limit":2,"next_rank":3,"my_claim":null,"claimable":true,"blocked_reason":null},{"seat_id":43,"route_id":9003,"status":"open","snapshot":{"route_name":"North-1","date":"2026-03-04","work_from":"06:30","work_end":"14:30","vehicle_type":"Van","distance":68,"stops":42,"start":"Scarborough","end":"Markham"},"primary_taken":false,"standby_taken":0,"standby_limit":2,"next_rank":1,"my_claim":null,"claimable":false,"blocked_reason":"time_conflict"}]}},"examples":{"route_mode":{"summary":"Pick a Route board","value":{"result":true,"message":"Successful","data":{"board":{"id":12,"title":"Route Board 2026-03-04","date":"2026-03-04","mode":"route","status":"open","is_open":true,"opens_at":"2026-03-03T18:00:00+00:00","closes_at":"2026-03-04T05:00:00+00:00","standby_limit":2,"withdraw_policy":"until_cutoff","withdraw_cutoff_hours":12,"max_primary_per_driver":1,"my_primary":0,"quota":null},"seats":[{"seat_id":41,"route_id":9001,"status":"open","snapshot":{"route_name":"East-3","date":"2026-03-04","work_from":"07:00","work_end":"15:00","vehicle_type":"Van","distance":68,"stops":42,"start":"Scarborough","end":"Markham"},"primary_taken":false,"standby_taken":0,"standby_limit":2,"next_rank":1,"my_claim":null,"claimable":true,"blocked_reason":null},{"seat_id":42,"route_id":9002,"status":"filled","snapshot":{"route_name":"East-5","date":"2026-03-04","work_from":"07:30","work_end":"15:30","vehicle_type":"Van","distance":55,"stops":38,"start":"Scarborough","end":"Markham"},"primary_taken":true,"standby_taken":1,"standby_limit":2,"next_rank":3,"my_claim":null,"claimable":true,"blocked_reason":null},{"seat_id":43,"route_id":9003,"status":"open","snapshot":{"route_name":"North-1","date":"2026-03-04","work_from":"06:30","work_end":"14:30","vehicle_type":"Van","distance":68,"stops":42,"start":"Scarborough","end":"Markham"},"primary_taken":false,"standby_taken":0,"standby_limit":2,"next_rank":1,"my_claim":null,"claimable":false,"blocked_reason":"time_conflict"}]}}},"seat_mode":{"summary":"Grab a Seat board","value":{"result":true,"message":"Successful","data":{"board":{"id":13,"title":"Saturday pool","date":"2026-03-07","mode":"seat","status":"open","is_open":true,"quota":{"seat_type":"over","standby_scope":"global","capacity":12,"taken":7,"remaining":5,"seats":6,"settled":false,"my_claim":null,"claimable":true,"blocked_reason":null},"opens_at":"2026-03-06T18:00:00+00:00","closes_at":"2026-03-07T05:00:00+00:00","standby_limit":1,"withdraw_policy":"allowed","withdraw_cutoff_hours":null,"max_primary_per_driver":1,"my_primary":0},"seats":[{"seat_id":61,"route_id":9101,"status":"open","snapshot":{"route_name":"East-3","date":"2026-03-07","work_from":"07:00","work_end":"15:00","vehicle_type":"Van","distance":68,"stops":42},"primary_taken":false,"standby_taken":0,"standby_limit":1,"next_rank":1,"my_claim":null,"claimable":false,"blocked_reason":"seat_mode"}]}}},"bid_mode":{"summary":"Bid mode (reverse auction)","value":{"result":true,"message":"Successful","data":{"board":{"id":14,"title":"Friday auction","date":"2026-03-06","mode":"bid","status":"open","is_open":true,"quota":null,"bid_visibility":"open","award_method":"lowest","currency":"CAD","settled":false,"opens_at":"2026-03-05T18:00:00+00:00","closes_at":"2026-03-06T05:00:00+00:00","standby_limit":1,"withdraw_policy":"allowed","withdraw_cutoff_hours":null,"max_primary_per_driver":1,"my_primary":0},"seats":[{"seat_id":61,"route_id":9010,"status":"open","snapshot":{"route_name":"West-2","date":"2026-03-06","work_from":"07:00","work_end":"15:00","vehicle_type":"Van","distance":68,"stops":42,"start":"Scarborough","end":"Markham"},"primary_taken":false,"standby_taken":0,"standby_limit":1,"next_rank":1,"my_claim":{"claim_id":702,"board_id":14,"board_title":"Friday auction","seat_id":61,"route_id":9010,"route_name":"West-2","is_pooled":false,"is_bid":true,"bid_price":290,"awarded_price":null,"currency":"CAD","global_standby":false,"date":"2026-03-06","work_from":"07:00","work_end":"15:00","rank":0,"status":"bidding","is_active":true,"reason":null,"claimed_at":"2026-03-05 20:11:02","decided_at":null,"can_withdraw":true,"withdraw_blocker":null,"withdraw_deadline":null},"bid":{"visibility":"open","currency":"CAD","reference_price":300,"ceiling_price":350,"instant_price":200,"bid_count":3,"lowest":285,"my_bid":290,"my_claim_id":702,"my_position":2,"allow_rebid":true,"min_bid_step":5,"can_bid":true,"blocked_reason":null},"claimable":false,"blocked_reason":"bid_mode"}]}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The account has no driver profile","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"No driver profile is linked to this account."}}}},"404":{"description":"Board not found or not visible to this driver","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Board not found."}}}}},"security":[{"bearerAuth":[]}]}},"/v1/driver/boards/{id}/claim":{"post":{"tags":["Driver Route Board"],"summary":"Claim a seat (route) on a Route Board, or grab a seat on a seat-mode board","description":"Route mode (seat_id required): first come first served. Rank 1 becomes the driver and is put on the vehicle slot immediately; later ranks queue as standby up to the board's standby_limit. Seat mode (\"Grab a Seat\", seat_id optional and ignored): the driver takes the next numbered seat in the board's pool (status pooled, data.capacity = pool size); the dispatcher hands out the vehicles when the board closes. Throttled to 30 requests per minute per user. 409 when the seat is full, already claimed by you, the board is not open, the seat is no longer available, the pool is full or the board is already settled; 422 for a time conflict, the per-driver maximum, eligibility or a bad seat_id (route mode only).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The board ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The board ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"seat_id":{"type":"integer","description":"The seat ID on that board. Required in route mode; optional and ignored on a seat-mode board.\n\n**Details:** Type `integer`."}}},"example":{"seat_id":41},"examples":{"route_mode":{"summary":"Route mode","value":{"seat_id":41}},"seat_mode":{"summary":"Seat mode (body may be empty)","value":[]}}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"rank":{"type":"integer","description":"Rank. Field in the JSON request body.\n\n**Details:** Type `integer`."},"claim_id":{"type":"integer","description":"Claim id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"status":{"type":"string","enum":["primary","standby","pooled"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `primary` · `standby` · `pooled`.\n\n**Details:** Type `string`."},"capacity":{"type":"integer","description":"Seat mode only: size of the pool the seat was taken from\n\n**Details:** Type `integer`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"message":"You got this route. It is now in your route list.","data":{"rank":1,"claim_id":501,"status":"primary"}},"examples":{"route_mode":{"summary":"Route mode","value":{"result":true,"message":"You got this route. It is now in your route list.","data":{"rank":1,"claim_id":501,"status":"primary"}}},"seat_mode":{"summary":"Seat mode","value":{"result":true,"message":"You got a seat. Vehicles are handed out when the board closes — we will tell you which one is yours.","data":{"rank":8,"claim_id":612,"status":"pooled","capacity":12}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The account has no driver profile","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"No driver profile is linked to this account."}}}},"404":{"description":"Board not found or not visible to this driver","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Board not found."}}}},"409":{"description":"Seat full / already claimed / board not open / seat unavailable / pool full / board settled","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"This route is full — the driver and every standby place are taken."},"examples":{"seat_full":{"value":{"result":false,"message":"This route is full — the driver and every standby place are taken."}},"quota_full":{"value":{"result":false,"message":"All seats on this board are taken."}}}}}},"422":{"description":"Time conflict, per-driver maximum reached, not eligible, or seat not on this board","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"This route overlaps another vehicle you already hold that day."}}}},"429":{"description":"Too Many Requests"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/boards/{id}/bid":{"post":{"tags":["Driver Route Board"],"summary":"Place or lower a bid on a seat of a bid-mode (reverse auction) Route Board","description":"Bid mode only: the driver names the pay they will accept for the route. The lowest bid wins when the board's deadline (closes_at) passes; a bid at or under the seat's instant_price wins immediately (data.awarded = true, the driver is put on the vehicle slot at once). A second bid from the same driver is a revision: it must be lower than the current one by at least the board's min_bid_step, and only when the board allows rebids. On an open board data.lowest is the current lowest bid on the seat (not who); on a sealed board it is null. A new lowest bid inside the anti-snipe window pushes the deadline out — data.closes_at is always the deadline that applies after this bid. Throttled to 30 requests per minute per user. 409 when the board is not open, already settled, the seat is no longer available (awarded) or the board does not allow rebids; 422 for a bid above the ceiling, a revised bid that is not lower by min_bid_step, a non-positive price, a seat that is not on this board, a board that is not in bid mode, or an ineligible driver.","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The board ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The board ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["seat_id","price"],"properties":{"seat_id":{"type":"integer","description":"**Required.**\n\nThe seat ID on that board\n\n**Details:** Type `integer`."},"price":{"type":"number","description":"**Required.**\n\nThe pay the driver will accept for the route, in the board's currency\n\n**Details:** Type `number`."}}},"example":{"seat_id":61,"price":290}}}},"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"claim_id":{"type":"integer","description":"Claim id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"price":{"type":"number","description":"The bid as stored (rounded to 2 decimals)\n\n**Details:** Type `number`."},"awarded":{"type":"boolean","description":"True when the bid met the instant price and the route is already the driver's\n\n**Details:** Type `boolean`."},"lowest":{"type":["number","null"],"description":"Current lowest bid on the seat after this bid; null on a sealed board\n\n**Details:** Type `number` · Nullable."},"closes_at":{"type":["string","null"],"description":"ISO 8601 deadline that applies after this bid (may have been extended by anti-snipe)\n\n**Details:** Type `string` · Nullable."},"status":{"type":"string","enum":["bidding","primary"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `bidding` · `primary`.\n\n**Details:** Type `string`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"message":"Your bid is in.","data":{"claim_id":702,"price":290,"awarded":false,"lowest":285,"closes_at":"2026-03-06T05:00:00+00:00","status":"bidding"}},"examples":{"placed":{"summary":"Bid placed (open board)","value":{"result":true,"message":"Your bid is in.","data":{"claim_id":702,"price":290,"awarded":false,"lowest":285,"closes_at":"2026-03-06T05:00:00+00:00","status":"bidding"}}},"lowered":{"summary":"Bid lowered, deadline extended by anti-snipe","value":{"result":true,"message":"Your bid has been lowered.","data":{"claim_id":702,"price":280,"awarded":false,"lowest":280,"closes_at":"2026-03-06T05:10:00+00:00","status":"bidding"}}},"instant":{"summary":"Instant price met","value":{"result":true,"message":"Your bid met the instant price — the route is yours.","data":{"claim_id":702,"price":200,"awarded":true,"lowest":200,"closes_at":"2026-03-06T05:00:00+00:00","status":"primary"}}},"sealed":{"summary":"Sealed board: lowest is never revealed","value":{"result":true,"message":"Your bid is in.","data":{"claim_id":703,"price":290,"awarded":false,"lowest":null,"closes_at":"2026-03-06T05:00:00+00:00","status":"bidding"}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"The account has no driver profile","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"No driver profile is linked to this account."}}}},"404":{"description":"Board not found or not visible to this driver","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Board not found."}}}},"409":{"description":"Board not open / board settled / seat already awarded / rebids not allowed","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"This vehicle is no longer available."},"examples":{"seat_awarded":{"value":{"result":false,"message":"This vehicle is no longer available."}},"rebid_denied":{"value":{"result":false,"message":"Bids cannot be changed on this board."}}}}}},"422":{"description":"Above the ceiling, revised bid not lower by min_bid_step, invalid price, seat not on this board, board not in bid mode, or not eligible","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"That is above the highest price accepted for this route."},"examples":{"over_ceiling":{"value":{"result":false,"message":"That is above the highest price accepted for this route."}},"must_be_lower":{"value":{"result":false,"message":"A revised bid must be lower than your current one by at least the minimum step."}},"invalid":{"value":{"result":false,"message":"Please enter a price above zero."}}}}}},"429":{"description":"Too Many Requests"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/claims/{id}/withdraw":{"post":{"tags":["Driver Route Board"],"summary":"Withdraw one of your Route Board claims","description":"Subject to the board's withdraw policy (allowed / denied / until N hours before the route starts). A standby claim may always be left. When a primary withdraws, the next standby is promoted automatically. 403 when the policy refuses; data.withdraw_deadline then tells until when it was possible (null under the denied policy). A pooled seat (seat mode) may always be given up before the board is settled; the seats behind it move up. A live bid (status bidding) on a bid-mode board may always be retracted before the award.","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The claim ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The claim ID\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"description":"Data. Field in the JSON request body.\n\n**Details:** Nullable."}}},"example":{"result":true,"message":"Your claim has been withdrawn.","data":null}}}},"401":{"description":"Unauthorized"},"403":{"description":"Withdrawal refused by the board's policy, or no driver profile","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":false,"message":"The withdrawal deadline for this route has passed. Please contact your dispatcher.","data":{"withdraw_deadline":"2026-03-03 19:00"}}}}},"404":{"description":"Claim not found or not yours","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"Board not found."}}}}},"security":[{"bearerAuth":[]}]}},"/v1/driver/claims":{"get":{"tags":["Driver Route Board"],"summary":"List your Route Board claims","description":"Active claims (pooled / primary / standby) first, then — with history=1 — withdrawn, vetoed, replaced, displaced, skipped, expired and completed ones. Each row says whether it can be withdrawn right now and, for a primary under the until_cutoff policy, the deadline.","parameters":[{"in":"query","name":"history","schema":{"type":"integer","enum":[0,1],"description":"1 to include finished claims (default 0)\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"required":false,"description":"1 to include finished claims (default 0)\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"array","items":{"type":"object","properties":{"claim_id":{"type":"integer","description":"Claim id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"board_id":{"type":"integer","description":"Board id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"board_title":{"type":"string","description":"Board title. Human-readable label.\n\n**Details:** Type `string`."},"seat_id":{"type":["integer","null"],"description":"Seat id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`."},"route_name":{"type":"string","description":"Route name. Human-readable label.\n\n**Details:** Type `string`."},"date":{"type":"string","description":"Calendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Type `string`."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"work_end":{"type":["string","null"],"description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"rank":{"type":"integer","description":"Route mode: 1 = driver, 2.. = standby position + 1. Seat mode: the seat number (pooled) or the standby position (global standby).\n\n**Details:** Type `integer`."},"status":{"type":"string","enum":["pooled","primary","standby","withdrawn","vetoed","replaced","displaced","skipped","expired","completed","bidding","lost"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pooled` · `primary` · `standby` · `withdrawn` · `vetoed` · `replaced` · `displaced` · `skipped` · `expired` · `completed` · `bidding` · `lost`.\n\n**Details:** Type `string`."},"is_active":{"type":"boolean","description":"Is active. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."},"claimed_at":{"type":"string","description":"Claimed at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."},"decided_at":{"type":["string","null"],"description":"Decided at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"can_withdraw":{"type":"boolean","description":"Can withdraw. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"withdraw_blocker":{"type":["string","null"],"description":"Lang key explaining why withdrawing is refused\n\n**Details:** Type `string` · Nullable."},"withdraw_deadline":{"type":["string","null"],"description":"Y-m-d H:i, only for a primary claim under the until_cutoff policy\n\n**Details:** Type `string` · Nullable."},"is_pooled":{"type":"boolean","description":"Seat mode: a numbered seat in the pool, no vehicle yet\n\n**Details:** Type `boolean`."},"global_standby":{"type":"boolean","description":"Seat mode: standby for any vehicle on the board\n\n**Details:** Type `boolean`."},"is_bid":{"type":"boolean","description":"True while the claim is a live bid (status bidding) on a bid-mode board\n\n**Details:** Type `boolean`."},"bid_price":{"type":["number","null"],"description":"Bid mode: the price the driver named\n\n**Details:** Type `number` · Nullable."},"awarded_price":{"type":["number","null"],"description":"Bid mode: the price the route was awarded at (primary claims)\n\n**Details:** Type `number` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `CAD`.","examples":["CAD"]}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"message":"Successful","data":[{"claim_id":501,"board_id":12,"board_title":"Route Board 2026-03-04","seat_id":41,"route_id":9001,"route_name":"East-3","date":"2026-03-04","work_from":"07:00","work_end":"15:00","rank":1,"status":"primary","is_active":true,"reason":null,"claimed_at":"2026-03-03 18:00:07","decided_at":null,"can_withdraw":true,"withdraw_blocker":null,"withdraw_deadline":"2026-03-03 19:00","is_pooled":false,"global_standby":false},{"claim_id":612,"board_id":13,"board_title":"Saturday pool","seat_id":null,"route_id":0,"route_name":"","is_pooled":true,"global_standby":false,"date":"2026-03-07","work_from":null,"work_end":null,"rank":8,"status":"pooled","is_active":true,"reason":null,"claimed_at":"2026-03-06 18:00:03","decided_at":null,"can_withdraw":true,"withdraw_blocker":null,"withdraw_deadline":null},{"claim_id":502,"board_id":12,"board_title":"Route Board 2026-03-04","seat_id":42,"route_id":9002,"route_name":"East-5","date":"2026-03-04","work_from":"07:30","work_end":"15:30","rank":2,"status":"standby","is_active":true,"reason":null,"claimed_at":"2026-03-03 18:00:07","decided_at":null,"can_withdraw":true,"withdraw_blocker":null,"withdraw_deadline":null,"is_pooled":false,"global_standby":false},{"claim_id":477,"board_id":11,"board_title":"Route Board 2026-03-02","seat_id":41,"route_id":9001,"route_name":"West-2","date":"2026-03-02","work_from":"07:00","work_end":"15:00","rank":1,"status":"replaced","is_active":false,"reason":"Assigned to another driver","claimed_at":"2026-03-03 18:00:07","decided_at":"2026-03-02 14:20:11","can_withdraw":false,"withdraw_blocker":"route_board.err_claim_not_active","withdraw_deadline":null,"is_pooled":false,"global_standby":false}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"The account has no driver profile","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"No driver profile is linked to this account."}}}}},"security":[{"bearerAuth":[]}]}},"/v1/apps/{appCode}/clients/{clientCode}/locker-resale/terms":{"get":{"tags":["Platform Apps"],"summary":"Handover terms for the buyer","description":"The terms a buyer ticks when opening a handover, in their language. Read it before opening a deal and show it: the deal snapshots the operator's current version as the one its buyer accepted, so an app that never showed it has agreed on their behalf. The operator's own wording replaces ours whole where they have written it; a language left blank falls back to ours. Send the version back when opening the deal — each deal records the wording its buyer actually accepted, so a later edit never rewrites what somebody agreed to.","operationId":"platformAppLockerResaleTerms","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"locale","in":"query","required":false,"schema":{"type":"string","description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`."},"description":"UI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"The terms and the version to record","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"version":"platform-v1","source":"platform","text":["We pass the goods on; we are not the seller.","The money for the goods is between the two of you."]}}}},"403":{"description":"The handover capability is off for this client, or the module is off for the business"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-resale/deals":{"get":{"tags":["Platform Apps"],"summary":"Handovers this customer is a party to","description":"Every handover where this customer is the buyer or the seller, newest first. Scoped to the person, not to the business: one customer never reads another's handovers. What each entry carries depends on which party the reader is — only the seller sees the drop-off code, the amount owed and the three decisions that are his; the buyer sees the pickup code and the cabinet address, and only once the seller has released it. When one account is both the buyer and the seller of a deal — the seller needs no account, so a seller contact that matches the caller's own is linked to it — the deal is answered as the seller, which is the larger of the two views, with also_buyer true and the buyer's pickup_code included.","operationId":"platformAppLockerResaleDeals","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},{"name":"open","in":"query","required":false,"schema":{"type":"boolean","description":"Open. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `boolean`."},"description":"Open. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `boolean`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · max `100`."},"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · max `100`."}],"responses":{"200":{"description":"Handovers, newest first","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"deals":[{"id":4108,"deal_no":"RH2609170001","status":"awaiting_release","status_label":"Waiting for the pickup code","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:12:04","dropoff_deadline":"2026-09-20 10:12:04","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-21 11:40:00","dropoff_code":null,"return_code":null,"outstanding_amount":0,"payment":null,"can_release":true,"can_revoke":false,"can_abort":true,"can_cancel":false,"location":"Cabinet A — Plaza Sud","compartment_number":12}],"pagination":{"page":1,"per_page":25,"total":1}}}}},"403":{"description":"The handover capability is off for this client, or the module is off for the business"}}},"post":{"tags":["Platform Apps"],"summary":"Open a handover","description":"The caller is the seller: their own name, phone, e-mail and language come from the account. The buyer needs no account — a phone number or an e-mail address is enough, and one of the two is required; the pickup code is sent there once the seller releases it. The answer carries the seller's drop-off code, which is also sent to the seller by SMS or e-mail; no cabinet is chosen here, because any of the operator's cabinets that take handovers may be used. Opening a deal as the buyer is no longer supported: a request that still carries seller_name, seller_phone or seller_email is refused with 422. The agreed price is recorded for the two parties only — the platform never collects the money for the goods.","operationId":"platformAppLockerResaleCreate","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyer_name":{"type":"string","description":"The buyer's name\n\n**Details:** Type `string`."},"buyer_phone":{"type":"string","description":"Required unless buyer_email is given\n\n**Details:** Type `string`."},"buyer_email":{"type":"string","description":"Required unless buyer_phone is given\n\n**Details:** Type `string`."},"buyer_locale":{"type":"string","description":"Language the buyer is written to in; defaults to the buyer's account language when the contact matches one, otherwise the request language\n\n**Details:** Type `string`."},"item_title":{"type":"string","description":"Item title. Human-readable label.\n\n**Details:** Type `string`."},"item_description":{"type":"string","description":"Item description. Free-text note.\n\n**Details:** Type `string`."},"item_price":{"type":"number","description":"Item price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"item_currency":{"type":"string","description":"Item currency. Field in the JSON request body.\n\n**Details:** Type `string`."}},"additionalProperties":true},"example":{"buyer_name":"Alex Tremblay","buyer_phone":"+15145550188","item_title":"Road bike","item_description":"54cm frame, blue","item_price":420,"item_currency":"CAD"}}}},"responses":{"200":{"description":"The handover, with the seller's drop-off code","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"deal":{"id":5120,"deal_no":"RS260917A1B2C3","status":"awaiting_dropoff","status_label":"Awaiting drop-off","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:02:11","dropoff_deadline":"2026-09-20 10:02:11","release_due_at":null,"expires_at":null,"can_cancel":true,"dropoff_code":483920,"return_code":null,"outstanding_amount":"0.00","payment":null,"can_release":false,"can_revoke":false,"can_abort":false,"location":null,"compartment_number":null,"address":null}}}}},"403":{"description":"The handover capability is off for this client, or the module is off for the business"},"422":{"description":"The buyer has no contact, the seller's account has neither phone nor e-mail, a seller_* field was sent (opening as the buyer is no longer supported), or one party already has as many open handovers as the operator allows"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-resale/deals/{id}":{"get":{"tags":["Platform Apps"],"summary":"One handover","description":"One handover as the calling party may see it, with the timeline of what both parties did — never the other party's phone number, IP or device. A seller who owes money also gets the `payment` block: the subject the scan-to-pay endpoints take, which is what lets him pay with anything the operator accepts rather than only a balance or a saved card. When one account is both the buyer and the seller of a deal — the seller needs no account, so a seller contact that matches the caller's own is linked to it — the deal is answered as the seller, which is the larger of the two views, with also_buyer true and the buyer's pickup_code included.","operationId":"platformAppLockerResaleShow","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The handover and its timeline","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"deal":{"id":4108,"deal_no":"RH2609170001","status":"awaiting_payment","status_label":"Waiting for payment","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:12:04","dropoff_deadline":"2026-09-20 10:12:04","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-21 11:40:00","dropoff_code":null,"return_code":null,"outstanding_amount":6,"payment":{"amount":6,"currency":"CAD","subject_type":"locker_resale","subject_id":4108,"payable_in_app":true,"public_token":"0f7c2b4e9a1d4f0b8c6e3a5d7b9f1c2e","pay_url":"https://app.example.com/pay/r/0f7c2b4e9a1d4f0b8c6e3a5d7b9f1c2e"},"can_release":false,"can_revoke":false,"can_abort":true,"can_cancel":false,"location":"Cabinet A — Plaza Sud","compartment_number":12},"timeline":[{"type":"created","label":"Deal opened","role":"buyer","occurred_at":"2026-09-17 10:12:04"},{"type":"dropoff_closed","label":"Goods placed","role":"seller","occurred_at":"2026-09-17 11:38:52"}]}}}},"403":{"description":"The handover capability is off for this client, or the module is off for the business"},"404":{"description":"No handover with that id that this customer is a party to"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-resale/deals/{id}/release":{"post":{"tags":["Platform Apps"],"summary":"Send the buyer the pickup code","description":"The seller's decision, and the only thing that gives the buyer a code — nothing releases it automatically. Until it is pressed the buyer knows a cabinet holds the goods but not which one. Refused before the goods are in, before the fee is settled, and after the deal has ended.","operationId":"platformAppLockerResaleRelease","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Released; the buyer has been told","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"deal":{"id":4108,"deal_no":"RH2609170001","status":"active","status_label":"Waiting for the buyer","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:12:04","dropoff_deadline":"2026-09-20 10:12:04","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-21 11:40:00","dropoff_code":null,"return_code":null,"outstanding_amount":0,"payment":null,"can_release":false,"can_revoke":true,"can_abort":true,"can_cancel":false,"location":"Cabinet A — Plaza Sud","compartment_number":12}}}}},"403":{"description":"The handover capability is off for this client, or the module is off for the business"},"404":{"description":"No handover with that id that this customer is a party to"},"422":{"description":"Not the seller, or the deal is not waiting to be released"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-resale/deals/{id}/revoke-code":{"post":{"tags":["Platform Apps"],"summary":"Revoke the pickup code","description":"Kills the code the buyer holds and puts the deal back to waiting; the buyer is told at once. Refused once a door has been opened for the buyer — an open door cannot be taken back by voiding a code. The send-by deadline is NOT extended: revoking after it has passed hands the deal back to the seller at the next sweep, which the app must say before the button is pressed.","operationId":"platformAppLockerResaleRevoke","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Revoked; the buyer has been told","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"deal":{"id":4108,"deal_no":"RH2609170001","status":"awaiting_release","status_label":"Waiting for the pickup code","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:12:04","dropoff_deadline":"2026-09-20 10:12:04","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-21 11:40:00","dropoff_code":null,"return_code":null,"outstanding_amount":0,"payment":null,"can_release":true,"can_revoke":false,"can_abort":true,"can_cancel":false,"location":"Cabinet A — Plaza Sud","compartment_number":12}}}}},"403":{"description":"The handover capability is off for this client, or the module is off for the business"},"404":{"description":"No handover with that id that this customer is a party to"},"422":{"description":"Not the seller, no code out, or a door is already opening for the buyer"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-resale/deals/{id}/abort":{"post":{"tags":["Platform Apps"],"summary":"Call the handover off","description":"The seller ends the deal and takes his goods back: the buyer's code stops working, a return code is sent to the seller, and the cabinet fee is not refunded. Available while the goods are in a cabinet and before the buyer has collected them.","operationId":"platformAppLockerResaleAbort","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"reason":"Buyer never paid me"}}}},"responses":{"200":{"description":"Called off; the return code is on its way","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"deal":{"id":4108,"deal_no":"RH2609170001","status":"aborted","status_label":"Called off","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:12:04","dropoff_deadline":"2026-09-20 10:12:04","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-21 11:40:00","dropoff_code":null,"return_code":284193,"outstanding_amount":0,"payment":null,"can_release":false,"can_revoke":false,"can_abort":false,"can_cancel":false,"location":"Cabinet A — Plaza Sud","compartment_number":12}}}}},"403":{"description":"The handover capability is off for this client, or the module is off for the business"},"404":{"description":"No handover with that id that this customer is a party to"},"422":{"description":"Not the seller, or the deal has already ended"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-resale/deals/{id}/cancel":{"post":{"tags":["Platform Apps"],"summary":"Cancel before anything is dropped off","description":"Either party may walk away while no goods have been placed: nothing has been paid, no compartment is held, and the drop-off code stops working. Once the goods are in a cabinet this is refused — from then on the seller calls the deal off instead, and the buyer waits.","operationId":"platformAppLockerResaleCancel","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"deal":{"id":4108,"deal_no":"RH2609170001","status":"cancelled","status_label":"Cancelled","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:12:04","dropoff_deadline":"2026-09-20 10:12:04","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-21 11:40:00","dropoff_code":null,"return_code":null,"outstanding_amount":0,"payment":null,"can_release":false,"can_revoke":false,"can_abort":false,"can_cancel":false,"location":"Cabinet A — Plaza Sud","compartment_number":12}}}}},"403":{"description":"The handover capability is off for this client, or the module is off for the business"},"404":{"description":"No handover with that id that this customer is a party to"},"422":{"description":"The goods are already in a cabinet"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-resale/deals/{id}/report":{"post":{"tags":["Platform Apps"],"summary":"Report a problem after collecting","description":"The buyer says what was in the box. It is a record for the operator to read beside the cabinet's own evidence, not a case: the platform never held the money for the goods, so it does not arbitrate, refund, or suspend anybody on the strength of it. Open for seven days after collection — after that the compartment has been reused and the record is no longer about this handover. Photos may be uploaded as files or sent as base64. The reason is one of empty, damaged, not_as_described or other.","operationId":"platformAppLockerResaleReport","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"reason":"not_as_described","description":"The frame is cracked.","photos":["<base64>"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`."},"photos[]":{"type":"array","items":{"type":"string","format":"binary","description":"Photos. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`, format `binary`."},"description":"Photos. Element of a list or map in the request/response payload.\n\n**Details:** Type `array`, items `string`."}}}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"report":{"id":91,"reason":"not_as_described","status":"open","created_at":"2026-09-19 09:02:11"}}}}},"403":{"description":"The handover capability is off for this client, or the module is off for the business"},"404":{"description":"No handover with that id that this customer is a party to"},"422":{"description":"Not the buyer, the goods were never collected, or the seven days have passed"}}}},"/v1/locker-resale/terms":{"get":{"tags":["Locker Resale"],"summary":"Terms shown to the buyer","description":"The terms a buyer agrees to when opening a handover, in their language. The operator's own wording replaces ours whole when they have set it; a language they left blank falls back to ours. The version comes back with the text — the deal records which wording its buyer actually accepted, so a later edit never rewrites what somebody agreed to.","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","description":"Language to read them in; defaults to the caller's own\n\nUI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`."},"description":"Language to read them in; defaults to the caller's own\n\nUI / content locale code (e.g. `en`, `chs`, `de`).\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"version":"platform-v1","source":"platform","text":["You are arranging a handover through a locker. The cabinet passes the goods from the seller to you; we are not the seller and we are not part of your sale.","We never hold the money for the goods. Whatever you pay the seller, you pay them directly, and any dispute about it is between the two of you.","The seller pays a cabinet fee when the goods go in. It is not refunded — not if the deal is called off, and not if you never come."]}}}},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-resale/deals":{"get":{"tags":["Locker Resale"],"summary":"List item handover deals","description":"Deals the authenticated caller is a party to, as buyer or as seller. Each deal is presented as that party may see it: the pickup code and the cabinet address reach the buyer only once the seller has released them. When one account is both the buyer and the seller of a deal — the seller needs no account, so a seller contact that matches the caller's own is linked to it — the deal is answered as the seller, which is the larger of the two views, with also_buyer true and the buyer's pickup_code included.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"awaiting_dropoff | dropoff_expired | awaiting_payment | awaiting_release | active | overdue | unpaid_terminated | aborted | completed | returned | cancelled | pending_clearance | cleared\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},"description":"awaiting_dropoff | dropoff_expired | awaiting_payment | awaiting_release | active | overdue | unpaid_terminated | aborted | completed | returned | cancelled | pending_clearance | cleared\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},{"name":"open","in":"query","required":false,"schema":{"type":"boolean","description":"Only deals that have not finished\n\n**Details:** Optional · Type `boolean`."},"description":"Only deals that have not finished\n\n**Details:** Optional · Type `boolean`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"Page number, from 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Page number, from 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","description":"Page size, up to 100\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"Page size, up to 100\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"deals":[{"id":5120,"deal_no":"RS260917A1B2C3","status":"awaiting_release","status_label":"Awaiting pickup code","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:02:11","dropoff_deadline":"2026-09-20 10:02:11","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-20 11:40:00","dropoff_code":null,"return_code":null,"outstanding_amount":"0.00","can_release":true,"can_revoke":false,"can_abort":true,"can_cancel":false,"location":"Central Mall","compartment_number":"A07"}],"pagination":{"page":1,"per_page":25,"total":1}}}}},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Locker Resale"],"summary":"Open an item handover deal as the seller","description":"The caller is the seller: their own name, phone, e-mail and language come from the account. The buyer needs no account — a phone number or an e-mail address is enough, and one of the two is required; the pickup code is sent there once the seller releases it. The answer carries the seller's drop-off code, which is also sent to the seller by SMS or e-mail; no cabinet is chosen here, because any of the operator's cabinets that take handovers may be used. Opening a deal as the buyer is no longer supported: a request that still carries seller_name, seller_phone or seller_email is refused with 422. The agreed price is recorded for the two parties only — the platform never collects the money for the goods.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyer_name":{"type":"string","description":"The buyer's name\n\n**Details:** Type `string`."},"buyer_phone":{"type":"string","description":"Required unless buyer_email is given\n\n**Details:** Type `string`."},"buyer_email":{"type":"string","description":"Required unless buyer_phone is given\n\n**Details:** Type `string`."},"buyer_locale":{"type":"string","description":"Language the buyer is written to in; defaults to the buyer's account language when the contact matches one, otherwise the request language\n\n**Details:** Type `string`."},"item_title":{"type":"string","description":"Item title. Human-readable label.\n\n**Details:** Type `string`."},"item_description":{"type":"string","description":"Item description. Free-text note.\n\n**Details:** Type `string`."},"item_price":{"type":"number","description":"Item price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number`."},"item_currency":{"type":"string","description":"Item currency. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"example":{"buyer_name":"Alex Tremblay","buyer_phone":"+15145550188","item_title":"Road bike","item_description":"54cm frame, blue","item_price":420,"item_currency":"CAD"}}}},"responses":{"201":{"description":"deal opened","content":{"application/json":{"example":{"result":true,"deal":{"id":5120,"deal_no":"RS260917A1B2C3","status":"awaiting_dropoff","status_label":"Awaiting drop-off","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:02:11","dropoff_deadline":"2026-09-20 10:02:11","release_due_at":null,"expires_at":null,"can_cancel":true,"dropoff_code":483920,"return_code":null,"outstanding_amount":"0.00","payment":null,"can_release":false,"can_revoke":false,"can_abort":false,"location":null,"compartment_number":null,"address":null}}}}},"422":{"description":"buyer contact missing, the seller's account has no contact, a seller_* field was sent (opening as the buyer is no longer supported), or too many deals already running for one party"},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-resale/deals/{id}":{"get":{"tags":["Locker Resale"],"summary":"One item handover deal","description":"One deal the caller is a party to, with the part of its timeline that party may read. Failed and refused attempts, and the other party's contact details, are never included. When one account is both the buyer and the seller of a deal — the seller needs no account, so a seller contact that matches the caller's own is linked to it — the deal is answered as the seller, which is the larger of the two views, with also_buyer true and the buyer's pickup_code included.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"deal":{"id":5120,"deal_no":"RS260917A1B2C3","status":"active","status_label":"Ready for pickup","role":"buyer","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:02:11","dropoff_deadline":"2026-09-20 10:02:11","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-20 11:40:00","pickup_code":"7GQ4M2","location":"Central Mall","compartment_number":"A07","address":"980 Rue Sainte-Catherine, Montreal, QC, H3B 1E5"},"timeline":[{"type":"created","label":"Deal opened","role":"buyer","occurred_at":"2026-09-17 10:02:11"},{"type":"dropoff_closed","label":"Goods placed, door closed","role":"seller","occurred_at":"2026-09-17 11:40:00"},{"type":"released","label":"Pickup code sent to buyer","role":"seller","occurred_at":"2026-09-17 12:05:44"}]}}}},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-resale/deals/{id}/release":{"post":{"tags":["Locker Resale"],"summary":"Send the buyer their pickup code","description":"Seller only. Nothing releases a pickup code automatically: until the seller calls this, the buyer has no code and does not know which cabinet holds the goods. Calling it twice re-sends the same code rather than replacing it.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"code sent","content":{"application/json":{"example":{"result":true,"deal":{"id":5120,"deal_no":"RS260917A1B2C3","status":"active","status_label":"Ready for pickup","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:02:11","dropoff_deadline":"2026-09-20 10:02:11","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-20 11:40:00","dropoff_code":null,"return_code":null,"outstanding_amount":"0.00","can_release":false,"can_revoke":true,"can_abort":true,"can_cancel":false,"location":"Central Mall","compartment_number":"A07"}}}}},"403":{"description":"the caller is not the seller on this deal"},"409":{"description":"the deal is not waiting for a code to be sent"},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-resale/deals/{id}/revoke-code":{"post":{"tags":["Locker Resale"],"summary":"Cancel the pickup code the buyer holds","description":"Seller only, and only until the buyer's compartment has actually been opened. The old code stops working at once and the buyer is told immediately; the seller can then send a new one. The send-by deadline is NOT reset by this, so revoking after it has passed leaves the deal to be returned to the seller at the next check.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"code cancelled","content":{"application/json":{"example":{"result":true,"deal":{"id":5120,"deal_no":"RS260917A1B2C3","status":"awaiting_release","status_label":"Awaiting pickup code","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:02:11","dropoff_deadline":"2026-09-20 10:02:11","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-20 11:40:00","dropoff_code":null,"return_code":null,"outstanding_amount":"0.00","can_release":true,"can_revoke":false,"can_abort":true,"can_cancel":false,"location":"Central Mall","compartment_number":"A07"}}}}},"403":{"description":"the caller is not the seller on this deal"},"409":{"description":"no live code, or a door of this deal is open right now"},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-resale/deals/{id}/abort":{"post":{"tags":["Locker Resale"],"summary":"Call a handover off","description":"Seller only. The buyer's code stops working, the seller is sent a return code for the goods, and the cabinet fee already paid is not refunded.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."}}},"example":{"reason":"Buyer never paid me"}}}},"responses":{"200":{"description":"deal called off","content":{"application/json":{"example":{"result":true,"deal":{"id":5120,"deal_no":"RS260917A1B2C3","status":"aborted","status_label":"Called off","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:02:11","dropoff_deadline":"2026-09-20 10:02:11","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-20 11:40:00","dropoff_code":null,"return_code":"4KD9P1","outstanding_amount":"0.00","can_release":false,"can_revoke":false,"can_abort":false,"can_cancel":false,"location":"Central Mall","compartment_number":"A07"}}}}},"403":{"description":"the caller is not the seller on this deal"},"409":{"description":"the deal can no longer be called off"},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-resale/deals/{id}/report":{"post":{"tags":["Locker Resale"],"summary":"Report a problem with collected goods","description":"The buyer says what came out of the compartment was not what was agreed. Buyer only, only after collecting, and only within seven days — after that a compartment has been reused and the evidence is no longer about this handover. Filing a report changes nothing about the deal: it stays completed, no money moves, nobody is suspended, and the platform does not arbitrate. It records what was said so the operator can read it beside the door logs and photos the cabinet produced by itself. Photos are base64 strings over GraphQL and multipart files (or base64) over REST, up to five.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"empty | damaged | not_as_described | other; anything else is recorded as other\n\n**Details:** Type `string`."},"description":{"type":"string","description":"Free text, up to 2000 characters\n\n**Details:** Type `string`."},"photos[]":{"type":"array","items":{"type":"string","format":"binary","description":"Photos. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`, format `binary`."},"description":"Up to five photo files\n\n**Details:** Type `array`, items `string`."}}}},"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"empty | damaged | not_as_described | other; anything else is recorded as other\n\n**Details:** Type `string`."},"description":{"type":"string","description":"Free text, up to 2000 characters\n\n**Details:** Type `string`."},"photos":{"type":"array","items":{"type":"string","description":"Photos. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Up to five base64 photos\n\n**Details:** Type `array`, items `string`."}}},"example":{"reason":"not_as_described","description":"The box held a different model."}}}},"responses":{"201":{"description":"report recorded","content":{"application/json":{"example":{"result":true,"report":{"id":91,"reason":"not_as_described","reason_label":"Not what was agreed","status":"open","photos":2,"created_at":"2026-09-18 09:12:40"},"message":"Your report has been passed to the operator of this locker. We do not hold the money for the goods, so anything you paid the seller stays between the two of you."}}}},"403":{"description":"the caller is not the buyer on this deal"},"409":{"description":"the goods have not been collected, or the seven-day window has closed"},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-resale/deals/{id}/cancel":{"post":{"tags":["Locker Resale"],"summary":"Cancel a handover before anything is dropped off","description":"Either party, and only while the goods are still with the seller. Once they are in a cabinet the deal can only be called off by the seller, who then has to collect them.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Deal id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"deal cancelled","content":{"application/json":{"example":{"result":true,"deal":{"id":5120,"deal_no":"RS260917A1B2C3","status":"cancelled","status_label":"Cancelled","role":"seller","item_title":"Road bike","item_price":420,"item_currency":"CAD","created_at":"2026-09-17 10:02:11","dropoff_deadline":"2026-09-20 10:02:11","release_due_at":"2026-09-18 11:40:00","expires_at":"2026-09-20 11:40:00","dropoff_code":null,"return_code":null,"outstanding_amount":"0.00","can_release":false,"can_revoke":false,"can_abort":false,"can_cancel":false,"location":"Central Mall","compartment_number":"A07"}}}}},"409":{"description":"goods are already in a cabinet"},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-storage/rentals":{"get":{"tags":["Locker Storage"],"summary":"List short-term locker storage rentals","description":"Rentals of the authenticated caller's own business. Read-only: a rental begins and ends at a physical door, so nothing here opens one. The renter's phone number and e-mail address are deliberately not returned.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"active | overdue | pending_clearance | completed | cleared | cancelled\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},"description":"active | overdue | pending_clearance | completed | cleared | cancelled\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},{"name":"occupying","in":"query","required":false,"schema":{"type":"boolean","description":"Only rentals still holding a compartment\n\n**Details:** Optional · Type `boolean`."},"description":"Only rentals still holding a compartment\n\n**Details:** Optional · Type `boolean`."},{"name":"warehouseId","in":"query","required":false,"schema":{"type":"integer","description":"Location id\n\n**Details:** Optional · Type `integer`."},"description":"Location id\n\n**Details:** Optional · Type `integer`."},{"name":"shelfId","in":"query","required":false,"schema":{"type":"integer","description":"Cabinet id\n\n**Details:** Optional · Type `integer`."},"description":"Cabinet id\n\n**Details:** Optional · Type `integer`."},{"name":"from","in":"query","required":false,"schema":{"type":"string","description":"Start date (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},"description":"Start date (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","description":"End date (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},"description":"End date (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"Page number, from 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Page number, from 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"name":"perPage","in":"query","required":false,"schema":{"type":"integer","description":"Page size, maximum 100\n\n**Details:** Optional · Type `integer`."},"description":"Page size, maximum 100\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"rentals":[{"id":1042,"status":"active","warehouse_id":31,"location":"Central Mall","shelf_id":77,"shelf_code":"LS-01","compartment_number":"A07","compartment_type":"Medium","registered_renter":false,"started_at":"2026-08-30T09:15:00+00:00","expires_at":"2026-08-31T09:15:00+00:00","ended_at":null,"charged":false,"amount":null,"currency":null}],"pagination":{"page":1,"per_page":25,"total":1,"last_page":1}}}}},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-storage/rentals/{id}":{"get":{"tags":["Locker Storage"],"summary":"Get one short-term locker storage rental","description":"A single rental of the caller's own business, with its event timeline. A rental belonging to anybody else answers 404, not 403 — the caller learns nothing about whether that id exists.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"rental":{"id":1042,"status":"active","warehouse_id":31,"location":"Central Mall","shelf_id":77,"shelf_code":"LS-01","compartment_number":"A07","compartment_type":"Medium","registered_renter":false,"started_at":"2026-08-30T09:15:00+00:00","expires_at":"2026-08-31T09:15:00+00:00","ended_at":null,"charged":false,"amount":null,"currency":null,"timeline":[{"event_type":"deposit","actor_type":"consumer","occurred_at":"2026-08-30T09:15:00+00:00"}]}}}}},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/luggage/relays":{"get":{"operationId":"listLuggageRelays","tags":["Luggage Relay"],"summary":"List luggage relays","description":"Bags of the caller's own business kept at the hub warehouse between two compartments (luggage relay). For a hotel system or an OTA following a traveller's bag. The renter's phone and e-mail are not returned. Answers 404 when the relay module is not enabled on this deployment.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"warning | planned | taken_out | at_hub | returning | returned | delivered | cancelled\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},"description":"warning | planned | taken_out | at_hub | returning | returned | delivered | cancelled\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},{"name":"open","in":"query","required":false,"schema":{"type":"boolean","description":"Only relays still in flight\n\n**Details:** Optional · Type `boolean`."},"description":"Only relays still in flight\n\n**Details:** Optional · Type `boolean`."},{"name":"rentalId","in":"query","required":false,"schema":{"type":"integer","description":"Storage rental id\n\n**Details:** Optional · Type `integer`."},"description":"Storage rental id\n\n**Details:** Optional · Type `integer`."},{"name":"code","in":"query","required":false,"schema":{"type":"string","description":"The renter's storage code\n\nStable machine code for this resource.\n\n**Details:** Optional · Type `string`."},"description":"The renter's storage code\n\nStable machine code for this resource.\n\n**Details:** Optional · Type `string`."},{"name":"fromWarehouseId","in":"query","required":false,"schema":{"type":"integer","description":"Cabinet site the bag left\n\n**Details:** Optional · Type `integer`."},"description":"Cabinet site the bag left\n\n**Details:** Optional · Type `integer`."},{"name":"returnWarehouseId","in":"query","required":false,"schema":{"type":"integer","description":"Cabinet site the bag returns to\n\n**Details:** Optional · Type `integer`."},"description":"Cabinet site the bag returns to\n\n**Details:** Optional · Type `integer`."},{"name":"from","in":"query","required":false,"schema":{"type":"string","description":"Created on or after (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},"description":"Created on or after (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","description":"Created on or before (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},"description":"Created on or before (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Page number\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"name":"perPage","in":"query","required":false,"schema":{"type":"integer","description":"Rows per page, max 100\n\n**Details:** Optional · Type `integer`."},"description":"Rows per page, max 100\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"relays":[{"id":12,"rental_id":3401,"rental_status":"relayed","status":"at_hub","trigger":"declared","from_site":{"id":31,"name":"Central Mall"},"hub":{"id":7,"name":"Hub Warehouse"},"return":{"kind":"address","site":null,"address":{"name":"Grand Hotel reception","address_1":"100 King St W","city":"Toronto","province":"ON","country":"CA","postcode":"M5X 1A9"},"address_line":"100 King St W, Toronto, ON, M5X 1A9","paid":false,"shipment":null},"return_by":"2026-09-27T14:00:00+00:00","declared_return_at":"2026-09-27T16:00:00+00:00","warn_until":null,"taken_out_at":"2026-09-25T10:12:00+00:00","hub_received_at":"2026-09-25T13:40:00+00:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"orders":{"out_order_id":88123,"back_order_id":null,"fallback_order_id":null},"hub_days":null,"price":{"hub_per_day":5,"relay_fee":3,"address_return_fee":12,"free_hub_hours":0,"currency":"CAD","alt_site_fee":null,"shipment_fee":null},"created_at":"2026-09-25T09:00:00+00:00","onward":null}],"pagination":{"page":1,"per_page":25,"total":1,"last_page":1}}}}},"401":{"description":"unauthenticated"},"422":{"description":"unknown status or invalid date"}},"security":[{"bearerAuth":[]}]}},"/v1/luggage/relays/{id}":{"get":{"operationId":"getLuggageRelay","tags":["Luggage Relay"],"summary":"Get one luggage relay","description":"One relay of the caller's own business with its steps, the participating sites it may return to, and whether delivery to an address is offered and at what fee. Another business's relay answers 404. Onward fields (additive): return.shipment (order_id, carrier, tracking_number once shipped), onward (the renter's onward choice: kind alt_site / own_delivery / shipment, status quoted / paid / weight_hold / shipped, weight band, option, price, hold, carrier_cost), price.alt_site_fee / price.shipment_fee, and shipment (whether a carrier shipment may still be chosen, and the weight bands). onward also carries channel (label / courier), declared (the renter's weight and size), measured (the hub scale's figures) and shipping_order_id (the courier's shipping order); shipment lists channels.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Relay id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Relay id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"relay":{"id":12,"rental_id":3401,"rental_status":"relayed","status":"at_hub","trigger":"declared","from_site":{"id":31,"name":"Central Mall"},"hub":{"id":7,"name":"Hub Warehouse"},"return":{"kind":"address","site":null,"address":{"name":"Grand Hotel reception","address_1":"100 King St W","city":"Toronto","province":"ON","country":"CA","postcode":"M5X 1A9"},"address_line":"100 King St W, Toronto, ON, M5X 1A9","paid":false,"shipment":null},"return_by":"2026-09-27T14:00:00+00:00","declared_return_at":"2026-09-27T16:00:00+00:00","warn_until":null,"taken_out_at":"2026-09-25T10:12:00+00:00","hub_received_at":"2026-09-25T13:40:00+00:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"orders":{"out_order_id":88123,"back_order_id":null,"fallback_order_id":null},"hub_days":null,"price":{"hub_per_day":5,"relay_fee":3,"address_return_fee":12,"free_hub_hours":0,"currency":"CAD","alt_site_fee":null,"shipment_fee":null},"created_at":"2026-09-25T09:00:00+00:00","timeline":[{"step":"planned","actor_type":"staff","occurred_at":"2026-09-25T09:00:00+00:00"},{"step":"taken_out","actor_type":"staff","occurred_at":"2026-09-25T10:12:00+00:00"}],"return_site_choices":[{"id":31,"name":"Central Mall"},{"id":33,"name":"Union Station"}],"address_return":{"offered":true,"fee":12},"onward":null,"shipment":{"offered":true,"weight_tiers_kg":[5,10,20,32],"channels":["label","courier"]}}}}}},"401":{"description":"unauthenticated"},"404":{"description":"not found"}},"security":[{"bearerAuth":[]}]}},"/v1/luggage/relays/{id}/return":{"post":{"operationId":"changeLuggageRelayReturn","tags":["Luggage Relay"],"summary":"Change where and when a relayed bag comes back","description":"On the renter's behalf: move the return to another participating cabinet site (return_warehouse_id), or ask for delivery to an address (address, with return_at), or move the time (return_at). A site and an address cannot be given together. An address return is billed before the driver is given the stop; the renter pays on their own page, or the bill is settled by the operator. Refused with 409 once the return order exists, or when the rate does not offer delivery to an address. With shipment (and address), the bag is shipped from the hub by a carrier instead: no return_at, the price of the chosen option and the relay fee go on the bill at once, and the changed list reads [\"shipment\"]. Refused with 422 when the option is no longer offered (reason: option_gone) and with 409 once the shipment is paid.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Relay id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Relay id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"return_warehouse_id":{"type":"integer","description":"A participating site of the relay's territory\n\n**Details:** Type `integer`.\n\n**Example:** `33`.","examples":[33]},"return_at":{"type":"string","description":"When the renter wants the bag, in the business's time zone\n\n**Details:** Type `string`.\n\n**Example:** `2026-09-27 16:00`.","examples":["2026-09-27 16:00"]},"address":{"type":"object","description":"Delivery address (P4). Needs return_at.\n\n**Details:** Type `object`.","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Grand Hotel reception`.","examples":["Grand Hotel reception"]},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`.\n\n**Example:** `+1 416 555 0100`.","examples":["+1 416 555 0100"]},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`.\n\n**Example:** `100 King St W`.","examples":["100 King St W"]},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`.","examples":[""]},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`.\n\n**Example:** `Toronto`.","examples":["Toronto"]},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`.","examples":["ON"]},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `M5X 1A9`.","examples":["M5X 1A9"]},"lat":{"type":"number","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `43.6487`.","examples":[43.6487]},"lng":{"type":"number","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `-79.3817`.","examples":[-79.3817]},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `Leave with the concierge`.","examples":["Leave with the concierge"]}}},"shipment":{"type":"object","description":"Carrier shipment (O3): the bag is shipped from the hub to the address by a carrier. Needs address; return_at is not used. Choose the option from POST /v1/luggage/relays/{id}/onward-quote. A courier option (key s…) creates a shipping order of that Shipping Service when the bag ships.\n\n**Details:** Type `object`.","properties":{"weight_tier_kg":{"type":"integer","description":"The weight band the renter chose, from shipment.weight_tiers_kg\n\n**Details:** Type `integer`.\n\n**Example:** `10`.","examples":[10]},"option":{"type":"string","description":"The key of one option from onward-quote\n\n**Details:** Type `string`.\n\n**Example:** `m12:DOM.EP`.","examples":["m12:DOM.EP"]},"weight_kg":{"type":"number","description":"Declared weight in kg (optional). Given, the weight band is the smallest one it fits and couriers are priced on it. Either weight_tier_kg or weight_kg is required.\n\n**Details:** Type `number`.\n\n**Example:** `8.5`.","examples":[8.5]},"dimensions_cm":{"type":"object","description":"Declared dimensions in cm, {length, width, height} (optional). Given, carriers and couriers are priced on them instead of the compartment's size.\n\n**Details:** Type `object`.","properties":{"length":{"type":"number","description":"Length dimension.\n\n**Details:** Type `number`.\n\n**Example:** `70`.","examples":[70]},"width":{"type":"number","description":"Width dimension.\n\n**Details:** Type `number`.\n\n**Example:** `45`.","examples":[45]},"height":{"type":"number","description":"Height dimension.\n\n**Details:** Type `number`.\n\n**Example:** `30`.","examples":[30]}}}}}}}}}},"responses":{"200":{"description":"changed","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"changed":["address","return_at"],"relay":{"id":12,"rental_id":3401,"rental_status":"relayed","status":"at_hub","trigger":"declared","from_site":{"id":31,"name":"Central Mall"},"hub":{"id":7,"name":"Hub Warehouse"},"return":{"kind":"address","site":null,"address":{"name":"Grand Hotel reception","address_1":"100 King St W","city":"Toronto","province":"ON","country":"CA","postcode":"M5X 1A9"},"address_line":"100 King St W, Toronto, ON, M5X 1A9","paid":false,"shipment":null},"return_by":"2026-09-27T14:00:00+00:00","declared_return_at":"2026-09-27T16:00:00+00:00","warn_until":null,"taken_out_at":"2026-09-25T10:12:00+00:00","hub_received_at":"2026-09-25T13:40:00+00:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"orders":{"out_order_id":88123,"back_order_id":null,"fallback_order_id":null},"hub_days":null,"price":{"hub_per_day":5,"relay_fee":3,"address_return_fee":12,"free_hub_hours":0,"currency":"CAD","alt_site_fee":null,"shipment_fee":null},"created_at":"2026-09-25T09:00:00+00:00","onward":null}}}}},"401":{"description":"unauthenticated"},"404":{"description":"not found"},"409":{"description":"the change is no longer allowed (return order exists, address return not offered, time outside the allowed range)"},"422":{"description":"a site and an address together, nothing to change, an address without return_at, a shipment without address / weight_tier_kg / option, or a shipment option no longer offered (reason)"}},"security":[{"bearerAuth":[]}]}},"/v1/locker-storage/report":{"get":{"tags":["Locker Storage"],"summary":"Short-term locker storage figures for a period","description":"Rentals, collections, overdue count, average stay and the amount actually charged, broken out by location. The money figure is the total taken from renters — it is not a share, a split or a settlement figure. Defaults to the last 30 days.","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","description":"Start date (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},"description":"Start date (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","description":"End date (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."},"description":"End date (YYYY-MM-DD)\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"from":"2026-08-01","to":"2026-08-30","summary":{"rentals":128,"completed":119,"overdue":3,"paid_rentals":96,"revenue":412.5,"avg_minutes":214,"occupying_now":6},"by_location":[{"warehouse_id":31,"rentals":128,"completed":119,"overdue":3,"revenue":412.5,"avg_minutes":214,"occupying_now":6}]}}}},"401":{"description":"unauthenticated"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/duty":{"get":{"tags":["Driver"],"summary":"Driver duty status and pending offers","description":"Dispatch Options → driver_duty. Returns whether the feature is enabled for the driver's business, the driver's on-duty state and the auto-assign offers awaiting an answer. With the feature disabled on_duty is always true and pending_offers empty.","responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"on_duty":true,"on_duty_changed_at":"2026-08-17 08:00:00","require_accept":true,"response_timeout_minutes":5,"pending_offers":[{"offer_id":31,"subject_type":"order","subject_id":555,"order_id":555,"order_ref":"SR100000555","order_type":"D","address":"12 Main St, Montreal","offered_at":"2026-08-17 10:00:00","expires_at":"2026-08-17 10:05:00"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Driver profile not found"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Driver"],"summary":"Go on / off duty","description":"Sets the calling driver on or off duty. Only on-duty drivers receive auto-assigned work when the business enabled dispatch_to_on_duty_only. Returns 409 when the feature is disabled for the business.","requestBody":{"required":true,"content":{"application/json":{"example":{"on_duty":false}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"on_duty":true,"on_duty_changed_at":"2026-08-17 08:00:00","require_accept":true,"response_timeout_minutes":5,"pending_offers":[{"offer_id":31,"subject_type":"order","subject_id":555,"order_id":555,"order_ref":"SR100000555","order_type":"D","address":"12 Main St, Montreal","offered_at":"2026-08-17 10:00:00","expires_at":"2026-08-17 10:05:00"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Driver profile not found"},"409":{"description":"Feature disabled for this business"},"422":{"description":"on_duty missing"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/assignments/pending":{"get":{"tags":["Driver"],"summary":"Pending auto-assign offers","description":"Auto-assigned orders still waiting for the driver's accept / reject (Dispatch Options → driver_duty with require_accept).","responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"pending_offers":[{"offer_id":31,"subject_type":"order","subject_id":555,"order_id":555,"order_ref":"SR100000555","order_type":"D","address":"12 Main St, Montreal","offered_at":"2026-08-17 10:00:00","expires_at":"2026-08-17 10:05:00"}]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Driver profile not found"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders/{orderId}/accept":{"post":{"tags":["Driver"],"summary":"Accept an assigned order","description":"Confirms an auto-assigned order. Accepting work that was planned by a dispatcher is a harmless no-op.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Accepted","content":{"application/json":{"example":{"result":true,"action":"accepted","released":false}}}},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"},"409":{"description":"Feature disabled, or the order is not assigned to this driver"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders/{orderId}/reject":{"post":{"tags":["Driver"],"summary":"Reject an assigned order","description":"Rejects an auto-assigned order: the work is released back to the pool (instant orders are revoked, route orders removed from the driver's route) and, per the business setting, re-queued to the orchestrator or held for the dispatcher. Rejecting dispatcher-planned work is only recorded (released=false).","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"example":{"reason":"Too far away"}}}},"responses":{"200":{"description":"Rejected","content":{"application/json":{"example":{"result":true,"action":"rejected","released":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Order not found"},"409":{"description":"Feature disabled, or the order is not assigned to this driver"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/earnings":{"get":{"tags":["Driver"],"summary":"Driver earnings summary","description":"Delivered orders, tips collected and an estimate of the pay the business payroll rule yields for the period (opt-in family delivery_tips with driver_earnings_visible; 409 otherwise). period = today | yesterday | week | month | custom (from/to, max 92 days).","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","default":"today","description":"Period. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string` · Default: `today`."},"description":"Period. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string` · Default: `today`."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"From. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"From. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"To. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"To. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `string`, format `date`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"period":"today","from":"2026-08-17 00:00:00","to":"2026-08-17 23:59:59","delivered_orders":12,"tips_total":34.5,"tips_pass_through_pct":100,"tips_driver_share":34.5,"estimated_pay":118.5,"estimated_pay_items":[{"type":"per_delivery","name":"Per Delivery","rate":7,"quantity":12,"subtotal":84},{"type":"tip_pass_through","name":"Tips pass-through (%)","rate":100,"quantity":34.5,"subtotal":34.5}],"currency":"CAD","has_payroll_rule":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Driver profile not found"},"409":{"description":"Earnings view not enabled"}},"security":[{"bearerAuth":[]}]}},"/v1/dispatch-options":{"get":{"tags":["Dispatch Options"],"summary":"Show my dispatch options","description":"Dispatch Options Center: every opt-in dispatch option family for the authenticated business, normalised with defaults. All families are off by default; a business that never opted in gets the defaults and behaves exactly as before. The module itself is granted per business by the platform (business_details.allow_dispatch_options): while it is not granted this endpoint answers 403 and every family reads as disabled.","responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"business_id":123,"families":["auto_assign","driver_duty","assign_quotes","ready_for_pickup","customer_alerts","delivery_tips","instant_kpi_report","reviews_center","tracking_page","consignee_profiles","payroll_v2","console_map_extras","public_order_forms","email_intake","pod_extras","console_onboarding"],"options":{"auto_assign":{"enabled":false,"scope":{"order_types":["I","D","P2P"],"channel_ids":[],"territory_ids":[]},"inhouse":{"enabled":true,"strategy":"nearest_to_pickup","max_pickup_distance_km":5,"max_open_orders":10,"delay_minutes":0,"accept_timeout_minutes":10,"fallback":"hold","require_fresh_position":true,"driver_pool":[]},"third_party":{"enabled":false,"strategy":"lowest_price","provider_priority":[],"delay_minutes":0,"max_fee":null,"fallback":"hold"},"hybrid_rules":[]}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business (client/employee) account"},"404":{"description":"Business settings not initialized"}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Dispatch Options"],"summary":"Partially update my dispatch options","description":"Body is {\"<family>\": {...}}. Only the submitted families change; each family is validated (unknown enum values, foreign territory/channel/provider ids rejected) and normalised. Unknown families are rejected with 400. Families: auto_assign, driver_duty, assign_quotes, ready_for_pickup, customer_alerts, delivery_tips, instant_kpi_report, reviews_center, tracking_page, consignee_profiles, payroll_v2, console_map_extras, public_order_forms, email_intake, pod_extras, console_onboarding (each family: {enabled: bool, ...family-specific keys}; see GET response for the normalised shape).","requestBody":{"required":true,"content":{"application/json":{"example":{"auto_assign":{"enabled":true,"scope":{"order_types":["D","P2P"]},"inhouse":{"strategy":"min_open_orders","max_open_orders":8,"fallback":"third_party"},"third_party":{"enabled":true,"strategy":"lowest_price","max_fee":25}}}}}},"responses":{"200":{"description":"Update applied","content":{"application/json":{"example":{"result":true,"business_id":123,"changed_families":["auto_assign"],"options":{"auto_assign":{"enabled":false,"scope":{"order_types":["I","D","P2P"],"channel_ids":[],"territory_ids":[]},"inhouse":{"enabled":true,"strategy":"nearest_to_pickup","max_pickup_distance_km":5,"max_open_orders":10,"delay_minutes":0,"accept_timeout_minutes":10,"fallback":"hold","require_fresh_position":true,"driver_pool":[]},"third_party":{"enabled":false,"strategy":"lowest_price","provider_priority":[],"delay_minutes":0,"max_fee":null,"fallback":"hold"},"hybrid_rules":[]}}}}}},"400":{"description":"Unknown family / empty body"},"401":{"description":"Unauthorized"},"403":{"description":"Read-only account"},"404":{"description":"Business settings not initialized"},"422":{"description":"Validation failed (errors keyed by field path)"}},"security":[{"bearerAuth":[]}]}},"/v1/dispatch-options/auto-assign/attempts":{"get":{"tags":["Dispatch Options"],"summary":"Recent auto-assign orchestrator decisions","description":"Activity log of the opt-in auto-assign orchestrator: one row per decision (assigned / broadcast / held / skipped / failed / timed_out). Empty unless the business enabled auto_assign.","parameters":[{"name":"order_id","in":"query","required":false,"schema":{"type":"integer","description":"Limit to one order\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`."},"description":"Limit to one order\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":30,"maximum":200,"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `30` · max `200`."},"description":"Limit. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `integer` · Default: `30` · max `200`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"business_id":123,"attempts":[{"id":1,"order_id":555,"order_ref":"SR100000555","order_type":"D","trigger":"created","stage":"inhouse","strategy":"nearest_to_pickup","status":"assigned","reason":null,"driver_id":12,"driver":"Alex","provider_id":null,"provider":null,"route_id":9001,"assignment_id":null,"detail":{"pipeline":"route_build","distance_km":1.8},"expires_at":null,"resolved_at":"2026-08-17 10:00:05","created_at":"2026-08-17 10:00:05"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"}},"security":[{"bearerAuth":[]}]}},"/v1/dispatch-options/assign-candidates/{orderId}":{"get":{"tags":["Dispatch Options"],"summary":"Quick-assign candidates for an order","description":"Ranked in-house drivers (distance to pickup, open orders, on-duty) next to live third-party quotes for one order. Requires the opt-in family assign_quotes (409 otherwise). Quotes are cached for quote_cache_seconds; pass refresh=1 to bypass.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","description":"Refresh. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `boolean`."},"description":"Refresh. Query parameter used to filter, sort, or paginate this request.\n\n**Details:** Optional · Type `boolean`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"order":{"id":555,"ref":"SO-100234","tracking_number":"SR100000555","type":"I","status_id":44,"driver_id":null,"route_id":null},"drivers":[{"driver_id":11,"name":"Alex (A1)","distance_km":1.2,"open_orders":1,"has_position":true,"in_area":true,"on_duty":true,"assign_mode":"instant"},{"driver_id":12,"name":"Bea","distance_km":null,"open_orders":0,"has_position":false,"in_area":true,"on_duty":true,"assign_mode":"instant"}],"third_party":{"enabled":true,"best_provider_id":5,"providers":[{"provider_id":5,"name":"Courier Co","covered":true,"quote":8.29,"currency":"CAD","note":null},{"provider_id":6,"name":"Other Co","covered":false,"quote":null,"currency":null,"note":"not_covered"}]},"generated_at":"2026-08-17 10:00:00","cached":false}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"Order not found"},"409":{"description":"assign_quotes not enabled"}},"security":[{"bearerAuth":[]}]}},"/v1/dispatch-options/assign-candidates/{orderId}/third-party":{"post":{"tags":["Dispatch Options"],"summary":"Assign the order to a third-party provider (quick assign)","description":"Creates the third-party assignment through the standard pipeline (guards, push, webhooks). Requires assign_quotes and the third-party delivery module.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"provider_id":5}}}},"responses":{"200":{"description":"Assigned","content":{"application/json":{"example":{"result":true,"assignment_id":91,"assignment_no":"TPD20260817100000ABC123","push_status":"pushed"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Order or provider not found"},"409":{"description":"Feature or module disabled"},"422":{"description":"Assignment refused (guard)"}},"security":[{"bearerAuth":[]}]}},"/v1/dispatch-options/orders/{orderId}/ready":{"post":{"tags":["Dispatch Options"],"summary":"Mark / unmark an order ready for pickup","description":"Ready-for-pickup mark (opt-in family ready_for_pickup; 409 otherwise). Marking ready emits order.ready (lifecycle webhooks) and, with automatic assignment set to \"when ready\", triggers the assignment. Client / employee accounts, and drivers when the option allows it.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"example":{"ready":true}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"example":{"result":true,"order_id":555,"ready":true,"ready_at":"2026-08-17 10:00:00"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not allowed"},"404":{"description":"Order not found"},"409":{"description":"Feature disabled or storage not migrated"}},"security":[{"bearerAuth":[]}]}},"/v1/reviews":{"get":{"tags":["Dispatch Options"],"summary":"List customer reviews (reviews center)","description":"Survey ratings with the delivering driver, escalation state and per-question answers. Opt-in family reviews_center; 409 with feature_enabled=false while off. Client / employee accounts.","parameters":[{"name":"from","in":"query","required":false,"description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-08-01`.","schema":{"type":"string","description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-08-01`."},"example":"2026-08-01"},{"name":"to","in":"query","required":false,"description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-08-17`.","schema":{"type":"string","description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-08-17`."},"example":"2026-08-17"},{"name":"driver_id","in":"query","required":false,"description":"Only this driver\n\nDriver id.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `11`.","schema":{"type":"integer","description":"Only this driver\n\nDriver id.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `11`."},"example":11},{"name":"min_rating","in":"query","required":false,"description":"1-5\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"1-5\n\n**Details:** Optional · Type `integer`."},"example":1},{"name":"max_rating","in":"query","required":false,"description":"1-5\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `3`.","schema":{"type":"integer","description":"1-5\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `3`."},"example":3},{"name":"escalation","in":"query","required":false,"description":"open | resolved\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","description":"open | resolved\n\n**Details:** Optional · Type `string`."},"example":"open"},{"name":"page","in":"query","required":false,"description":"Page (default 1)\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Page (default 1)\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"example":1},{"name":"per_page","in":"query","required":false,"description":"Rows per page (default 25, max 200)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Rows per page (default 25, max 200)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"example":25}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"items":[{"id":9001,"order_id":555,"ref":"ORD-555","customer":"Jane Doe","rating":2,"comments":"Driver was late","driver_id":11,"driver":"Alex (A)","escalation_status":"open","escalated_at":"2026-08-17 10:05:00","resolved_at":null,"resolution_note":null,"answers":[{"question_id":3,"question":"How was the driver?","rating":2,"text":null}],"created_at":"2026-08-17 10:05:00"}],"total":120,"page":1,"per_page":25}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/reviews/summary":{"get":{"tags":["Dispatch Options"],"summary":"Reviews summary and driver ranking (reviews center)","description":"Rating distribution, average, low-rating and escalation counts, plus the per-driver ranking. Opt-in family reviews_center; 409 while off.","parameters":[{"name":"from","in":"query","required":false,"description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-08-01`.","schema":{"type":"string","description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-08-01`."},"example":"2026-08-01"},{"name":"to","in":"query","required":false,"description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-08-17`.","schema":{"type":"string","description":"YYYY-MM-DD\n\n**Details:** Optional · Type `string`.\n\n**Example:** `2026-08-17`."},"example":"2026-08-17"},{"name":"driver_id","in":"query","required":false,"description":"Only this driver\n\nDriver id.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `11`.","schema":{"type":"integer","description":"Only this driver\n\nDriver id.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `11`."},"example":11}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"summary":{"total":120,"average":4.35,"distribution":{"1":3,"2":5,"3":10,"4":30,"5":72},"low_ratings":18,"low_pct":15,"escalations_open":4,"escalations_resolved":14,"threshold":3,"driver_rating":4.5},"driver_ranking":[{"driver_id":11,"driver":"Alex (A)","rated_orders":40,"average":4.7,"low_ratings":1}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/reviews/{rateId}/resolve":{"post":{"tags":["Dispatch Options"],"summary":"Mark a review escalation as followed up (or reopen it)","description":"Escalation workflow of the reviews center (opt-in family reviews_center; 409 while off or when the storage migration has not run). Body: note (optional, max 1000 chars), reopen (optional bool).","parameters":[{"name":"rateId","in":"path","required":true,"schema":{"type":"integer","description":"Rate id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Rate id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"example":{"note":"Called the customer, refunded delivery fee","reopen":false}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"example":{"result":true,"id":9001,"escalation_status":"resolved"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"Review not found"},"409":{"description":"Feature disabled or storage not migrated"}},"security":[{"bearerAuth":[]}]}},"/v1/consignees":{"get":{"tags":["Dispatch Options"],"summary":"List recipient (consignee) profiles","description":"Recipient profiles aggregated from orders (opt-in family consignee_profiles; 409 with feature_enabled=false while off). Client / employee accounts.","parameters":[{"name":"q","in":"query","required":false,"description":"Name / phone / email / company / address search\n\n**Details:** Optional · Type `string`.\n\n**Example:** `Jane`.","schema":{"type":"string","description":"Name / phone / email / company / address search\n\n**Details:** Optional · Type `string`.\n\n**Example:** `Jane`."},"example":"Jane"},{"name":"vip","in":"query","required":false,"description":"Only VIP (true) / non-VIP (false)\n\n**Details:** Optional · Type `boolean`.\n\n**Example:** `true`.","schema":{"type":"boolean","description":"Only VIP (true) / non-VIP (false)\n\n**Details:** Optional · Type `boolean`.\n\n**Example:** `true`."},"example":true},{"name":"min_orders","in":"query","required":false,"description":"Minimum order count\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `2`.","schema":{"type":"integer","description":"Minimum order count\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `2`."},"example":2},{"name":"page","in":"query","required":false,"description":"Page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"example":1},{"name":"per_page","in":"query","required":false,"description":"Rows per page (max 200)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `25`.","schema":{"type":"integer","description":"Rows per page (max 200)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `25`."},"example":25}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"items":[{"id":41,"name":"Jane Doe","company_name":null,"phone":"+14165550123","email":"jane@example.com","last_address":"100 King St W, Toronto, M5X 1A9","is_vip":true,"default_instructions":"Leave with concierge","notes":"Prefers afternoon","orders_count":12,"delivered_count":11,"failed_count":1,"avg_rating":4.8,"tips_total":23.5,"first_order_at":"2026-01-10 09:12:00","last_order_at":"2026-08-15 14:02:00","last_order_id":5551}],"total":1,"page":1,"per_page":25}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/consignees/lookup":{"get":{"tags":["Dispatch Options"],"summary":"Look up the recipient profile behind a phone / email","description":"Profile + recent orders for a recipient (opt-in family consignee_profiles). Phone is normalised (E.164 when parseable, else digits); email is the fallback identity.","parameters":[{"name":"phone","in":"query","required":false,"description":"Recipient phone\n\nPhone number used for OTP or contact.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `416-555-0123`.","schema":{"type":"string","description":"Recipient phone\n\nPhone number used for OTP or contact.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `416-555-0123`."},"example":"416-555-0123"},{"name":"email","in":"query","required":false,"description":"Recipient email\n\nAccount email address.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `jane@example.com`.","schema":{"type":"string","description":"Recipient email\n\nAccount email address.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `jane@example.com`."},"example":"jane@example.com"},{"name":"country","in":"query","required":false,"description":"ISO-2 country for phone parsing\n\nISO country code or country name accepted by the address pipeline.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `CA`.","schema":{"type":"string","description":"ISO-2 country for phone parsing\n\nISO country code or country name accepted by the address pipeline.\n\n**Details:** Optional · Type `string`.\n\n**Example:** `CA`."},"example":"CA"},{"name":"recent","in":"query","required":false,"description":"Recent orders to include (default 5)\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Recent orders to include (default 5)\n\n**Details:** Optional · Type `integer`."},"example":5}],"responses":{"200":{"description":"successful operation (found may be false)","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"found":true,"profile":{"id":41,"name":"Jane Doe","company_name":null,"phone":"+14165550123","email":"jane@example.com","last_address":"100 King St W, Toronto, M5X 1A9","is_vip":true,"default_instructions":"Leave with concierge","notes":"Prefers afternoon","orders_count":12,"delivered_count":11,"failed_count":1,"avg_rating":4.8,"tips_total":23.5,"first_order_at":"2026-01-10 09:12:00","last_order_at":"2026-08-15 14:02:00","last_order_id":5551},"recent_orders":[{"id":5551,"ref":"ORD-5551","status_id":8,"status":"Successful","address":"100 King St W, Toronto","created_at":"2026-08-15 14:02:00"}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/consignees/{id}":{"put":{"tags":["Dispatch Options"],"summary":"Update a recipient profile (VIP, default instructions, notes)","description":"Editable part of a recipient profile (opt-in family consignee_profiles). Only the keys sent are changed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"is_vip":true,"default_instructions":"Leave with concierge","notes":"Prefers afternoon"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"example":{"result":true,"profile":{"id":41,"name":"Jane Doe","company_name":null,"phone":"+14165550123","email":"jane@example.com","last_address":"100 King St W, Toronto, M5X 1A9","is_vip":true,"default_instructions":"Leave with concierge","notes":"Prefers afternoon","orders_count":12,"delivered_count":11,"failed_count":1,"avg_rating":4.8,"tips_total":23.5,"first_order_at":"2026-01-10 09:12:00","last_order_at":"2026-08-15 14:02:00","last_order_id":5551}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"Profile not found"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders/{orderId}/cash-collected":{"post":{"tags":["Dispatch Options"],"summary":"Driver records cash collected on an order (payroll v2)","description":"Cash-collected settlement (opt-in family payroll_v2 with cash_settlement; 409 while off or storage not migrated). Payroll generation nets the collected cash out of the driver's pay (payment_after_cash). Send amount null to clear. Driver accounts; the order must be assigned to the driver.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."},"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"amount":42.5}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"example":{"result":true,"order_id":555,"cash_collected":42.5}}}},"401":{"description":"Unauthorized"},"403":{"description":"Order not assigned to this driver"},"404":{"description":"Order not found"},"409":{"description":"Feature disabled or storage not migrated"},"422":{"description":"Amount out of range"}},"security":[{"bearerAuth":[]}]}},"/third-party-delivery/carrier-webhook/{apiType}/{providerId}":{"post":{"tags":["ThirdPartyDelivery"],"summary":"Inbound on-demand courier webhook (DoorDash Drive, Uber Direct)","description":"Public per-provider URL registered in the carrier's developer portal. No API token: DoorDash requests are authenticated with the provider's webhook auth token (Bearer or Basic password), Uber Direct requests with the X-Postmates-Signature HMAC-SHA256 of the raw body using the provider's webhook signing key. Recognised delivery-status events update the assignment like the classic webhook; courier location / unknown events are acknowledged and ignored; an unknown delivery id is answered 200 so the carrier stops retrying. Only api types flagged carrier_webhook (doordash_drive, uber_direct).","parameters":[{"name":"apiType","in":"path","required":true,"schema":{"type":"string","enum":["doordash_drive","uber_direct"],"description":"Allowed values: `doordash_drive` · `uber_direct`.\n\n**Details:** Required · Type `string`."},"description":"Allowed values: `doordash_drive` · `uber_direct`.\n\n**Details:** Required · Type `string`."},{"name":"providerId","in":"path","required":true,"schema":{"type":"integer","description":"Provider id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."},"description":"Provider id. Primary key or resource identifier in the URL path.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"doordash":{"summary":"DoorDash Drive event","value":{"event_name":"DASHER_DROPPED_OFF","external_delivery_id":"SRDD-555-A77","delivery_status":"delivered","created_at":"2026-08-17T20:01:00Z","dasher_name":"Sam"}},"uber":{"summary":"Uber Direct event","value":{"kind":"event.delivery_status","delivery_id":"del_abc","status":"delivered","created":"2026-08-17T20:05:00Z","data":{"id":"del_abc","status":"delivered","courier":{"name":"Kim"}}}}}}}},"responses":{"200":{"description":"Accepted (or ignored / assignment not found)","content":{"application/json":{"example":{"result":true,"data":{"order_id":555,"duplicate":false,"tracking_event_id":9001}}}}},"401":{"description":"Signature / token verification failed"},"404":{"description":"Unknown carrier or provider"},"422":{"description":"Unrecognised payload"}}}},"/intake/email/inbound":{"post":{"tags":["Orders"],"summary":"Inbound email webhook for order intake (mail-provider callback)","description":"Dispatch Options → email_intake. Point your mail provider's inbound route (Mailgun routes / SendGrid inbound parse) at this URL for the intake domain. The business is identified by the token in the recipient address (orders-<token>@<intake domain>); optional Mailgun signature verification (timestamp/token/signature) when EMAIL_INTAKE_MAILGUN_SIGNING_KEY is set. Accepts recipient|to, sender|from, subject, stripped-text|body-plain|text (or body-html), Message-Id. Every accepted email is stored in the business's confirmation queue with a parsed order candidate; when auto-create is on and the candidate is complete, the order is created immediately. Answers 406 for unknown recipients so the provider stops retrying, 403 for senders outside the allow-list, 200 with duplicate=true for a repeated Message-Id.","requestBody":{"required":true,"content":{"multipart/form-data":{"example":{"recipient":"orders-abcdef123456@intake.superroute.ca","sender":"Shop <orders@shop.example.com>","subject":"Delivery request","body-plain":"Name: Jane Doe\nPhone: 416-555-0123\nAddress: 100 King St W\nCity: Toronto\nPostal code: M5X 1A9","Message-Id":"<m1@shop>"}}}},"responses":{"200":{"description":"Stored (and possibly auto-created)","content":{"application/json":{"example":{"result":true,"id":12,"confidence":94,"missing":[],"auto_created":false,"order_id":null}}}},"401":{"description":"Invalid Mailgun signature"},"403":{"description":"Sender not allowed"},"406":{"description":"Unknown recipient / intake disabled"}}}},"/v1/driver/pod-requirements":{"get":{"tags":["Dispatch Options"],"summary":"POD requirements at stop completion (driver app)","description":"Dispatch Options → pod_extras. Tells the app what to collect before completing a stop. While off every flag is false and geofence_m is 0. When on, POST /v1/driver/update-deliver additionally accepts age_verified (bool) and geofence_override_reason (string) and answers 422 with pod_requirement = pod_age_verification_required | pod_pickup_photo_required | pod_item_check_required | pod_geofence | pod_geofence_no_position when a requirement is not met.","responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"enabled":true,"age_verification_required":true,"pickup_photo_required":false,"item_check_required":true,"geofence_m":150,"geofence_allow_override":true}}}},"401":{"description":"Unauthorized"},"404":{"description":"Driver profile not found"}},"security":[{"bearerAuth":[]}]}},"/v1/orders/{orderId}/chat":{"get":{"tags":["Order Chat"],"summary":"Order chat thread (dispatcher view)","description":"Messages, unread counters and participants of one of your orders' chat threads. The thread is created lazily. Use `since_id` to poll for newer messages.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."},"example":5551,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."},{"name":"since_id","in":"query","required":false,"description":"Only messages with an id greater than this\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `0`.","schema":{"type":"integer","description":"Only messages with an id greater than this\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `0`."},"example":0}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"conversation":{"id":12,"order_id":5551,"status":"open","locked":false,"last_message_at":"2026-09-01 14:02:00","unread":{"dispatcher":1,"driver":0,"customer":0},"can_send":true,"driver_chat":true,"customer_chat":false,"driver_to_customer":false,"allow_attachments":true,"quick_replies":["On my way","Running late"]},"order":{"id":5551,"ref":"ORD-5551","tracking_number":"SR123456","status_id":16,"driver_id":11,"driver_alias":"Alex"},"messages":[{"id":101,"conversation_id":12,"sender_type":"driver","sender_user_id":901,"sender_name":"Alex","body":"On my way","attachment_url":null,"delivered_to":["dispatcher"],"created_at":"2026-09-01 14:02:00","read_at_dispatcher":null,"read_at_driver":"2026-09-01 14:02:00","read_at_customer":null}],"poll_interval":15}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a client / employee account"},"404":{"description":"Order not found (or not visible to the caller)"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Order Chat"],"summary":"Send a dispatcher message into an order chat","description":"Posts a message into the order's thread. `audience` narrows delivery to `driver` or `customer` (default `all` = everyone the option allows). Send an image either as multipart `attachment` or as `attachment_base64` (jpeg/png/webp/gif, max 5 MB by default). Locked threads answer 409 with `locked: true`. Throttled 60/min.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."},"example":5551,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"body":"Please call the customer before arriving","audience":"driver","attachment_base64":null}},"multipart/form-data":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Body. Field in the JSON request body.\n\n**Details:** Type `string`."},"audience":{"type":"string","enum":["all","driver","customer"],"description":"Allowed values: `all` · `driver` · `customer`.\n\n**Details:** Type `string`."},"attachment":{"type":"string","format":"binary","description":"Attachment. Field in the JSON request body.\n\n**Details:** Type `string`, format `binary`."}}}}}},"responses":{"200":{"description":"Message stored (and pushed live)","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"message":{"id":102,"conversation_id":12,"sender_type":"dispatcher","sender_user_id":700,"sender_name":"Ops Team","body":"Please call the customer before arriving","attachment_url":null,"delivered_to":["driver"],"created_at":"2026-09-01 14:05:00","read_at_dispatcher":"2026-09-01 14:05:00","read_at_driver":null,"read_at_customer":null},"conversation":{"id":12,"order_id":5551,"status":"open","locked":false,"last_message_at":"2026-09-01 14:05:00","unread":{"dispatcher":0,"driver":1,"customer":0}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a client / employee account"},"404":{"description":"Order not found"},"409":{"description":"Feature disabled, or conversation locked ({locked: true})"},"422":{"description":"Empty body without attachment, body too long, bad audience, attachment refused"}},"security":[{"bearerAuth":[]}]}},"/v1/orders/{orderId}/chat/read":{"post":{"tags":["Order Chat"],"summary":"Mark an order chat as read (dispatcher)","description":"Stamps read_at_dispatcher on every message and clears the dispatcher unread counter.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."},"example":5551,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."}],"responses":{"200":{"description":"Marked read","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"order_id":5551,"unread":0}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a client / employee account"},"404":{"description":"Order not found"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/order-chat/inbox":{"get":{"tags":["Order Chat"],"summary":"Order chat inbox","description":"Recent conversations of your business with unread counters and the last message, most recent first.","parameters":[{"name":"unread_only","in":"query","required":false,"description":"Only conversations with unread messages for the dispatcher\n\n**Details:** Optional · Type `boolean`.","schema":{"type":"boolean","description":"Only conversations with unread messages for the dispatcher\n\n**Details:** Optional · Type `boolean`."},"example":false},{"name":"q","in":"query","required":false,"description":"Search by order ref, tracking number or recipient name\n\n**Details:** Optional · Type `string`.\n\n**Example:** `ORD-5551`.","schema":{"type":"string","description":"Search by order ref, tracking number or recipient name\n\n**Details:** Optional · Type `string`.\n\n**Example:** `ORD-5551`."},"example":"ORD-5551"},{"name":"driver_id","in":"query","required":false,"description":"Only orders assigned to this driver\n\nDriver id.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `11`.","schema":{"type":"integer","description":"Only orders assigned to this driver\n\nDriver id.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `11`."},"example":11},{"name":"limit","in":"query","required":false,"description":"Rows (default 50, max 200)\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Rows (default 50, max 200)\n\n**Details:** Optional · Type `integer`."},"example":50}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"items":[{"id":12,"order_id":5551,"status":"open","locked":false,"last_message_at":"2026-09-01 14:02:00","unread":{"dispatcher":1,"driver":0,"customer":0},"order":{"id":5551,"ref":"ORD-5551","tracking_number":"SR123456","name":"Jane Doe","address":"100 King St W, Toronto","status_id":16,"driver_id":11,"driver_alias":"Alex"},"last_message":{"id":101,"sender_type":"driver","sender_name":"Alex","body":"On my way","attachment_url":null,"created_at":"2026-09-01 14:02:00"}}],"unread_total":1,"total":1}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a client / employee account"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders/{orderId}/chat":{"get":{"tags":["Order Chat"],"summary":"Order chat thread (driver view)","description":"Chat thread of one of the calling driver's assigned orders: only messages delivered to the driver. Orders not assigned to the caller answer 404. Requires the `driver_chat` switch of the option.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."},"example":5551,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."},{"name":"since_id","in":"query","required":false,"description":"Only messages with an id greater than this\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `0`.","schema":{"type":"integer","description":"Only messages with an id greater than this\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `0`."},"example":0}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"conversation":{"id":12,"order_id":5551,"status":"open","locked":false,"last_message_at":"2026-09-01 14:05:00","unread":{"dispatcher":0,"driver":1,"customer":0},"can_send":true,"driver_chat":true,"customer_chat":false,"driver_to_customer":false,"allow_attachments":true,"quick_replies":["On my way","Running late"]},"order":{"id":5551,"ref":"ORD-5551","tracking_number":"SR123456","status_id":16,"driver_id":11,"driver_alias":"Alex"},"messages":[{"id":102,"conversation_id":12,"sender_type":"dispatcher","sender_user_id":700,"sender_name":"Ops Team","body":"Please call the customer before arriving","attachment_url":null,"delivered_to":["driver"],"created_at":"2026-09-01 14:05:00","read_at_dispatcher":"2026-09-01 14:05:00","read_at_driver":null,"read_at_customer":null}],"poll_interval":15}}}},"401":{"description":"Unauthorized"},"404":{"description":"Driver profile not found, or order not assigned to the caller"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Order Chat"],"summary":"Send a driver message into an order chat","description":"Posts a driver message into the thread of one of the caller's assigned orders. Reaches the dispatcher, and the customer too when `driver_to_customer` is on. Image as multipart `attachment` or `attachment_base64`. Throttled 60/min.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."},"example":5551,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"body":"On my way","attachment_base64":null}},"multipart/form-data":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Body. Field in the JSON request body.\n\n**Details:** Type `string`."},"attachment":{"type":"string","format":"binary","description":"Attachment. Field in the JSON request body.\n\n**Details:** Type `string`, format `binary`."}}}}}},"responses":{"200":{"description":"Message stored","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"message":{"id":103,"conversation_id":12,"sender_type":"driver","sender_user_id":901,"sender_name":"Alex","body":"On my way","attachment_url":null,"delivered_to":["dispatcher"],"created_at":"2026-09-01 14:06:00","read_at_dispatcher":null,"read_at_driver":"2026-09-01 14:06:00","read_at_customer":null},"conversation":{"id":12,"order_id":5551,"status":"open","locked":false,"last_message_at":"2026-09-01 14:06:00","unread":{"dispatcher":1,"driver":0,"customer":0}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Driver profile not found, or order not assigned to the caller"},"409":{"description":"Feature disabled, or conversation locked"},"422":{"description":"Empty body without attachment, body too long, attachment refused"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/orders/{orderId}/chat/read":{"post":{"tags":["Order Chat"],"summary":"Mark an order chat as read (driver)","description":"Stamps read_at_driver on every message delivered to the driver and clears the driver unread counter.","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."},"example":5551,"description":"Superroute order id (`orders.id`).\n\n**Details:** Required · Type `integer`.\n\n**Example:** `5551`."}],"responses":{"200":{"description":"Marked read","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"order_id":5551,"unread":0}}}},"401":{"description":"Unauthorized"},"404":{"description":"Driver profile not found, or order not assigned to the caller"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/driver/chat/unread":{"get":{"tags":["Order Chat"],"summary":"Driver unread chat counters","description":"Per-order unread chat message counters for the calling driver's assigned orders. Answers 409 with `feature_enabled: false` while the option (or its `driver_chat` switch) is off.","responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"items":[{"order_id":5551,"order_ref":"ORD-5551","unread":1,"last_message_at":"2026-09-01 14:05:00"}],"unread_total":1}}}},"401":{"description":"Unauthorized"},"404":{"description":"Driver profile not found"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/ai-ops/conversations":{"get":{"tags":["Operations AI Agent"],"summary":"List operations AI agent conversations","description":"Conversations of the authenticated business (console assistant, tracking-page care agent, suggestions), newest first, with today's turn usage. Contractor (broker) accounts only see their own.","parameters":[{"name":"surface","in":"query","required":false,"description":"console | tracking | suggestion\n\nAllowed values: `console` · `tracking` · `suggestion`.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","enum":["console","tracking","suggestion"],"description":"console | tracking | suggestion\n\nAllowed values: `console` · `tracking` · `suggestion`.\n\n**Details:** Optional · Type `string`."},"example":"console"},{"name":"status","in":"query","required":false,"description":"open | closed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `open` · `closed`.\n\n**Details:** Optional · Type `string`.","schema":{"type":"string","enum":["open","closed"],"description":"open | closed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `open` · `closed`.\n\n**Details:** Optional · Type `string`."},"example":"open"},{"name":"order_id","in":"query","required":false,"description":"Only conversations attached to this order\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `5551`.","schema":{"type":"integer","description":"Only conversations attached to this order\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `5551`."},"example":5551},{"name":"page","in":"query","required":false,"description":"Page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`.","schema":{"type":"integer","description":"Page\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"example":1},{"name":"per_page","in":"query","required":false,"description":"Rows per page (max 100)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `25`.","schema":{"type":"integer","description":"Rows per page (max 100)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`.\n\n**Example:** `25`."},"example":25}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"items":[{"id":12,"business_id":830,"user_id":831,"surface":"console","order_id":null,"title":"Anything late on route 7?","status":"open","turns_count":3,"prompt_tokens":2140,"completion_tokens":310,"last_message_at":"2026-09-01 14:02:11","created_at":"2026-09-01 13:55:40"}],"total":1,"page":1,"per_page":25,"usage":{"used":3,"cap":500,"remaining":497}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature disabled","content":{"application/json":{"example":{"result":false,"feature_enabled":false,"message":"The operations AI agent is not enabled for this business."}}}},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Operations AI Agent"],"summary":"Start an operations AI agent conversation","description":"Opens a console conversation. With `message`, the first turn is answered in the same call: the agent may call the User MCP read tools (personal data masked) and propose writes through propose_write — a proposal becomes a pending row on /mcp-approvals and is never executed by the agent.","requestBody":{"required":false,"content":{"application/json":{"example":{"title":"Morning check","order_id":null,"message":"Which orders on today's routes are already late?","lang":"en"}}}},"responses":{"201":{"description":"Created (with the first answer when `message` was sent)","content":{"application/json":{"example":{"result":true,"status":"ok","reply":"Two stops are past their window: REF-5551 (route 7, 45 min late) and REF-5562 (route 9, 12 min late).","message":{"id":42,"role":"assistant","content":"Two stops are past their window: REF-5551 (route 7, 45 min late) and REF-5562 (route 9, 12 min late).","tool_calls":[],"tool_results":[],"approval_id":null,"created_at":"2026-09-01 14:02:11"},"tool_calls":[{"name":"list_exceptions","ok":true,"approval_id":null}],"approvals":[],"usage":{"used":4,"cap":500,"remaining":496},"tokens":{"prompt":1830,"completion":96},"error":null,"conversation":{"id":12,"business_id":830,"user_id":831,"surface":"console","order_id":null,"title":"Morning check","status":"open","turns_count":1,"prompt_tokens":1830,"completion_tokens":96,"last_message_at":"2026-09-01 14:02:11","created_at":"2026-09-01 14:01:50"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"order_id not found for this business"},"409":{"description":"Feature disabled"},"422":{"description":"Validation error"},"429":{"description":"Daily turn cap reached","content":{"application/json":{"example":{"result":false,"error_code":"DAILY_CAP_REACHED","message":"The daily turn cap for the operations agent has been reached.","usage":{"used":500,"cap":500,"remaining":0}}}}},"502":{"description":"The model did not produce an answer"},"503":{"description":"No AI service key configured"}},"security":[{"bearerAuth":[]}]}},"/v1/ai-ops/conversations/{id}":{"get":{"tags":["Operations AI Agent"],"summary":"One conversation with its transcript","description":"The conversation plus every message: user turns, tool rounds (tool_calls / tool_results, personal data masked) and assistant answers, with the approval id created whenever the agent proposed a change.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"conversation":{"id":12,"business_id":830,"user_id":831,"surface":"console","order_id":null,"title":"Cancel order 5551","status":"open","turns_count":1,"prompt_tokens":620,"completion_tokens":48,"last_message_at":"2026-09-01 14:02:11","created_at":"2026-09-01 14:01:50","messages":[{"id":40,"role":"user","content":"Cancel order 5551, the customer called.","tool_calls":[],"tool_results":[],"approval_id":null,"created_at":"2026-09-01 14:01:50"},{"id":41,"role":"tool","content":null,"tool_calls":[{"name":"propose_write","args":{"tool_name":"cancel_order","arguments":{"order_id":5551},"summary":"Customer called to cancel"}}],"tool_results":[{"name":"propose_write","ok":true,"result":{"status":"pending","approval_id":77,"tool_name":"cancel_order","risk":"high","review_url":"/mcp-approvals/77"},"error":null,"approval_id":77}],"approval_id":77,"created_at":"2026-09-01 14:02:05"},{"id":42,"role":"assistant","content":"I submitted the cancellation of order 5551 for approval (proposal #77).","tool_calls":[],"tool_results":[],"approval_id":77,"created_at":"2026-09-01 14:02:11"}]}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"Conversation not found"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/ai-ops/conversations/{id}/messages":{"post":{"tags":["Operations AI Agent"],"summary":"Send a message to a conversation","description":"One user turn in an open console conversation. The answer comes back with the tool calls made and the approval ids of any proposed change (propose_write → McpWriteApproval, reviewed on /mcp-approvals). Never executes a write.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"message":"Cancel order 5551, the customer called.","lang":"en"}}}},"responses":{"200":{"description":"Answered","content":{"application/json":{"example":{"result":true,"status":"ok","reply":"I submitted the cancellation of order 5551 for approval (proposal #77). A dispatcher needs to approve it on /mcp-approvals before it takes effect.","message":{"id":45,"role":"assistant","content":"I submitted the cancellation of order 5551 for approval (proposal #77). A dispatcher needs to approve it on /mcp-approvals before it takes effect.","tool_calls":[],"tool_results":[],"approval_id":77,"created_at":"2026-09-01 14:06:30"},"tool_calls":[{"name":"propose_write","ok":true,"approval_id":77}],"approvals":[77],"usage":{"used":5,"cap":500,"remaining":495},"tokens":{"prompt":2210,"completion":74},"error":null,"conversation":{"id":12,"business_id":830,"user_id":831,"surface":"console","order_id":null,"title":"Morning check","status":"open","turns_count":2,"prompt_tokens":4040,"completion_tokens":170,"last_message_at":"2026-09-01 14:06:30","created_at":"2026-09-01 14:01:50"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"Conversation not found"},"409":{"description":"Feature disabled, or the conversation is closed"},"422":{"description":"Validation error / not a console conversation"},"429":{"description":"Daily turn cap reached"},"502":{"description":"The model did not produce an answer"},"503":{"description":"No AI service key configured"}},"security":[{"bearerAuth":[]}]}},"/v1/ai-ops/suggestions":{"get":{"tags":["Operations AI Agent"],"summary":"AI dispatcher suggestions (advice only)","description":"Prioritised suggestions computed from live signals — undelivered stops past their time window, on-duty drivers with no open work, unassigned backlog older than the configured threshold, failed stops today — phrased by the model and cached 5 minutes per business. Each `proposed_action` is a propose_write payload the caller may submit for human approval; nothing is executed automatically. Requires the family's dispatch_suggestions switch.","parameters":[{"name":"refresh","in":"query","required":false,"description":"Bypass the 5-minute cache\n\n**Details:** Optional · Type `boolean`.","schema":{"type":"boolean","description":"Bypass the 5-minute cache\n\n**Details:** Optional · Type `boolean`."},"example":false},{"name":"lang","in":"query","required":false,"description":"Language of the phrased suggestions (app locale code)\n\n**Details:** Optional · Type `string`.\n\n**Example:** `en`.","schema":{"type":"string","description":"Language of the phrased suggestions (app locale code)\n\n**Details:** Optional · Type `string`.\n\n**Example:** `en`."},"example":"en"}],"responses":{"200":{"description":"successful operation","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"enabled":true,"cached":false,"generated_by":"model","computed_at":"2026-09-01 14:05:00","signals":{"late_orders":1,"idle_drivers":1,"unassigned_backlog":3,"failed_today":0},"suggestions":[{"id":"backlog","priority":"high","signal":"unassigned_backlog","title":"3 unassigned orders, oldest waiting 190 min","detail":"Idle Ida is on duty with no open work: plan a route for the backlog.","order_id":5560,"proposed_action":{"tool_name":"build_route","arguments":{"route_name":"AI suggested route 2026-09-01","route_date":"2026-09-01","drivers":[{"id":12}]},"summary":"Build a route for the unassigned backlog with 1 idle driver(s)"}},{"id":"late-5551","priority":"medium","signal":"late_order","title":"Order REF-5551 is 45 min past its time window","detail":"Still Out For Delivery on route 7 (driver 11). Consider warning the customer or moving the stop.","order_id":5551,"proposed_action":{"tool_name":"update_order_note","arguments":{"order_id":5551,"note":"Running late: 45 min past the time window (AI suggestion)"},"summary":"Add a late-delivery note on order #5551"}}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature or dispatch_suggestions disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/sms-marketing/subscribers":{"get":{"tags":["SMS Marketing"],"summary":"List SMS marketing subscribers","description":"Subscribers of the business: double opt-in status (pending | subscribed | unsubscribed), consent evidence (time, IP, channel), tags and message counters.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","subscribed","unsubscribed"],"description":"Filter by status\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pending` · `subscribed` · `unsubscribed`.\n\n**Details:** Optional · Type `string`."},"description":"Filter by status\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pending` · `subscribed` · `unsubscribed`.\n\n**Details:** Optional · Type `string`."},{"name":"q","in":"query","required":false,"schema":{"type":"string","description":"Search name or phone digits\n\n**Details:** Optional · Type `string`."},"description":"Search name or phone digits\n\n**Details:** Optional · Type `string`."},{"name":"tag","in":"query","required":false,"schema":{"type":"string","description":"Only subscribers carrying this tag\n\n**Details:** Optional · Type `string`."},"description":"Only subscribers carrying this tag\n\n**Details:** Optional · Type `string`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":200,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `25` · max `200`."},"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `25` · max `200`."}],"responses":{"200":{"description":"Subscriber page","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"items":[{"id":12,"phone":"+14165550123","name":"Jane Doe","status":"subscribed","opt_in_source":"tracking_page","confirmed_via":"sms_reply","language":"en","consent_at":"2026-09-01 10:12:00","consent_ip":"203.0.113.4","unsubscribed_at":null,"unsubscribe_reason":null,"last_message_at":"2026-09-03 11:00:00","messages_sent_count":1,"tags":["vip"],"consignee_profile_id":41,"created_at":"2026-09-01 10:10:00"}],"total":1,"page":1,"per_page":25}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature disabled, revoked or not migrated"}},"security":[{"bearerAuth":[]}]}},"/v1/sms-marketing/subscribers/{id}/unsubscribe":{"post":{"tags":["SMS Marketing"],"summary":"Unsubscribe a subscriber","description":"Manual unsubscribe (idempotent). The number is never messaged again unless the recipient opts in anew from the tracking page.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"example":{"reason":"customer request"}}}},"responses":{"200":{"description":"Unsubscribed","content":{"application/json":{"example":{"result":true,"subscriber":{"id":12,"phone":"+14165550123","name":"Jane Doe","status":"unsubscribed","opt_in_source":"tracking_page","confirmed_via":"sms_reply","language":"en","consent_at":"2026-09-01 10:12:00","consent_ip":"203.0.113.4","unsubscribed_at":"2026-09-04 09:00:00","unsubscribe_reason":"customer request","last_message_at":"2026-09-03 11:00:00","messages_sent_count":1,"tags":["vip"],"consignee_profile_id":41,"created_at":"2026-09-01 10:10:00"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"Subscriber not found"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/sms-marketing/audience/preview":{"post":{"tags":["SMS Marketing"],"summary":"Audience size and sample for a segment","description":"Counts the confirmed subscribers matching a segment and returns a small masked sample. Segment types: all | first_order (exactly one order) | high_value (>= high_value_min_orders) | lapsed (no order for lapsed_after_days) | low_rating (latest survey rating <= 2) | pickup_only | tag.","requestBody":{"required":true,"content":{"application/json":{"example":{"segment":{"type":"lapsed","tag":null}}}}},"responses":{"200":{"description":"Preview","content":{"application/json":{"example":{"result":true,"count":38,"sample":[{"id":12,"name":"Jane Doe","phone":"••••••••0123"}],"segment":{"type":"lapsed","tag":null}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/sms-marketing/campaigns":{"get":{"tags":["SMS Marketing"],"summary":"List SMS marketing campaigns","description":"Campaigns with status (draft | scheduled | sending | sent | cancelled), segment, schedule and send counters.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","scheduled","sending","sent","cancelled"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `draft` · `scheduled` · `sending` · `sent` · `cancelled`.\n\n**Details:** Optional · Type `string`."},"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `draft` · `scheduled` · `sending` · `sent` · `cancelled`.\n\n**Details:** Optional · Type `string`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer` · Default: `1`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","default":25,"maximum":200,"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `25` · max `200`."},"description":"Number of items returned per page.\n\n**Details:** Optional · Type `integer` · Default: `25` · max `200`."}],"responses":{"200":{"description":"Campaign page","content":{"application/json":{"example":{"result":true,"feature_enabled":true,"items":[{"id":7,"name":"Fall offer","status":"sent","segment":{"type":"high_value","tag":null},"message_template":"Hi {name}, use {offer_code} at {business}!","offer_promotion_id":3,"scheduled_at":null,"started_at":"2026-09-03 11:00:00","finished_at":"2026-09-03 11:02:10","audience_count":120,"sent_count":112,"failed_count":1,"skipped_count":7,"created_by":860,"created_at":"2026-09-02 16:40:00"}],"total":1,"page":1,"per_page":25}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]},"post":{"tags":["SMS Marketing"],"summary":"Create an SMS marketing campaign","description":"Creates a draft campaign. Placeholders in message_template: {name} (first name), {offer_code}, {business}; the sender name and the unsubscribe footer are added automatically. offer_promotion_id must belong to the business: batch-coupon promotions hand one unique unused coupon per recipient, other promotions use their single coupon code. scheduled_at is read in the business timezone; with schedule=true the campaign is scheduled at once (started by the minutely scheduler). Returns the rendered preview for a sample recipient.","requestBody":{"required":true,"content":{"application/json":{"example":{"name":"Fall offer","message_template":"Hi {name}, use {offer_code} at {business}!","segment":{"type":"high_value","tag":null},"offer_promotion_id":3,"scheduled_at":"2026-09-10 10:00","schedule":true}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"result":true,"campaign":{"id":8,"name":"Fall offer","status":"scheduled","segment":{"type":"high_value","tag":null},"message_template":"Hi {name}, use {offer_code} at {business}!","offer_promotion_id":3,"scheduled_at":"2026-09-10 10:00:00","started_at":null,"finished_at":null,"audience_count":0,"sent_count":0,"failed_count":0,"skipped_count":0,"created_by":860,"created_at":"2026-09-03 12:00:00"},"preview":{"message":"Acme: Hi Jane, use FALL-A at Acme! Reply STOP to unsubscribe.","length":62,"segments":1}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"409":{"description":"Feature disabled"},"422":{"description":"Validation failed","content":{"application/json":{"example":{"result":false,"message":"Validation failed","errors":{"offer_promotion_id":["Promotion not found for this business"]}}}}}},"security":[{"bearerAuth":[]}]}},"/v1/sms-marketing/campaigns/{id}":{"get":{"tags":["SMS Marketing"],"summary":"One campaign with its send log","description":"Campaign details plus one row per recipient: queued | sent | failed | skipped with skip_reason (unsubscribed | weekly_cap | min_interval | no_offer_code | cancelled), offer code and Twilio message SID. Phones are masked.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"example":{"result":true,"campaign":{"id":7,"name":"Fall offer","status":"sent","segment":{"type":"high_value","tag":null},"message_template":"Hi {name}, use {offer_code} at {business}!","offer_promotion_id":3,"scheduled_at":null,"started_at":"2026-09-03 11:00:00","finished_at":"2026-09-03 11:02:10","audience_count":2,"sent_count":1,"failed_count":0,"skipped_count":1,"created_by":860,"created_at":"2026-09-02 16:40:00"},"sends":[{"id":901,"subscriber_id":12,"name":"Jane Doe","phone":"••••••••0123","status":"sent","skip_reason":null,"offer_code":"FALL-A","message_sid":"SM8f3c...","sent_at":"2026-09-03 11:00:04","error":null},{"id":902,"subscriber_id":13,"name":"Bob","phone":"••••••••0456","status":"skipped","skip_reason":"weekly_cap","offer_code":null,"message_sid":null,"sent_at":null,"error":null}]}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"Campaign not found"},"409":{"description":"Feature disabled"}},"security":[{"bearerAuth":[]}]}},"/v1/sms-marketing/campaigns/{id}/send":{"post":{"tags":["SMS Marketing"],"summary":"Send a campaign now, or schedule it","description":"Without a body: freezes the audience (confirmed subscribers of the segment) into send rows and queues batches that honour the weekly / interval caps, the business quiet hours (batches are deferred, recipients never skipped) and unsubscribes. With scheduled_at (business timezone) the campaign is scheduled instead. Idempotent for a campaign already sending; 409 for sent / cancelled campaigns.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":false,"content":{"application/json":{"example":{"scheduled_at":"2026-09-10 10:00"}}}},"responses":{"200":{"description":"Sending started (or scheduled)","content":{"application/json":{"example":{"result":true,"campaign":{"id":8,"name":"Fall offer","status":"sending","segment":{"type":"high_value","tag":null},"message_template":"Hi {name}, use {offer_code} at {business}!","offer_promotion_id":3,"scheduled_at":null,"started_at":"2026-09-03 12:05:00","finished_at":null,"audience_count":120,"sent_count":0,"failed_count":0,"skipped_count":0,"created_by":860,"created_at":"2026-09-03 12:00:00"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"Campaign not found"},"409":{"description":"Feature disabled, or campaign not in a sendable state"},"422":{"description":"Invalid scheduled_at"}},"security":[{"bearerAuth":[]}]}},"/v1/sms-marketing/campaigns/{id}/cancel":{"post":{"tags":["SMS Marketing"],"summary":"Cancel a campaign","description":"Cancels a draft, scheduled or sending campaign; recipients not yet messaged are marked skipped (cancelled). 409 for sent / already cancelled campaigns.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"example":{"result":true,"campaign":{"id":8,"name":"Fall offer","status":"cancelled","segment":{"type":"high_value","tag":null},"message_template":"Hi {name}, use {offer_code} at {business}!","offer_promotion_id":3,"scheduled_at":null,"started_at":"2026-09-03 12:05:00","finished_at":"2026-09-03 12:06:30","audience_count":120,"sent_count":50,"failed_count":0,"skipped_count":70,"created_by":860,"created_at":"2026-09-03 12:00:00"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not a business account"},"404":{"description":"Campaign not found"},"409":{"description":"Feature disabled, or campaign already sent / cancelled"}},"security":[{"bearerAuth":[]}]}},"/sms-marketing/inbound":{"post":{"tags":["SMS Marketing"],"summary":"Twilio inbound SMS webhook (public)","description":"Configure as the Messaging webhook of the Twilio number used for SMS marketing (URL: https://<api-domain>/api/sms-marketing/inbound). Twilio form fields From, To, Body, MessageSid. The business is resolved from the sender's number (narrowed by To when several businesses share a subscriber), then the X-Twilio-Signature header is validated with that business's auth token (403 on mismatch). YES / OUI / SI / JA / CONFIRM / START confirm a pending opt-in; every configured unsubscribe keyword (STOP, UNSUBSCRIBE, CANCEL, END, QUIT, ARRET by default) unsubscribes. Idempotent per MessageSid. Always answers empty TwiML.","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"example":{"From":"+14165550123","To":"+15550001111","Body":"YES","MessageSid":"SM8f3c1d2e"}}}},"responses":{"200":{"description":"Acknowledged","content":{"text/xml":{"example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><Response></Response>"}}},"403":{"description":"Signature rejected"},"429":{"description":"Throttled"}}}},"/v1/apps/{appCode}/registration/clients":{"get":{"tags":["Platform Apps"],"summary":"List the Clients that accept new customer registrations","description":"Public and unauthenticated: this is the first call an app makes for a person who has no account yet, and it answers nothing account-specific. Only Clients whose assignment is effective, whose customer role is enabled and whose auth.registration capability is on are listed, so every entry is a door that will actually accept a sign-up. When `count` is 1 the app can skip the picker and open the registration form directly.","operationId":"platformAppRegistrationClients","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."}],"responses":{"200":{"description":"The Clients open to registration for this app.","content":{"application/json":{"example":{"result":true,"data":{"app":{"code":"mibox","name":"MiBox"},"count":2,"items":[{"client_code":"n4x7q2g8w9r3k6m1p5t0z8ab","display_name":"MiBox Toronto","logo_url":"https://cdn.example.com/mibox-to.png","primary_color":"#146C94","support_email":"support@example.com","privacy_url":"https://example.com/privacy","terms_url":"https://example.com/terms","requires_approval":true,"phone_verification_required":true,"sms_configured":true,"default_phone_region":"CA"},{"client_code":"b8k2m5q9w1e4r7t0y3u6i9op","display_name":"MiBox Vancouver","logo_url":null,"primary_color":"#146C94","support_email":null,"privacy_url":null,"terms_url":null,"requires_approval":false,"phone_verification_required":false,"sms_configured":false,"default_phone_region":"CA"}]}}}}},"404":{"description":"App not found or not active"}}}},"/v1/apps/{appCode}/account-closure/withdraw":{"post":{"tags":["Platform Apps"],"summary":"Withdraw a pending account closure request","description":"Unauthenticated by necessity: an open closure request suspends the account and revokes its tokens, so requiring a session would make the request impossible to take back. The one-shot `withdrawal_token` is the credential; it is returned once by the closure request itself, again in the notice email's link, and again in the 403 ACCOUNT_CLOSURE_PENDING body when a correct password is refused at sign-in. Withdrawing restores the account to exactly the status it held before the request.","operationId":"platformAppWithdrawAccountClosure","parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["withdrawal_token"],"properties":{"withdrawal_token":{"type":"string","maxLength":191,"description":"**Required.**\n\nWithdrawal token. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string` · maxLength `191`."}}},"example":{"withdrawal_token":"one-shot-withdrawal-token"}}}},"responses":{"200":{"description":"The request was withdrawn and the account restored.","content":{"application/json":{"example":{"result":true,"message":"The account closure request has been withdrawn.","data":{"id":42,"status":"cancelled","requested_at":"2026-09-05T10:00:00+00:00","cancelled_at":"2026-09-05T12:00:00+00:00","completed_at":null,"handled_at":null,"reason":"Moving away","decision_reason":null,"requires_review":true}}}}},"404":{"description":"No pending closure request matches this token"},"422":{"description":"Invalid request"}}}},"/v3/client/exclusion-zone-sets":{"get":{"tags":["Client"],"summary":"List exclusion zone sets","description":"Sets the caller can use when building routes, with their zones and the circumference of the zones in use. Business staff manage every set of the business. Contractors (brokers) can read and use the business's sets and manage only the sets they created; editing a business set returns 403. Requires Exclusion Zones to be enabled for the account by the platform administrator; while it is off every exclusion zone set operation answers 403 with error_code exclusion_zones_not_enabled.","operationId":"clientListExclusionZoneSets","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Exclusion zone sets","content":{"application/json":{"example":{"success":true,"data":[{"id":12,"name":"Bridge closures","description":"Weekend works","color":"#C23B2E","status":1,"owner":"business","broker_id":null,"can_edit":true,"perimeter_m":3899.4,"limit_m":100000,"zones":[{"id":31,"name":"Champlain approach","polygon":[[-73.56,45.5],[-73.55,45.5],[-73.55,45.51],[-73.56,45.51],[-73.56,45.5]],"effective_from":"2026-09-01","effective_until":"2026-09-30","status":1,"perimeter_m":3899.4}],"created_at":"2026-09-13 10:00:00","updated_at":"2026-09-13 10:00:00"}]}}}},"403":{"description":"Not allowed to use exclusion zones, or Exclusion Zones is not enabled for the account (error_code exclusion_zones_not_enabled)","content":{"application/json":{"example":{"success":false,"message":"Not allowed to use exclusion zones"}}}}}},"post":{"tags":["Client"],"summary":"Create an exclusion zone set","description":"Creates a set with its zones. A contractor's new set belongs to that contractor. Business staff manage every set of the business. Contractors (brokers) can read and use the business's sets and manage only the sets they created; editing a business set returns 403. Requires Exclusion Zones to be enabled for the account by the platform administrator; while it is off every exclusion zone set operation answers 403 with error_code exclusion_zones_not_enabled.","operationId":"clientCreateExclusionZoneSet","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `120`."},"description":{"type":["string","null"],"maxLength":2000,"description":"Free-text description.\n\n**Details:** Type `string` · Nullable · maxLength `2000`."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"Color. Field in the JSON request body.\n\n**Details:** Type `string` · pattern `^#[0-9a-fA-F]{6}$`.\n\n**Example:** `#C23B2E`.","examples":["#C23B2E"]},"status":{"type":"integer","enum":[0,1],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"zones":{"type":"array","maxItems":200,"items":{"type":"object","required":["polygon"],"properties":{"id":{"type":["integer","null"],"description":"Send on update to keep an existing zone\n\n**Details:** Type `integer` · Nullable."},"name":{"type":["string","null"],"maxLength":120,"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable · maxLength `120`."},"polygon":{"type":"array","minItems":3,"maxItems":1000,"items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number","description":"Polygon. Element of a list or map in the request/response payload.\n\n**Details:** Type `number`."},"description":"Polygon. Element of a list or map in the request/response payload.\n\n**Details:** Type `array`, items `number` · minItems `2` · maxItems `2`."},"description":"**Required.**\n\nRing of [lng, lat] corners; it is closed for you.\n\n**Details:** Type `array`, items `array` · minItems `3` · maxItems `1000`."},"effective_from":{"type":["string","null"],"format":"date","description":"First day the zone applies; empty for no start\n\n**Details:** Type `string`, format `date` · Nullable."},"effective_until":{"type":["string","null"],"format":"date","description":"Last day the zone applies; empty for no end\n\n**Details:** Type `string`, format `date` · Nullable."},"status":{"type":"integer","enum":[0,1],"description":"1 in use (default), 0 kept but ignored\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]}}},"description":"The complete zone list. Enabled zones may total at most 100 km of circumference (Valhalla's exclude_polygons limit).\n\n**Details:** Type `array`, items `object` · maxItems `200`."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"success":true,"data":{"id":12,"name":"Bridge closures","description":"Weekend works","color":"#C23B2E","status":1,"owner":"business","broker_id":null,"can_edit":true,"perimeter_m":3899.4,"limit_m":100000,"zones":[{"id":31,"name":"Champlain approach","polygon":[[-73.56,45.5],[-73.55,45.5],[-73.55,45.51],[-73.56,45.51],[-73.56,45.5]],"effective_from":"2026-09-01","effective_until":"2026-09-30","status":1,"perimeter_m":3899.4}],"created_at":"2026-09-13 10:00:00","updated_at":"2026-09-13 10:00:00"}}}}},"403":{"description":"Not allowed to use exclusion zones, or Exclusion Zones is not enabled for the account (error_code exclusion_zones_not_enabled)","content":{"application/json":{"example":{"success":false,"message":"Not allowed to use exclusion zones"}}}},"422":{"description":"Invalid shape or dates, or zones over the 100 km limit","content":{"application/json":{"example":{"success":false,"message":"Zones in use add up to 104.2 km, over the 100 km limit. Remove or shrink zones before saving.","errors":{"zones":["Zones in use add up to 104.2 km, over the 100 km limit. Remove or shrink zones before saving."]}}}}}}}},"/v3/client/exclusion-zone-sets/{id}":{"get":{"tags":["Client"],"summary":"Get an exclusion zone set","operationId":"clientGetExclusionZoneSet","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Exclusion zone set","content":{"application/json":{"example":{"success":true,"data":{"id":12,"name":"Bridge closures","description":"Weekend works","color":"#C23B2E","status":1,"owner":"business","broker_id":null,"can_edit":true,"perimeter_m":3899.4,"limit_m":100000,"zones":[{"id":31,"name":"Champlain approach","polygon":[[-73.56,45.5],[-73.55,45.5],[-73.55,45.51],[-73.56,45.51],[-73.56,45.5]],"effective_from":"2026-09-01","effective_until":"2026-09-30","status":1,"perimeter_m":3899.4}],"created_at":"2026-09-13 10:00:00","updated_at":"2026-09-13 10:00:00"}}}}},"404":{"description":"Exclusion zone set not found.","content":{"application/json":{"example":{"success":false,"message":"Exclusion zone set not found."}}}}}},"put":{"tags":["Client"],"summary":"Update an exclusion zone set","description":"Omitted fields keep their values. When zones is sent it replaces the whole list: zones without an id are added, listed ids are kept and updated, and unlisted zones are removed. Routes already built keep the zones they were planned with. Business staff manage every set of the business. Contractors (brokers) can read and use the business's sets and manage only the sets they created; editing a business set returns 403. Requires Exclusion Zones to be enabled for the account by the platform administrator; while it is off every exclusion zone set operation answers 403 with error_code exclusion_zones_not_enabled.","operationId":"clientUpdateExclusionZoneSet","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"name":{"type":"string","maxLength":120,"description":"Human-readable name.\n\n**Details:** Type `string` · maxLength `120`."},"description":{"type":["string","null"],"maxLength":2000,"description":"Free-text description.\n\n**Details:** Type `string` · Nullable · maxLength `2000`."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"Color. Field in the JSON request body.\n\n**Details:** Type `string` · pattern `^#[0-9a-fA-F]{6}$`.\n\n**Example:** `#C23B2E`.","examples":["#C23B2E"]},"status":{"type":"integer","enum":[0,1],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"zones":{"type":"array","maxItems":200,"items":{"type":"object","required":["polygon"],"properties":{"id":{"type":["integer","null"],"description":"Send on update to keep an existing zone\n\n**Details:** Type `integer` · Nullable."},"name":{"type":["string","null"],"maxLength":120,"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable · maxLength `120`."},"polygon":{"type":"array","minItems":3,"maxItems":1000,"items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number","description":"Polygon. Element of a list or map in the request/response payload.\n\n**Details:** Type `number`."},"description":"Polygon. Element of a list or map in the request/response payload.\n\n**Details:** Type `array`, items `number` · minItems `2` · maxItems `2`."},"description":"**Required.**\n\nRing of [lng, lat] corners; it is closed for you.\n\n**Details:** Type `array`, items `array` · minItems `3` · maxItems `1000`."},"effective_from":{"type":["string","null"],"format":"date","description":"First day the zone applies; empty for no start\n\n**Details:** Type `string`, format `date` · Nullable."},"effective_until":{"type":["string","null"],"format":"date","description":"Last day the zone applies; empty for no end\n\n**Details:** Type `string`, format `date` · Nullable."},"status":{"type":"integer","enum":[0,1],"description":"1 in use (default), 0 kept but ignored\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]}}},"description":"The complete zone list. Enabled zones may total at most 100 km of circumference (Valhalla's exclude_polygons limit).\n\n**Details:** Type `array`, items `object` · maxItems `200`."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"example":{"success":true,"data":{"id":12,"name":"Bridge closures","description":"Weekend works","color":"#C23B2E","status":1,"owner":"business","broker_id":null,"can_edit":true,"perimeter_m":3899.4,"limit_m":100000,"zones":[{"id":31,"name":"Champlain approach","polygon":[[-73.56,45.5],[-73.55,45.5],[-73.55,45.51],[-73.56,45.51],[-73.56,45.5]],"effective_from":"2026-09-01","effective_until":"2026-09-30","status":1,"perimeter_m":3899.4}],"created_at":"2026-09-13 10:00:00","updated_at":"2026-09-13 10:00:00"}}}}},"403":{"description":"You cannot change this zone set., or Exclusion Zones is not enabled for the account (error_code exclusion_zones_not_enabled)","content":{"application/json":{"example":{"success":false,"message":"You cannot change this zone set."}}}},"404":{"description":"Exclusion zone set not found.","content":{"application/json":{"example":{"success":false,"message":"Exclusion zone set not found."}}}},"422":{"description":"Invalid shape or dates, or zones over the 100 km limit","content":{"application/json":{"example":{"success":false,"message":"Zones in use add up to 104.2 km, over the 100 km limit. Remove or shrink zones before saving.","errors":{"zones":["Zones in use add up to 104.2 km, over the 100 km limit. Remove or shrink zones before saving."]}}}}}}},"delete":{"tags":["Client"],"summary":"Delete an exclusion zone set","description":"Routes already built keep the zones they were planned with. Business staff manage every set of the business. Contractors (brokers) can read and use the business's sets and manage only the sets they created; editing a business set returns 403. Requires Exclusion Zones to be enabled for the account by the platform administrator; while it is off every exclusion zone set operation answers 403 with error_code exclusion_zones_not_enabled.","operationId":"clientDeleteExclusionZoneSet","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"example":{"success":true,"data":{"id":12,"deleted":true}}}}},"403":{"description":"You cannot change this zone set., or Exclusion Zones is not enabled for the account (error_code exclusion_zones_not_enabled)","content":{"application/json":{"example":{"success":false,"message":"You cannot change this zone set."}}}},"404":{"description":"Exclusion zone set not found.","content":{"application/json":{"example":{"success":false,"message":"Exclusion zone set not found."}}}}}}},"/v3/client/exclusion-zone-sets/{id}/export":{"get":{"tags":["Exclusion Zones"],"operationId":"exclusionZoneSetExport","summary":"Export an exclusion zone set as a GeoJSON or KML file","description":"Downloads the set's active zones as GeoJSON (RFC 7946, application/geo+json) or KML 2.2. Exterior rings are written counter-clockwise per RFC 7946 while the stored shapes stay untouched. Contractor accounts only reach their own sets; the module must be enabled for the business.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"format","required":false,"schema":{"type":"string","enum":["geojson","kml"],"default":"geojson","description":"Allowed values: `geojson` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."},"description":"Allowed values: `geojson` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."}],"responses":{"200":{"description":"The file, as an attachment","content":{"application/geo+json":{"schema":{"type":"object","description":"An RFC 7946 FeatureCollection; one Feature per active zone with name, set_name, purpose, effective dates and color properties"}},"application/vnd.google-earth.kml+xml":{"schema":{"type":"string","description":"A KML 2.2 Document with one Placemark per active zone"}}}},"403":{"description":"Exclusion zones are not enabled for this business"},"404":{"description":"Zone set not found or not visible to this account"},"422":{"description":"Unsupported format"}}}},"/v3/client/exclusion-zone-sets/import/preview":{"post":{"tags":["Exclusion Zones"],"operationId":"exclusionZoneSetImportPreview","summary":"Preview a GeoJSON / KML / KMZ upload for import into an exclusion zone set","description":"Step one of the two-step import: parse the file and report each feature that would be imported (name, vertex count, perimeter) and each refusal with its reason (polygon_has_holes, over_perimeter_cap with the figure and the cap, too_many_vertices, invalid_ring, not_a_polygon). Nothing is written. Limits: 5 MB per file, 2000 features, 20000 vertices per ring; a KMZ is capped at 20 MB decompressed. The preview id is valid for 30 minutes and only for the uploader.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"**Required.**\n\nA .geojson, .json, .kml or .kmz file\n\n**Details:** Type `string`, format `binary`."}}}}}},"responses":{"200":{"description":"The preview","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"preview_id":{"type":"string","description":"Preview id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"expires_in_seconds":{"type":"integer","description":"Expires in seconds. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `1800`.","examples":[1800]},"features":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Index. Field in the JSON request body.\n\n**Details:** Type `integer`."},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable."},"vertices":{"type":"integer","description":"Vertices. Field in the JSON request body.\n\n**Details:** Type `integer`."},"perimeter_m":{"type":"number","description":"Perimeter m. Field in the JSON request body.\n\n**Details:** Type `number`."}}},"description":"Features. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"refused":{"type":"array","items":{"type":"object","properties":{"feature":{"type":"string","description":"Feature. Field in the JSON request body.\n\n**Details:** Type `string`."},"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."}}},"description":"Refused. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"403":{"description":"Exclusion zones are not enabled for this business"},"422":{"description":"The file does not parse, exceeds a limit, or no file was sent"}}}},"/v3/client/exclusion-zone-sets/import/commit":{"post":{"tags":["Exclusion Zones"],"operationId":"exclusionZoneSetImportCommit","summary":"Commit a previewed import into a new or existing exclusion zone set","description":"Step two of the two-step import: takes the preview id plus the caller's choices and writes through the set's own save path, so broker scope and the Valhalla perimeter cap apply unchanged. Target new creates a set, append adds to an existing set, replace substitutes an existing set's zones.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["preview_id"],"properties":{"preview_id":{"type":"string","description":"**Required.**\n\nPreview id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"target":{"type":"string","enum":["new","append","replace"],"default":"new","description":"Allowed values: `new` · `append` · `replace`.\n\n**Details:** Type `string` · Default: `new`."},"set_id":{"type":"integer","description":"The target set for append / replace\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"The name of a new set\n\n**Details:** Type `string`."},"feature_indexes":{"type":"array","items":{"type":"integer","description":"Feature indexes. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Preview feature indexes to import; all when absent\n\n**Details:** Type `array`, items `integer`."},"names":{"type":"object","description":"Per-feature name overrides, keyed by preview index\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"The written set","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"set_id":{"type":"integer","description":"Set id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"set_name":{"type":"string","description":"Set name. Human-readable label.\n\n**Details:** Type `string`."},"zones":{"type":"integer","description":"Zones. Field in the JSON request body.\n\n**Details:** Type `integer`."}}}}}},"403":{"description":"Not authorized to change the target set, or the module is off"},"404":{"description":"Target set not found"},"422":{"description":"Preview expired, nothing selected, or the save was refused (the response carries errors)"}}}},"/v3/client/planning-area-sets/{id}/export":{"get":{"tags":["Planning Areas"],"operationId":"planningAreaSetExport","summary":"Export a planning area set as a GeoJSON or KML file","description":"Same contract as the exclusion zone set export, for planning areas. No module gate and no perimeter cap: planning areas never reach the routing engine.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"format","required":false,"schema":{"type":"string","enum":["geojson","kml"],"default":"geojson","description":"Allowed values: `geojson` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."},"description":"Allowed values: `geojson` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."}],"responses":{"200":{"description":"The file, as an attachment","content":{"application/geo+json":{"schema":{"type":"object","description":"An RFC 7946 FeatureCollection; one Feature per active area"}},"application/vnd.google-earth.kml+xml":{"schema":{"type":"string","description":"A KML 2.2 Document with one Placemark per active area"}}}},"404":{"description":"Zone set not found or not visible to this account"},"422":{"description":"Unsupported format"}}}},"/v3/client/planning-area-sets/import/preview":{"post":{"tags":["Planning Areas"],"operationId":"planningAreaSetImportPreview","summary":"Preview a GeoJSON / KML / KMZ upload for import into a planning area set","description":"Same contract as the exclusion zone set import preview, without the perimeter cap: planning areas never reach the routing engine.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"**Required.**\n\nA .geojson, .json, .kml or .kmz file\n\n**Details:** Type `string`, format `binary`."}}}}}},"responses":{"200":{"description":"The preview","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"preview_id":{"type":"string","description":"Preview id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"expires_in_seconds":{"type":"integer","description":"Expires in seconds. Field in the JSON request body.\n\n**Details:** Type `integer`."},"features":{"type":"array","items":{"type":"object","description":"Features. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Features. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"refused":{"type":"array","items":{"type":"object","description":"Refused. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Refused. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"422":{"description":"The file does not parse, exceeds a limit, or no file was sent"}}}},"/v3/client/planning-area-sets/import/commit":{"post":{"tags":["Planning Areas"],"operationId":"planningAreaSetImportCommit","summary":"Commit a previewed import into a new or existing planning area set","description":"Same contract as the exclusion zone set import commit, for planning areas.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["preview_id"],"properties":{"preview_id":{"type":"string","description":"**Required.**\n\nPreview id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"target":{"type":"string","enum":["new","append","replace"],"default":"new","description":"Allowed values: `new` · `append` · `replace`.\n\n**Details:** Type `string` · Default: `new`."},"set_id":{"type":"integer","description":"Set id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"feature_indexes":{"type":"array","items":{"type":"integer","description":"Feature indexes. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Feature indexes. Field in the JSON request body.\n\n**Details:** Type `array`, items `integer`."},"names":{"type":"object","description":"Names. Human-readable label.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"The written set","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"set_id":{"type":"integer","description":"Set id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"set_name":{"type":"string","description":"Set name. Human-readable label.\n\n**Details:** Type `string`."},"zones":{"type":"integer","description":"Zones. Field in the JSON request body.\n\n**Details:** Type `integer`."}}}}}},"403":{"description":"Not authorized to change the target set"},"404":{"description":"Target set not found"},"422":{"description":"Preview expired, nothing selected, or the save was refused"}}}},"/v3/client/territories/{id}/export":{"get":{"tags":["Territories"],"operationId":"territoryExport","summary":"Export a territory as a GeoJSON or KML file","description":"A drawn territory (type 1) exports its boundary polygon, exterior ring counter-clockwise per RFC 7946; the stored legacy shape is untouched. A postcode-defined territory exports its properties with no polygon (boundary data is not redistributed).","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"format","required":false,"schema":{"type":"string","enum":["geojson","kml"],"default":"geojson","description":"Allowed values: `geojson` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."},"description":"Allowed values: `geojson` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."}],"responses":{"200":{"description":"The file, as an attachment","content":{"application/geo+json":{"schema":{"type":"object","description":"An RFC 7946 FeatureCollection with one Feature"}},"application/vnd.google-earth.kml+xml":{"schema":{"type":"string","description":"A KML 2.2 Document with one Placemark"}}}},"404":{"description":"Territory not found in this business"},"422":{"description":"Unsupported format, or the territory has no drawn boundary"}}}},"/v3/client/territories/import/preview":{"post":{"tags":["Territories"],"operationId":"territoryImportPreview","summary":"Preview a GeoJSON / KML / KMZ upload for import as a territory boundary","description":"Same two-step contract as the zone-set import, with the one-shape rule: a territory holds exactly one outer ring, so MultiPolygon parts are refused (one_shape_required) and holes are refused by name. Nothing is written.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"**Required.**\n\nFile. Field in the JSON request body.\n\n**Details:** Type `string`, format `binary`."}}}}}},"responses":{"200":{"description":"The preview","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"preview_id":{"type":"string","description":"Preview id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"expires_in_seconds":{"type":"integer","description":"Expires in seconds. Field in the JSON request body.\n\n**Details:** Type `integer`."},"features":{"type":"array","items":{"type":"object","description":"Features. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Features. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"refused":{"type":"array","items":{"type":"object","description":"Refused. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Refused. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"422":{"description":"The file does not parse, exceeds a limit, or no file was sent"}}}},"/v3/client/territories/import/commit":{"post":{"tags":["Territories"],"operationId":"territoryImportCommit","summary":"Commit a previewed boundary as a new territory or onto an existing one","description":"Target new creates a drawn territory (the centre is computed exactly as the territory form computes it); target replace rewrites an existing territory's boundary in the legacy stored shape. Replacing a postcode-defined territory is refused unless convert is true — a round trip must never silently turn a postcode territory into a polygon one.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["preview_id"],"properties":{"preview_id":{"type":"string","description":"**Required.**\n\nPreview id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"target":{"type":"string","enum":["new","replace"],"default":"new","description":"Allowed values: `new` · `replace`.\n\n**Details:** Type `string` · Default: `new`."},"territory_id":{"type":"integer","description":"The replace target\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"The name of a new territory\n\n**Details:** Type `string`."},"feature_index":{"type":"integer","description":"Which preview feature (one shape each); the sole one when absent\n\n**Details:** Type `integer`."},"convert":{"type":"boolean","description":"Explicit consent to turn a postcode-defined territory into a drawn one\n\n**Details:** Type `boolean`."}}}}}},"responses":{"200":{"description":"The written territory","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Target territory not found"},"422":{"description":"Preview expired, several shapes without a selection, or conversion not consented"}}}},"/v3/client/regions/{id}/export":{"get":{"tags":["Regions"],"operationId":"regionExport","summary":"Export a region as a GeoJSON or KML file","description":"A drawn region exports its boundary polygon (counter-clockwise); a postcode-defined region exports its postcode list with no polygon — boundary data is not redistributed. The region is reached through its territory's business.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"format","required":false,"schema":{"type":"string","enum":["geojson","kml"],"default":"geojson","description":"Allowed values: `geojson` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."},"description":"Allowed values: `geojson` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."}],"responses":{"200":{"description":"The file, as an attachment","content":{"application/geo+json":{"schema":{"type":"object","description":"An RFC 7946 FeatureCollection with one Feature"}},"application/vnd.google-earth.kml+xml":{"schema":{"type":"string","description":"A KML 2.2 Document with one Placemark"}}}},"404":{"description":"Region not found in this business"},"422":{"description":"Unsupported format"}}}},"/v3/client/regions/import/preview":{"post":{"tags":["Regions"],"operationId":"regionImportPreview","summary":"Preview a GeoJSON / KML / KMZ upload for import as a region boundary","description":"Same contract as the territory import preview, with the same one-shape rule. Nothing is written.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"**Required.**\n\nFile. Field in the JSON request body.\n\n**Details:** Type `string`, format `binary`."}}}}}},"responses":{"200":{"description":"The preview","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"preview_id":{"type":"string","description":"Preview id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"features":{"type":"array","items":{"type":"object","description":"Features. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Features. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"refused":{"type":"array","items":{"type":"object","description":"Refused. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Refused. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"422":{"description":"The file does not parse, exceeds a limit, or no file was sent"}}}},"/v3/client/regions/import/commit":{"post":{"tags":["Regions"],"operationId":"regionImportCommit","summary":"Replace an existing drawn region's boundary from a preview","description":"Region import is replace-only: creating a region needs the full region form (group, costs, priority), which an uploaded polygon cannot carry. A postcode-defined region is never converted — its postcode groups drive routing.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["preview_id","region_id"],"properties":{"preview_id":{"type":"string","description":"**Required.**\n\nPreview id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"target":{"type":"string","enum":["replace"],"default":"replace","description":"Allowed values: `replace`.\n\n**Details:** Type `string` · Default: `replace`."},"region_id":{"type":"integer","description":"**Required.**\n\nRegion id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"feature_index":{"type":"integer","description":"Feature index. Field in the JSON request body.\n\n**Details:** Type `integer`."}}}}}},"responses":{"200":{"description":"The written region","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"region_id":{"type":"integer","description":"Region id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Target region not found"},"422":{"description":"Preview expired, not a drawn region, or target new was asked"}}}},"/v3/client/routes/{routeId}/export":{"get":{"tags":["Routes"],"operationId":"routeGeoExport","summary":"Export a route as a GeoJSON, GPX or KML file","description":"The planned line (the engine's precision-5 polyline, decoded server-side exactly as the browser decodes it), the stops in stop order, and — with include=actual_track — the driven GPS track ordered by recorded time. Contractors reach only routes and drivers their scope allows; recipient names appear only for internal staff that add include=recipients, never by default. In GPX the stop sequence is a rte and the lines are trks.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"routeId","required":true,"schema":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},"description":"Route id (`routes.id`).\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"format","required":false,"schema":{"type":"string","enum":["geojson","gpx","kml"],"default":"geojson","description":"Allowed values: `geojson` · `gpx` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."},"description":"Allowed values: `geojson` · `gpx` · `kml`.\n\n**Details:** Optional · Type `string` · Default: `geojson`."},{"in":"query","name":"driver_detail_id","required":false,"schema":{"type":"integer","description":"Export one seat only\n\n**Details:** Optional · Type `integer`."},"description":"Export one seat only\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"include","required":false,"schema":{"type":"string","description":"Comma list: actual_track, recipients (internal staff only)\n\n**Details:** Optional · Type `string`."},"description":"Comma list: actual_track, recipients (internal staff only)\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"The file, as an attachment","content":{"application/geo+json":{"schema":{"type":"object","description":"A FeatureCollection: stop Points, the planned LineString (kind planned_line) and optionally the actual track (kind actual_track)"}},"application/gpx+xml":{"schema":{"type":"string"}},"application/vnd.google-earth.kml+xml":{"schema":{"type":"string"}}}},"404":{"description":"Route not found, or not visible to this account"},"422":{"description":"Unsupported format"}}}},"/calendar-feeds/{token}.ics":{"get":{"tags":["Calendar Feeds"],"operationId":"calendarFeedFetch","summary":"Fetch an iCalendar subscription","description":"The anonymous fetch calendar clients (Google, Apple, Outlook) poll. The token in the URL is the whole credential; it is stored hashed and can be paused, rotated or revoked at any time. A paused, revoked or unknown token answers the SAME empty VCALENDAR with 200 — a probe never learns a token once worked. The body is evaluated as the feed's owner at fetch time: whatever that user may see NOW, nothing more. Instants are UTC (no TZID, no VTIMEZONE), all-day items are DATE values, recurring patterns are pre-expanded over the feed's window. Honours If-None-Match with 304; rate-limited to 60 fetches per hour per token.","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string","description":"The feed token from the create or rotate answer\n\nBearer or one-time token for this flow.\n\n**Details:** Required · Type `string`."},"description":"The feed token from the create or rotate answer\n\nBearer or one-time token for this flow.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"The calendar","content":{"text/calendar":{"schema":{"type":"string","description":"An RFC 5545 VCALENDAR; empty (no VEVENTs) when the token is paused, revoked or unknown"}}}},"304":{"description":"Not modified (If-None-Match matched the ETag)"},"429":{"description":"Rate limited; Retry-After says when to try again"}}}},"/holiday-templates/{id}.ics":{"get":{"tags":["Calendar Feeds"],"operationId":"holidayTemplateCalendarFetch","summary":"Fetch a built-in holiday template as a public calendar","description":"A public, token-less iCalendar of one built-in (published) holiday template — no authentication, no module switch. All events are all-day DATE closures over a fixed window from 7 days back to 366 days ahead. An unknown or unpublished template id answers the SAME empty VCALENDAR with 200. Honours If-None-Match with 304; rate-limited to 120 fetches per hour per template.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"The published holiday template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"The published holiday template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The calendar","content":{"text/calendar":{"schema":{"type":"string","description":"An RFC 5545 VCALENDAR; empty (no VEVENTs) when the template id is unknown or unpublished"}}}},"304":{"description":"Not modified (If-None-Match matched the ETag)"},"429":{"description":"Rate limited; Retry-After says when to try again"}}}},"/v1/calendar-feeds":{"get":{"tags":["Calendar Feeds"],"operationId":"calendarFeedsList","summary":"List the caller's calendar feeds","description":"Token hints (last four characters) only — a full token leaves the system exactly once, on create or rotate. Requires the calendar-feeds module, which the platform administrator enables per business (default off).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The caller's feeds","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"feeds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"kind":{"type":"string","description":"Kind. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"subject_type":{"type":["string","null"],"description":"Subject type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"subject_id":{"type":["integer","null"],"description":"Subject id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"token_hint":{"type":"string","description":"Token hint. Secret credential — never logged or returned by the API.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"window_days":{"type":"integer","description":"Window days. Field in the JSON request body.\n\n**Details:** Type `integer`."},"last_fetched_at":{"type":["string","null"],"description":"Last fetched at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"fetch_count":{"type":"integer","description":"Fetch count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}}},"description":"Feeds. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `array`, items `object`."}}}}}},"403":{"description":"Calendar feeds are not enabled for this business"}}},"post":{"tags":["Calendar Feeds"],"operationId":"calendarFeedCreate","summary":"Create a calendar feed","description":"Mints a subscription URL. The answer carries the URL exactly once — only its hash and last four characters are stored, so it cannot be shown again (rotate to get a new one). Kinds and default windows: route_days 90 days, fleet_shifts 28, planning_schedule 90, reservations 90, operating_hours 90, holidays 366; per-feed window_days up to 366. Subjects: planning_schedule requires subject_id (the planning schedule); reservations takes subject_type merchant_store + subject_id for one venue, or no subject for every store the owner may manage; the others take no subject.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["route_days","fleet_shifts","planning_schedule","reservations","operating_hours","holidays"],"description":"**Required.**\n\nAllowed values: `route_days` · `fleet_shifts` · `planning_schedule` · `reservations` · `operating_hours` · `holidays`.\n\n**Details:** Type `string`."},"subject_type":{"type":["string","null"],"description":"Subject type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `fleet`.","examples":["fleet"]},"subject_id":{"type":["integer","null"],"description":"Subject id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"options":{"type":"object","properties":{"window_days":{"type":"integer","maximum":366,"description":"Window days. Field in the JSON request body.\n\n**Details:** Type `integer` · max `366`."}},"description":"Options. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"responses":{"200":{"description":"The feed, and its URL — shown exactly once","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"feed":{"type":"object","description":"Feed. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"url":{"type":"string","description":"Copy it now; it is never shown again\n\n**Details:** Type `string`."}}}}}},"403":{"description":"Calendar feeds are not enabled for this business"},"422":{"description":"Unsupported kind"}}}},"/v1/calendar-feeds/{id}/rotate":{"post":{"tags":["Calendar Feeds"],"operationId":"calendarFeedRotate","summary":"Rotate a feed's token","description":"Mints a new token and kills the old one immediately. The answer carries the new URL exactly once.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The feed and its new URL","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"feed":{"type":"object","description":"Feed. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"url":{"type":"string","description":"Url. Absolute or relative URL.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Feed not found"}}}},"/v1/calendar-feeds/{id}/pause":{"post":{"tags":["Calendar Feeds"],"operationId":"calendarFeedPause","summary":"Pause a feed","description":"A paused feed answers the empty calendar until resumed. The token stays valid.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The feed","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"feed":{"type":"object","description":"Feed. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."}}}}}},"404":{"description":"Feed not found"}}}},"/v1/calendar-feeds/{id}/resume":{"post":{"tags":["Calendar Feeds"],"operationId":"calendarFeedResume","summary":"Resume a paused feed","description":"The feed answers its events again on the next fetch.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The feed","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"feed":{"type":"object","description":"Feed. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."}}}}}},"404":{"description":"Feed not found"}}}},"/v1/calendar-feeds/{id}":{"delete":{"tags":["Calendar Feeds"],"operationId":"calendarFeedRevoke","summary":"Revoke a feed","description":"The token dies now; the row stays for the audit. Revocation is final — create a new feed to subscribe again.","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer","description":"Resource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Resource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}}}}},"404":{"description":"Feed not found"}}}},"/v1/holiday-calendars/import/preview":{"post":{"tags":["Calendar Feeds"],"operationId":"holidayCalendarImportPreview","summary":"Preview an .ics holiday import","description":"Parses an uploaded iCalendar file (multipart `file`, or `content_base64` + `filename` in JSON; 2 MB cap) and answers the holiday rules it maps to. Each ALL-DAY event becomes a rule: FREQ=YEARLY with BYMONTH+BYMONTHDAY maps to a fixed-date rule, with BYMONTH+BYDAY=nXX to an nth-weekday rule; a non-recurring event becomes exact dates (one per day of its span, 31-day cap); any other yearly pattern is expanded as exact dates for the next 3 years; timed events and non-yearly recurrences are refused with a reason. Nothing is written — the preview lives in the cache for 30 minutes under the answered preview_id, keyed to the uploader. Allowed for client admins and reservation-enabled merchants.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"**Required.**\n\nThe .ics file\n\n**Details:** Type `string`, format `binary`."}}}},"application/json":{"schema":{"type":"object","required":["content_base64"],"properties":{"content_base64":{"type":"string","description":"**Required.**\n\nThe .ics content, base64-encoded\n\n**Details:** Type `string`."},"filename":{"type":"string","description":"Names the calendar when the file carries no X-WR-CALNAME\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"The preview","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"preview_id":{"type":"string","description":"Pass to commit within 30 minutes\n\n**Details:** Type `string`."},"calendar":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"timezone":{"type":"string","description":"X-WR-TIMEZONE when a valid IANA zone, else the business timezone\n\n**Details:** Type `string`."}},"description":"Calendar. Field in the JSON request body.\n\n**Details:** Type `object`."},"rules":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"rule_type":{"type":"string","enum":["fixed_date","nth_weekday","exact_date"],"description":"Allowed values: `fixed_date` · `nth_weekday` · `exact_date`.\n\n**Details:** Type `string`."},"exact_date":{"type":["string","null"],"description":"Exact date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string` · Nullable."},"month":{"type":["integer","null"],"description":"Month. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"day_of_month":{"type":["integer","null"],"description":"Day of month. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"weekday":{"type":["integer","null"],"description":"Weekday. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"ordinal":{"type":["integer","null"],"description":"Ordinal. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."}}},"description":"Rules. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"refused":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string","description":"Summary. Field in the JSON request body.\n\n**Details:** Type `string`."},"reason":{"type":"string","enum":["timed_event","unsupported_recurrence","span_too_long"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\nAllowed values: `timed_event` · `unsupported_recurrence` · `span_too_long`.\n\n**Details:** Type `string`."}}},"description":"Refused. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"counts":{"type":"object","properties":{"events":{"type":"integer","description":"Events. Field in the JSON request body.\n\n**Details:** Type `integer`."},"rules":{"type":"integer","description":"Rules. Field in the JSON request body.\n\n**Details:** Type `integer`."},"refused":{"type":"integer","description":"Refused. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Counts. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object`."},"expires_in":{"type":"integer","description":"Expires in. Field in the JSON request body.\n\n**Details:** Type `integer`."}}}}}},"403":{"description":"The caller may not manage holiday calendars"},"422":{"description":"Missing file, oversized file, or not an iCalendar"}}}},"/v1/holiday-calendars/import/commit":{"post":{"tags":["Calendar Feeds"],"operationId":"holidayCalendarImportCommit","summary":"Commit an .ics import as a draft holiday calendar","description":"Turns a preview into a new holiday calendar with status draft — it affects nothing until reviewed and published. The preview must belong to the caller and be under 30 minutes old; an expired or foreign preview_id answers 404. The calendar is created through the holiday calendar manager's normal path, including its audit row.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["preview_id"],"properties":{"preview_id":{"type":"string","description":"**Required.**\n\nPreview id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Overrides the calendar name from the preview\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"The draft calendar","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"calendar":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`.\n\n**Example:** `draft`.","examples":["draft"]},"timezone":{"type":"string","description":"Timezone. Field in the JSON request body.\n\n**Details:** Type `string`."},"rules":{"type":"integer","description":"Rules. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Calendar. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"The caller may not manage holiday calendars"},"404":{"description":"Unknown, expired or foreign preview_id"},"422":{"description":"The preview mapped no rules"}}}},"/v1/client/recurring-pickups/schedules":{"get":{"tags":["Client"],"summary":"List recurring pickup schedules","description":"Every recurring pickup schedule of the account with its skips and extras and its next due date. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) see only the templates they run (their contractor pool, or a driver of theirs) and the schedules and runs riding with them. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientListRecurringPickupSchedules","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"Only schedules in this status: active, paused or ended\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},"description":"Only schedules in this status: active, paused or ended\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."}],"responses":{"200":{"description":"Schedules","content":{"application/json":{"example":{"success":true,"data":[{"id":31,"status":"active","customer_name":"Northside Bakery","company_name":"Northside Bakery Ltd","contact_name":"Ana","telephone":"+1 604 555 0101","email":"ana@example.com","customer_user_id":null,"addressbook_id":null,"address_1":"120 Main St","address_2":null,"city":"Vancouver","province":"BC","postcode":"V6B 1A1","country":"CA","lat":49.2827,"lng":-123.1207,"recurrence_type":"weekly","weekdays":[1,3,5],"interval_days":null,"month_days":[],"starts_on":"2026-09-15","ends_on":null,"window_start":"09:00","window_end":"11:00","service_minutes":10,"expected_packages":3,"expected_weight":null,"instructions":"Ring the back door bell","notes":null,"next_due":"2026-09-16","last_generated_for":null,"created_at":"2026-09-14 10:00:00","updated_at":"2026-09-14 10:00:00","exceptions":[{"id":5,"pickup_schedule_id":31,"service_date":"2026-09-18","type":"skip","window_start":null,"window_end":null,"note":"Closed for inventory"}],"notify_reminder":0,"reminder_timing":"evening_before","notify_completion":0,"reminder_sent_for":null,"customer_can_skip":null,"customer_can_change_window":null,"customer_can_request_extra":null,"customer_cutoff_hours":null,"customer_cutoff_basis":null,"self_service_token_rotated_at":null}]}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}},"post":{"tags":["Client"],"summary":"Create a recurring pickup schedule","description":"A customer collected at one location on a recurrence; the address is geocoded when lat/lng are left empty. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientCreateRecurringPickupSchedule","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_name","address_1","city","recurrence_type","starts_on"],"properties":{"customer_name":{"type":"string","maxLength":191,"description":"**Required.**\n\nCustomer name. Human-readable label.\n\n**Details:** Type `string` · maxLength `191`."},"company_name":{"type":["string","null"],"description":"Contact company name at the stop.\n\n**Details:** Type `string` · Nullable."},"contact_name":{"type":["string","null"],"description":"Contact name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"telephone":{"type":["string","null"],"description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string` · Nullable."},"email":{"type":["string","null"],"format":"email","description":"Account email address.\n\n**Details:** Type `string`, format `email` · Nullable."},"customer_user_id":{"type":["integer","null"],"description":"A customer account of this business\n\n**Details:** Type `integer` · Nullable."},"addressbook_id":{"type":["integer","null"],"description":"Fills the address fields left empty\n\n**Details:** Type `integer` · Nullable."},"address_1":{"type":"string","description":"**Required.**\n\nPrimary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":["string","null"],"description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string` · Nullable."},"city":{"type":"string","description":"**Required.**\n\nCity / locality.\n\n**Details:** Type `string`."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"postcode":{"type":["string","null"],"description":"Postal / ZIP code.\n\n**Details:** Type `string` · Nullable."},"country":{"type":["string","null"],"description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string` · Nullable."},"lat":{"type":["number","null"],"description":"Geocoded from the address when empty\n\n**Details:** Type `number` · Nullable."},"lng":{"type":["number","null"],"description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"recurrence_type":{"type":"string","enum":["daily","weekly","every_n_days","monthly"],"description":"**Required.**\n\nAllowed values: `daily` · `weekly` · `every_n_days` · `monthly`.\n\n**Details:** Type `string`."},"weekdays":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7,"description":"Weekdays. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer` · min `1` · max `7`."},"description":"ISO weekdays, weekly only\n\n**Details:** Type `array`, items `integer`."},"interval_days":{"type":"integer","minimum":1,"maximum":365,"description":"every_n_days only\n\n**Details:** Type `integer` · min `1` · max `365`."},"month_days":{"type":"array","items":{"type":"integer","minimum":1,"maximum":31,"description":"Month days. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer` · min `1` · max `31`."},"description":"monthly only; a day the month lacks falls on its last day\n\n**Details:** Type `array`, items `integer`."},"starts_on":{"type":"string","format":"date","description":"**Required.**\n\nStarts on. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date`."},"ends_on":{"type":["string","null"],"format":"date","description":"Ends on. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date` · Nullable."},"window_start":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Window start. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"window_end":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Window end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"service_minutes":{"type":["integer","null"],"description":"Service minutes. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"expected_packages":{"type":["integer","null"],"description":"Expected packages. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"expected_weight":{"type":["number","null"],"description":"Expected weight. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · Nullable."},"instructions":{"type":["string","null"],"description":"Instructions. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"string","enum":["active","paused","ended"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `paused` · `ended`.\n\n**Details:** Type `string`."},"notify_reminder":{"type":"integer","enum":[0,1],"description":"Send a pickup reminder to the schedule's phone / email (phase 2). Nothing is sent when both are empty. Default 0.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"reminder_timing":{"type":"string","enum":["evening_before","morning_of"],"description":"When the reminder goes out: with the evening generation (default) or with the morning check.\n\nAllowed values: `evening_before` · `morning_of`.\n\n**Details:** Type `string`."},"notify_completion":{"type":"integer","enum":[0,1],"description":"Send a completion notice when the pickup is done. Default 0.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_skip":{"type":["integer","null"],"enum":[0,1,null],"description":"Customer self-service: the customer may skip a date (1 / 0); null follows the template's default\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_change_window":{"type":["integer","null"],"enum":[0,1,null],"description":"Customer self-service: the customer may change the window of a date (1 / 0); null follows the template's default\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_request_extra":{"type":["integer","null"],"enum":[0,1,null],"description":"Customer self-service: the customer may request an extra pickup (1 / 0); null follows the template's default\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_cutoff_hours":{"type":["integer","null"],"minimum":0,"maximum":720,"description":"Changes close this many hours before the cut-off basis; null follows the template\n\n**Details:** Type `integer` · Nullable · min `0` · max `720`."},"customer_cutoff_basis":{"type":["string","null"],"enum":["generation","window_start",null],"description":"generation: before the day's evening generation; window_start: before the window start; null follows the template\n\nAllowed values: `generation` · `window_start`.\n\n**Details:** Type `string` · Nullable."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"success":true,"data":{"id":31,"status":"active","customer_name":"Northside Bakery","company_name":"Northside Bakery Ltd","contact_name":"Ana","telephone":"+1 604 555 0101","email":"ana@example.com","customer_user_id":null,"addressbook_id":null,"address_1":"120 Main St","address_2":null,"city":"Vancouver","province":"BC","postcode":"V6B 1A1","country":"CA","lat":49.2827,"lng":-123.1207,"recurrence_type":"weekly","weekdays":[1,3,5],"interval_days":null,"month_days":[],"starts_on":"2026-09-15","ends_on":null,"window_start":"09:00","window_end":"11:00","service_minutes":10,"expected_packages":3,"expected_weight":null,"instructions":"Ring the back door bell","notes":null,"next_due":"2026-09-16","last_generated_for":null,"created_at":"2026-09-14 10:00:00","updated_at":"2026-09-14 10:00:00","notify_reminder":0,"reminder_timing":"evening_before","notify_completion":0,"reminder_sent_for":null,"customer_can_skip":null,"customer_can_change_window":null,"customer_can_request_extra":null,"customer_cutoff_hours":null,"customer_cutoff_basis":null,"self_service_token_rotated_at":null}}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"Choose at least one weekday.","errors":{"weekdays":["Choose at least one weekday."]}}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/schedules/{id}":{"get":{"tags":["Client"],"summary":"Get a recurring pickup schedule","description":"One schedule with its skips and extras. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) see only the templates they run (their contractor pool, or a driver of theirs) and the schedules and runs riding with them. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientGetRecurringPickupSchedule","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Schedule","content":{"application/json":{"example":{"success":true,"data":{"id":31,"status":"active","customer_name":"Northside Bakery","company_name":"Northside Bakery Ltd","contact_name":"Ana","telephone":"+1 604 555 0101","email":"ana@example.com","customer_user_id":null,"addressbook_id":null,"address_1":"120 Main St","address_2":null,"city":"Vancouver","province":"BC","postcode":"V6B 1A1","country":"CA","lat":49.2827,"lng":-123.1207,"recurrence_type":"weekly","weekdays":[1,3,5],"interval_days":null,"month_days":[],"starts_on":"2026-09-15","ends_on":null,"window_start":"09:00","window_end":"11:00","service_minutes":10,"expected_packages":3,"expected_weight":null,"instructions":"Ring the back door bell","notes":null,"next_due":"2026-09-16","last_generated_for":null,"created_at":"2026-09-14 10:00:00","updated_at":"2026-09-14 10:00:00","exceptions":[{"id":5,"pickup_schedule_id":31,"service_date":"2026-09-18","type":"skip","window_start":null,"window_end":null,"note":"Closed for inventory"}],"notify_reminder":0,"reminder_timing":"evening_before","notify_completion":0,"reminder_sent_for":null,"customer_can_skip":null,"customer_can_change_window":null,"customer_can_request_extra":null,"customer_cutoff_hours":null,"customer_cutoff_basis":null,"self_service_token_rotated_at":null}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}},"put":{"tags":["Client"],"summary":"Update a recurring pickup schedule","description":"Fields left out keep their value. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientUpdateRecurringPickupSchedule","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_name":{"type":"string","maxLength":191,"description":"Customer name. Human-readable label.\n\n**Details:** Type `string` · maxLength `191`."},"company_name":{"type":["string","null"],"description":"Contact company name at the stop.\n\n**Details:** Type `string` · Nullable."},"contact_name":{"type":["string","null"],"description":"Contact name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"telephone":{"type":["string","null"],"description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string` · Nullable."},"email":{"type":["string","null"],"format":"email","description":"Account email address.\n\n**Details:** Type `string`, format `email` · Nullable."},"customer_user_id":{"type":["integer","null"],"description":"A customer account of this business\n\n**Details:** Type `integer` · Nullable."},"addressbook_id":{"type":["integer","null"],"description":"Fills the address fields left empty\n\n**Details:** Type `integer` · Nullable."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":["string","null"],"description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string` · Nullable."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"postcode":{"type":["string","null"],"description":"Postal / ZIP code.\n\n**Details:** Type `string` · Nullable."},"country":{"type":["string","null"],"description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string` · Nullable."},"lat":{"type":["number","null"],"description":"Geocoded from the address when empty\n\n**Details:** Type `number` · Nullable."},"lng":{"type":["number","null"],"description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"recurrence_type":{"type":"string","enum":["daily","weekly","every_n_days","monthly"],"description":"Allowed values: `daily` · `weekly` · `every_n_days` · `monthly`.\n\n**Details:** Type `string`."},"weekdays":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7,"description":"Weekdays. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer` · min `1` · max `7`."},"description":"ISO weekdays, weekly only\n\n**Details:** Type `array`, items `integer`."},"interval_days":{"type":"integer","minimum":1,"maximum":365,"description":"every_n_days only\n\n**Details:** Type `integer` · min `1` · max `365`."},"month_days":{"type":"array","items":{"type":"integer","minimum":1,"maximum":31,"description":"Month days. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer` · min `1` · max `31`."},"description":"monthly only; a day the month lacks falls on its last day\n\n**Details:** Type `array`, items `integer`."},"starts_on":{"type":"string","format":"date","description":"Starts on. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date`."},"ends_on":{"type":["string","null"],"format":"date","description":"Ends on. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date` · Nullable."},"window_start":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Window start. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"window_end":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Window end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"service_minutes":{"type":["integer","null"],"description":"Service minutes. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"expected_packages":{"type":["integer","null"],"description":"Expected packages. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"expected_weight":{"type":["number","null"],"description":"Expected weight. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number` · Nullable."},"instructions":{"type":["string","null"],"description":"Instructions. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"notes":{"type":["string","null"],"description":"Free-text notes.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"string","enum":["active","paused","ended"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `paused` · `ended`.\n\n**Details:** Type `string`."},"notify_reminder":{"type":"integer","enum":[0,1],"description":"Send a pickup reminder to the schedule's phone / email (phase 2). Nothing is sent when both are empty. Default 0.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"reminder_timing":{"type":"string","enum":["evening_before","morning_of"],"description":"When the reminder goes out: with the evening generation (default) or with the morning check.\n\nAllowed values: `evening_before` · `morning_of`.\n\n**Details:** Type `string`."},"notify_completion":{"type":"integer","enum":[0,1],"description":"Send a completion notice when the pickup is done. Default 0.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_skip":{"type":["integer","null"],"enum":[0,1,null],"description":"Customer self-service: the customer may skip a date (1 / 0); null follows the template's default\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_change_window":{"type":["integer","null"],"enum":[0,1,null],"description":"Customer self-service: the customer may change the window of a date (1 / 0); null follows the template's default\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_request_extra":{"type":["integer","null"],"enum":[0,1,null],"description":"Customer self-service: the customer may request an extra pickup (1 / 0); null follows the template's default\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_cutoff_hours":{"type":["integer","null"],"minimum":0,"maximum":720,"description":"Changes close this many hours before the cut-off basis; null follows the template\n\n**Details:** Type `integer` · Nullable · min `0` · max `720`."},"customer_cutoff_basis":{"type":["string","null"],"enum":["generation","window_start",null],"description":"generation: before the day's evening generation; window_start: before the window start; null follows the template\n\nAllowed values: `generation` · `window_start`.\n\n**Details:** Type `string` · Nullable."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"example":{"success":true,"data":{"id":31,"status":"active","customer_name":"Northside Bakery","company_name":"Northside Bakery Ltd","contact_name":"Ana","telephone":"+1 604 555 0101","email":"ana@example.com","customer_user_id":null,"addressbook_id":null,"address_1":"120 Main St","address_2":null,"city":"Vancouver","province":"BC","postcode":"V6B 1A1","country":"CA","lat":49.2827,"lng":-123.1207,"recurrence_type":"weekly","weekdays":[1,3,5],"interval_days":null,"month_days":[],"starts_on":"2026-09-15","ends_on":null,"window_start":"09:00","window_end":"11:00","service_minutes":10,"expected_packages":3,"expected_weight":null,"instructions":"Ring the back door bell","notes":null,"next_due":"2026-09-16","last_generated_for":null,"created_at":"2026-09-14 10:00:00","updated_at":"2026-09-14 10:00:00","notify_reminder":0,"reminder_timing":"evening_before","notify_completion":0,"reminder_sent_for":null,"customer_can_skip":null,"customer_can_change_window":null,"customer_can_request_extra":null,"customer_cutoff_hours":null,"customer_cutoff_basis":null,"self_service_token_rotated_at":null}}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"Choose at least one weekday.","errors":{"weekdays":["Choose at least one weekday."]}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}},"delete":{"tags":["Client"],"summary":"Delete a recurring pickup schedule","description":"Orders already generated are kept; the schedule leaves every template. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientDeleteRecurringPickupSchedule","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"example":{"success":true,"data":{"id":31,"deleted":true}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/schedules/{id}/exceptions":{"post":{"tags":["Client"],"summary":"Skip a date or add an extra date","description":"A skip removes the due pickup on that date; an extra adds one on a date the recurrence does not cover, optionally with its own window. One exception per schedule and date, a new one replaces the old. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientAddRecurringPickupException","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","service_date"],"properties":{"type":{"type":"string","enum":["skip","extra","window"],"description":"**Required.**\n\nwindow: the date stays due with another window (window_start / window_end), as customer self-service records it.\n\nAllowed values: `skip` · `extra` · `window`.\n\n**Details:** Type `string`."},"service_date":{"type":"string","format":"date","description":"**Required.**\n\nService date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date`."},"window_start":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Window start. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"window_end":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Window end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"note":{"type":["string","null"],"maxLength":255,"description":"Note. Free-text note.\n\n**Details:** Type `string` · Nullable · maxLength `255`."}}}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"example":{"success":true,"data":{"id":5,"pickup_schedule_id":31,"service_date":"2026-09-18","type":"skip","window_start":null,"window_end":null,"note":"Closed for inventory"}}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"Choose at least one weekday.","errors":{"weekdays":["Choose at least one weekday."]}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/schedules/{id}/exceptions/{exceptionId}":{"delete":{"tags":["Client"],"summary":"Remove a skip or extra date","description":"The recurrence applies again on that date. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientRemoveRecurringPickupException","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},{"name":"exceptionId","in":"path","required":true,"schema":{"type":"integer","description":"Exception id\n\n**Details:** Required · Type `integer`."},"description":"Exception id\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Removed","content":{"application/json":{"example":{"success":true,"data":{"id":5,"deleted":true}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/templates":{"get":{"tags":["Client"],"summary":"List recurring pickup route templates","description":"Every template of the account with its members in template order. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) see only the templates they run (their contractor pool, or a driver of theirs) and the schedules and runs riding with them. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientListRecurringPickupTemplates","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Templates","content":{"application/json":{"example":{"success":true,"data":[{"id":4,"name":"Downtown morning collection","code":"DT-AM","status":1,"sort_order":0,"territory_id":null,"sequence_mode":"fixed","allow_adhoc_pickups":0,"allow_deliveries":1,"driver_id":77,"broker_id":null,"fleet_qty":0,"start_address_id":12,"end_address_id":12,"work_from":"08:00","work_end":"13:00","route_name_prefix":"Pickup-Route-","channel_id":null,"routing_engine":null,"solver_rules":null,"created_at":"2026-09-14 10:00:00","updated_at":"2026-09-14 10:00:00","members":[{"id":9,"pickup_schedule_id":31,"sequence":1,"weekdays":null,"customer_name":"Northside Bakery","address":"120 Main St, Vancouver","schedule_status":"active"}],"day_overrides":[{"id":3,"weekday":3,"service_date":null,"no_service":0,"driver_id":null,"broker_id":null,"fleet_qty":2,"start_address_id":12,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"special_days":[{"id":4,"weekday":null,"service_date":"2026-12-25","no_service":1,"driver_id":null,"broker_id":null,"fleet_qty":null,"start_address_id":null,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"customer_can_skip":0,"customer_can_change_window":0,"customer_can_request_extra":0,"customer_cutoff_hours":0,"customer_cutoff_basis":"generation"}]}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}},"post":{"tags":["Client"],"summary":"Create a recurring pickup route template","description":"A fixed route made of schedules. A schedule may ride with only one template per weekday; a member's weekdays (ISO 1..7, null = every day it is due) restrict when it rides with this one. sequence_mode: fixed (the members in table order), time_window (ordered by the customers' windows), optimise (the engine decides) or mixed (members with a sequence keep it, the others are placed by their window or by the engine). Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientCreateRecurringPickupTemplate","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","sequence_mode"],"properties":{"name":{"type":"string","maxLength":120,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `120`."},"code":{"type":["string","null"],"maxLength":32,"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable · maxLength `32`."},"status":{"type":"integer","enum":[0,1],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable."},"sequence_mode":{"type":"string","enum":["fixed","time_window","optimise","mixed"],"description":"**Required.**\n\nAllowed values: `fixed` · `time_window` · `optimise` · `mixed`.\n\n**Details:** Type `string`."},"allow_adhoc_pickups":{"type":"integer","enum":[0,1],"description":"Whether ad-hoc pickup orders may be added to the daily route\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"allow_deliveries":{"type":"integer","enum":[0,1],"description":"Whether delivery orders may be added to the daily route\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"broker_id":{"type":["integer","null"],"description":"Contractor pool for pending vehicles\n\n**Details:** Type `integer` · Nullable."},"fleet_qty":{"type":"integer","minimum":0,"maximum":50,"description":"Fleet qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · min `0` · max `50`."},"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"work_from":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"work_end":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"route_name_prefix":{"type":["string","null"],"maxLength":64,"description":"Route name prefix. Human-readable label.\n\n**Details:** Type `string` · Nullable · maxLength `64`."},"channel_id":{"type":["integer","null"],"description":"Channel id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"routing_engine":{"type":["integer","null"],"enum":[1,2,3,null],"description":"Allowed values: `1` · `2` · `3`.\n\n**Details:** Type `integer` · Nullable."},"solver_rules":{"type":["object","null"],"description":"Solver rules. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"members":{"type":"array","items":{"type":"object","properties":{"pickup_schedule_id":{"type":"integer","description":"Pickup schedule id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"sequence":{"type":["integer","null"],"description":"Sequence. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"weekdays":{"type":["array","null"],"items":{"type":"integer","description":"Weekdays. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Weekdays. Field in the JSON request body.\n\n**Details:** Type `array`, items `integer` · Nullable."}}},"description":"Members. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"day_overrides":{"type":"array","description":"Per-weekday vehicle overrides (phase 2). One row per ISO weekday (1 = Monday); a null field falls back to the template. Sent = the set is replaced; omitted = kept.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":1,"maximum":7,"description":"Weekday. Field in the JSON request body.\n\n**Details:** Type `integer` · min `1` · max `7`."},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"broker_id":{"type":["integer","null"],"description":"Broker id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"fleet_qty":{"type":["integer","null"],"description":"Fleet qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `08:00`.","examples":["08:00"]},"work_end":{"type":["string","null"],"description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `13:00`.","examples":["13:00"]}}}},"special_days":{"type":"array","description":"Special dates (phase 2): a date outranks its weekday — another vehicle, the two switches for that day (null = template's), or no_service = 1 for no route at all. Sent = the set is replaced; omitted = kept.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"service_date":{"type":"string","format":"date","description":"Service date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date`."},"no_service":{"type":"integer","enum":[0,1],"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"broker_id":{"type":["integer","null"],"description":"Broker id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"fleet_qty":{"type":["integer","null"],"description":"Fleet qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `08:00`.","examples":["08:00"]},"work_end":{"type":["string","null"],"description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `13:00`.","examples":["13:00"]},"allow_adhoc_pickups":{"type":["integer","null"],"enum":[0,1,null],"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"allow_deliveries":{"type":["integer","null"],"enum":[0,1,null],"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]}}}},"customer_can_skip":{"type":"integer","enum":[0,1],"description":"Customer self-service: the customer may skip a date (1 / 0); default 0 for every schedule of the template\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_change_window":{"type":"integer","enum":[0,1],"description":"Customer self-service: the customer may change the window of a date (1 / 0); default 0 for every schedule of the template\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_request_extra":{"type":"integer","enum":[0,1],"description":"Customer self-service: the customer may request an extra pickup (1 / 0); default 0 for every schedule of the template\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_cutoff_hours":{"type":"integer","minimum":0,"maximum":720,"description":"Changes close this many hours before the cut-off basis; default 0\n\n**Details:** Type `integer` · min `0` · max `720`."},"customer_cutoff_basis":{"type":"string","enum":["generation","window_start"],"description":"generation (default) or window_start\n\nAllowed values: `generation` · `window_start`.\n\n**Details:** Type `string`."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"success":true,"data":{"id":4,"name":"Downtown morning collection","code":"DT-AM","status":1,"sort_order":0,"territory_id":null,"sequence_mode":"fixed","allow_adhoc_pickups":0,"allow_deliveries":1,"driver_id":77,"broker_id":null,"fleet_qty":0,"start_address_id":12,"end_address_id":12,"work_from":"08:00","work_end":"13:00","route_name_prefix":"Pickup-Route-","channel_id":null,"routing_engine":null,"solver_rules":null,"created_at":"2026-09-14 10:00:00","updated_at":"2026-09-14 10:00:00","members":[{"id":9,"pickup_schedule_id":31,"sequence":1,"weekdays":null,"customer_name":"Northside Bakery","address":"120 Main St, Vancouver","schedule_status":"active"}],"day_overrides":[{"id":3,"weekday":3,"service_date":null,"no_service":0,"driver_id":null,"broker_id":null,"fleet_qty":2,"start_address_id":12,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"special_days":[{"id":4,"weekday":null,"service_date":"2026-12-25","no_service":1,"driver_id":null,"broker_id":null,"fleet_qty":null,"start_address_id":null,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"customer_can_skip":0,"customer_can_change_window":0,"customer_can_request_extra":0,"customer_cutoff_hours":0,"customer_cutoff_basis":"generation"}}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"Choose at least one weekday.","errors":{"weekdays":["Choose at least one weekday."]}}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/templates/{id}":{"get":{"tags":["Client"],"summary":"Get a recurring pickup route template","description":"One template with its members. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) see only the templates they run (their contractor pool, or a driver of theirs) and the schedules and runs riding with them. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientGetRecurringPickupTemplate","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Template","content":{"application/json":{"example":{"success":true,"data":{"id":4,"name":"Downtown morning collection","code":"DT-AM","status":1,"sort_order":0,"territory_id":null,"sequence_mode":"fixed","allow_adhoc_pickups":0,"allow_deliveries":1,"driver_id":77,"broker_id":null,"fleet_qty":0,"start_address_id":12,"end_address_id":12,"work_from":"08:00","work_end":"13:00","route_name_prefix":"Pickup-Route-","channel_id":null,"routing_engine":null,"solver_rules":null,"created_at":"2026-09-14 10:00:00","updated_at":"2026-09-14 10:00:00","members":[{"id":9,"pickup_schedule_id":31,"sequence":1,"weekdays":null,"customer_name":"Northside Bakery","address":"120 Main St, Vancouver","schedule_status":"active"}],"day_overrides":[{"id":3,"weekday":3,"service_date":null,"no_service":0,"driver_id":null,"broker_id":null,"fleet_qty":2,"start_address_id":12,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"special_days":[{"id":4,"weekday":null,"service_date":"2026-12-25","no_service":1,"driver_id":null,"broker_id":null,"fleet_qty":null,"start_address_id":null,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"customer_can_skip":0,"customer_can_change_window":0,"customer_can_request_extra":0,"customer_cutoff_hours":0,"customer_cutoff_basis":"generation"}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}},"put":{"tags":["Client"],"summary":"Update a recurring pickup route template","description":"Fields left out keep their value; members, when sent, replace the member list. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientUpdateRecurringPickupTemplate","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120,"description":"Human-readable name.\n\n**Details:** Type `string` · maxLength `120`."},"code":{"type":["string","null"],"maxLength":32,"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable · maxLength `32`."},"status":{"type":"integer","enum":[0,1],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."},"territory_id":{"type":["integer","null"],"description":"Territory id.\n\n**Details:** Type `integer` · Nullable."},"sequence_mode":{"type":"string","enum":["fixed","time_window","optimise","mixed"],"description":"Allowed values: `fixed` · `time_window` · `optimise` · `mixed`.\n\n**Details:** Type `string`."},"allow_adhoc_pickups":{"type":"integer","enum":[0,1],"description":"Whether ad-hoc pickup orders may be added to the daily route\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"allow_deliveries":{"type":"integer","enum":[0,1],"description":"Whether delivery orders may be added to the daily route\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"broker_id":{"type":["integer","null"],"description":"Contractor pool for pending vehicles\n\n**Details:** Type `integer` · Nullable."},"fleet_qty":{"type":"integer","minimum":0,"maximum":50,"description":"Fleet qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · min `0` · max `50`."},"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"work_from":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"work_end":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable · pattern `^\\d{2}:\\d{2}$`."},"route_name_prefix":{"type":["string","null"],"maxLength":64,"description":"Route name prefix. Human-readable label.\n\n**Details:** Type `string` · Nullable · maxLength `64`."},"channel_id":{"type":["integer","null"],"description":"Channel id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"routing_engine":{"type":["integer","null"],"enum":[1,2,3,null],"description":"Allowed values: `1` · `2` · `3`.\n\n**Details:** Type `integer` · Nullable."},"solver_rules":{"type":["object","null"],"description":"Solver rules. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"members":{"type":"array","items":{"type":"object","properties":{"pickup_schedule_id":{"type":"integer","description":"Pickup schedule id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"sequence":{"type":["integer","null"],"description":"Sequence. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"weekdays":{"type":["array","null"],"items":{"type":"integer","description":"Weekdays. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Weekdays. Field in the JSON request body.\n\n**Details:** Type `array`, items `integer` · Nullable."}}},"description":"Members. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"day_overrides":{"type":"array","description":"Per-weekday vehicle overrides (phase 2). One row per ISO weekday (1 = Monday); a null field falls back to the template. Sent = the set is replaced; omitted = kept.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":1,"maximum":7,"description":"Weekday. Field in the JSON request body.\n\n**Details:** Type `integer` · min `1` · max `7`."},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"broker_id":{"type":["integer","null"],"description":"Broker id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"fleet_qty":{"type":["integer","null"],"description":"Fleet qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `08:00`.","examples":["08:00"]},"work_end":{"type":["string","null"],"description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `13:00`.","examples":["13:00"]}}}},"special_days":{"type":"array","description":"Special dates (phase 2): a date outranks its weekday — another vehicle, the two switches for that day (null = template's), or no_service = 1 for no route at all. Sent = the set is replaced; omitted = kept.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"service_date":{"type":"string","format":"date","description":"Service date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date`."},"no_service":{"type":"integer","enum":[0,1],"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"broker_id":{"type":["integer","null"],"description":"Broker id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"fleet_qty":{"type":["integer","null"],"description":"Fleet qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `08:00`.","examples":["08:00"]},"work_end":{"type":["string","null"],"description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `13:00`.","examples":["13:00"]},"allow_adhoc_pickups":{"type":["integer","null"],"enum":[0,1,null],"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"allow_deliveries":{"type":["integer","null"],"enum":[0,1,null],"description":"Enum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]}}}},"customer_can_skip":{"type":"integer","enum":[0,1],"description":"Customer self-service: the customer may skip a date (1 / 0); default 0 for every schedule of the template\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_change_window":{"type":"integer","enum":[0,1],"description":"Customer self-service: the customer may change the window of a date (1 / 0); default 0 for every schedule of the template\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_can_request_extra":{"type":"integer","enum":[0,1],"description":"Customer self-service: the customer may request an extra pickup (1 / 0); default 0 for every schedule of the template\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_cutoff_hours":{"type":"integer","minimum":0,"maximum":720,"description":"Changes close this many hours before the cut-off basis; default 0\n\n**Details:** Type `integer` · min `0` · max `720`."},"customer_cutoff_basis":{"type":"string","enum":["generation","window_start"],"description":"generation (default) or window_start\n\nAllowed values: `generation` · `window_start`.\n\n**Details:** Type `string`."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"example":{"success":true,"data":{"id":4,"name":"Downtown morning collection","code":"DT-AM","status":1,"sort_order":0,"territory_id":null,"sequence_mode":"fixed","allow_adhoc_pickups":0,"allow_deliveries":1,"driver_id":77,"broker_id":null,"fleet_qty":0,"start_address_id":12,"end_address_id":12,"work_from":"08:00","work_end":"13:00","route_name_prefix":"Pickup-Route-","channel_id":null,"routing_engine":null,"solver_rules":null,"created_at":"2026-09-14 10:00:00","updated_at":"2026-09-14 10:00:00","members":[{"id":9,"pickup_schedule_id":31,"sequence":1,"weekdays":null,"customer_name":"Northside Bakery","address":"120 Main St, Vancouver","schedule_status":"active"}],"day_overrides":[{"id":3,"weekday":3,"service_date":null,"no_service":0,"driver_id":null,"broker_id":null,"fleet_qty":2,"start_address_id":12,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"special_days":[{"id":4,"weekday":null,"service_date":"2026-12-25","no_service":1,"driver_id":null,"broker_id":null,"fleet_qty":null,"start_address_id":null,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"customer_can_skip":0,"customer_can_change_window":0,"customer_can_request_extra":0,"customer_cutoff_hours":0,"customer_cutoff_basis":"generation"}}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"Choose at least one weekday.","errors":{"weekdays":["Choose at least one weekday."]}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}},"delete":{"tags":["Client"],"summary":"Delete a recurring pickup route template","description":"Routes already generated are kept. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientDeleteRecurringPickupTemplate","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"example":{"success":true,"data":{"id":4,"deleted":true}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/templates/{id}/members":{"put":{"tags":["Client"],"summary":"Replace the members of a template","description":"The whole member list, in sequence order. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientSetRecurringPickupTemplateMembers","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["members"],"properties":{"members":{"type":"array","items":{"type":"object","properties":{"pickup_schedule_id":{"type":"integer","description":"Pickup schedule id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"sequence":{"type":["integer","null"],"description":"Sequence. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"weekdays":{"type":["array","null"],"items":{"type":"integer","description":"Weekdays. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Weekdays. Field in the JSON request body.\n\n**Details:** Type `array`, items `integer` · Nullable."}}},"description":"**Required.**\n\nMembers. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"example":{"success":true,"data":{"id":4,"name":"Downtown morning collection","code":"DT-AM","status":1,"sort_order":0,"territory_id":null,"sequence_mode":"fixed","allow_adhoc_pickups":0,"allow_deliveries":1,"driver_id":77,"broker_id":null,"fleet_qty":0,"start_address_id":12,"end_address_id":12,"work_from":"08:00","work_end":"13:00","route_name_prefix":"Pickup-Route-","channel_id":null,"routing_engine":null,"solver_rules":null,"created_at":"2026-09-14 10:00:00","updated_at":"2026-09-14 10:00:00","members":[{"id":9,"pickup_schedule_id":31,"sequence":1,"weekdays":null,"customer_name":"Northside Bakery","address":"120 Main St, Vancouver","schedule_status":"active"}],"day_overrides":[{"id":3,"weekday":3,"service_date":null,"no_service":0,"driver_id":null,"broker_id":null,"fleet_qty":2,"start_address_id":12,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"special_days":[{"id":4,"weekday":null,"service_date":"2026-12-25","no_service":1,"driver_id":null,"broker_id":null,"fleet_qty":null,"start_address_id":null,"end_address_id":null,"work_from":null,"work_end":null,"allow_adhoc_pickups":null,"allow_deliveries":null}],"customer_can_skip":0,"customer_can_change_window":0,"customer_can_request_extra":0,"customer_cutoff_hours":0,"customer_cutoff_basis":"generation"}}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"Choose at least one weekday.","errors":{"weekdays":["Choose at least one weekday."]}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/templates/{id}/day/{date}":{"get":{"tags":["Client"],"summary":"Preview the day of a recurring pickup template","description":"What the daily board shows for one template and date, before and after generation: every member in the day's order with its state (due, skipped, extra, on the route, picked up), the vehicle the route gets that day and where it comes from (template, weekday override, date override), the two switches, and once generated the route and the stops whose planned arrival is outside the customer window. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) reach the days of the templates they run (their contractor pool, or a driver of theirs) and may crew a day with their own drivers and pool only. Before the module's migrations have run the answer is 409 with error_code schema_not_ready. changes lists the audited changes of the day (source customer, dispatcher or api), newest first.","operationId":"clientRecurringPickupDay","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},{"name":"date","in":"path","required":true,"schema":{"type":"string","format":"date","description":"The service date (Y-m-d)\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Required · Type `string`, format `date`."},"description":"The service date (Y-m-d)\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Required · Type `string`, format `date`."}],"responses":{"200":{"description":"The day","content":{"application/json":{"example":{"success":true,"data":{"template_id":4,"template_name":"Downtown morning collection","sequence_mode":"fixed","service_date":"2026-09-16","no_service":false,"run":{"id":12,"status":"generated","route_id":98765,"error":null},"route":{"id":98765,"name":"Pickup-Route-2026-09-16","status":3,"allow_adhoc_pickups":0,"allow_deliveries":1,"started":false},"switches":{"allow_adhoc_pickups":0,"allow_deliveries":1},"vehicle":{"source":"weekday","driver_id":78,"broker_id":null,"fleet_qty":0,"start_address_id":12,"end_address_id":12,"work_from":"08:00","work_end":"13:00"},"stops":[{"pickup_schedule_id":31,"customer_name":"Northside Bakery","address":"120 Main St, Vancouver","window":"09:00 - 11:00","sequence":1,"position":1,"fixed":true,"due":true,"exception":null,"order_id":555001,"on_route":true,"stop_number":1,"started":false,"order_status":16},{"pickup_schedule_id":32,"customer_name":"Harbour Deli","address":"9 Water St, Vancouver","window":null,"sequence":2,"position":2,"fixed":true,"due":true,"exception":"skip","order_id":null,"on_route":false,"stop_number":null,"started":false,"order_status":null}],"window_violations":[{"order_id":555001,"arrival":"2026-09-16 11:20:00","window_start":"2026-09-16 09:00:00","window_end":"2026-09-16 11:00:00"}],"changes":[{"id":7,"pickup_schedule_id":32,"action":"skip","source":"customer","actor_user_id":null,"actor_label":"Harbour Deli","details":{"note":"Closed for inventory"},"created_at":"2026-09-15 08:12:00"}]}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}},"post":{"tags":["Client"],"summary":"Adjust the day of a recurring pickup template","description":"A generated day stays changeable until it is completed (design §5). Before generation the adjustment is recorded as a per-date override and applied when the route is generated; after generation it is applied to the route and its orders as well, and recorded so a regenerate reproduces it. Stops already picked up are never touched: they are left alone and named in kept. The body is the adjustment's result plus success; a refusal (a started stop, a day that cannot change) answers 409. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) reach the days of the templates they run (their contractor pool, or a driver of theirs) and may crew a day with their own drivers and pool only. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientAdjustRecurringPickupDay","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Template id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},{"name":"date","in":"path","required":true,"schema":{"type":"string","format":"date","description":"The service date (Y-m-d)\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Required · Type `string`, format `date`."},"description":"The service date (Y-m-d)\n\nCalendar date (typically `YYYY-MM-DD` in the business timezone).\n\n**Details:** Required · Type `string`, format `date`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["skip","extra","unexcept","reorder","vehicle","switches","cancel","restore"],"description":"**Required.**\n\nThe adjustment to apply. skip (pickup_schedule_id, note): the schedule is skipped that date and, after generation, its not-started order is cancelled and taken off the route. extra (pickup_schedule_id, window_start, window_end, note): an extra pickup that date; after generation its order is created and inserted through the normal insert path, respecting the sequence mode. unexcept (pickup_schedule_id): removes the date's skip or extra. reorder (sequence: schedule ids in order): the day's order, written to the route's not-started stops after generation. vehicle (driver_id, broker_id, fleet_qty, start_address_id, end_address_id, work_from, work_end): the day's vehicle, re-crewed on an unstarted route. switches (allow_adhoc_pickups, allow_deliveries): the day's two switches, on the route as well. cancel: no service that day — the route is cancelled for drivers who have not started, pending recurring orders are cancelled, the run is marked cancelled; started stops stay and are reported in kept. restore: undoes cancel before generation.\n\nAllowed values: `skip` · `extra` · `unexcept` · `reorder` · `vehicle` · `switches` · `cancel` · `restore`.\n\n**Details:** Type `string`."},"pickup_schedule_id":{"type":"integer","description":"skip / extra / unexcept\n\n**Details:** Type `integer`."},"note":{"type":["string","null"],"maxLength":255,"description":"Note. Free-text note.\n\n**Details:** Type `string` · Nullable · maxLength `255`."},"window_start":{"type":["string","null"],"description":"extra\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `13:00`.","examples":["13:00"]},"window_end":{"type":["string","null"],"description":"extra\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `15:00`.","examples":["15:00"]},"sequence":{"type":"array","items":{"type":"integer","description":"Sequence. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"reorder: schedule ids in the day's order\n\n**Details:** Type `array`, items `integer`."},"driver_id":{"type":["integer","null"],"description":"Driver id.\n\n**Details:** Type `integer` · Nullable."},"broker_id":{"type":["integer","null"],"description":"Broker id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"fleet_qty":{"type":["integer","null"],"description":"Fleet qty. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"work_end":{"type":["string","null"],"description":"Work end. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"allow_adhoc_pickups":{"type":["integer","null"],"enum":[0,1,null],"description":"switches\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"allow_deliveries":{"type":["integer","null"],"enum":[0,1,null],"description":"switches\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","x-enumDescriptions":["No / false / off","Yes / true / on"]}}},"example":{"action":"skip","pickup_schedule_id":31,"note":"Customer closed"}}}},"responses":{"200":{"description":"Applied (applied = override before generation, route after it; kept = started stops left as they are)","content":{"application/json":{"example":{"success":true,"action":"skip","ok":true,"applied":"route","message":"The date was skipped and the stop taken off the route.","order_id":555001}}}},"409":{"description":"Refused: a started stop, or a day that cannot change","content":{"application/json":{"example":{"success":false,"action":"skip","ok":false,"message":"This pickup has already started; it is left as it is."}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"pickup_schedule_id is required.","errors":{"pickup_schedule_id":["pickup_schedule_id is required."]}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/runs":{"get":{"tags":["Client"],"summary":"List recurring pickup runs","description":"One run per template and service date: generated (with the route), empty (nothing was due) or failed (with the error). Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) see only the templates they run (their contractor pool, or a driver of theirs) and the schedules and runs riding with them. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientListRecurringPickupRuns","security":[{"bearerAuth":[]}],"parameters":[{"name":"service_date","in":"query","required":false,"schema":{"type":"string","description":"Only runs for this date (Y-m-d)\n\n**Details:** Optional · Type `string`."},"description":"Only runs for this date (Y-m-d)\n\n**Details:** Optional · Type `string`."},{"name":"template_id","in":"query","required":false,"schema":{"type":"integer","description":"Only runs of this template\n\n**Details:** Optional · Type `integer`."},"description":"Only runs of this template\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Runs","content":{"application/json":{"example":{"success":true,"data":[{"id":12,"pickup_route_template_id":4,"service_date":"2026-09-16","route_id":98765,"status":"generated","stops_due":6,"stops_generated":6,"stops_skipped":0,"generated_at":"2026-09-15 18:00:04","error":null}]}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/generate":{"post":{"tags":["Client"],"summary":"Generate the recurring pickup routes of a date","description":"The same idempotent flow the scheduler runs: due pickups get their order once, each template its route once. dry_run reports what would be generated and writes nothing; regenerate cancels a template's route when no stop has started and builds it again. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403): creating, editing, deleting and generating stay the business's. Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientGenerateRecurringPickups","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service_date"],"properties":{"service_date":{"type":"string","format":"date","description":"**Required.**\n\nService date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date`."},"template_id":{"type":["integer","null"],"description":"Template id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"dry_run":{"type":"boolean","description":"Report what would be generated and write nothing\n\n**Details:** Type `boolean`."},"regenerate":{"type":"boolean","description":"Cancel the run's route when no stop has started and build it again\n\n**Details:** Type `boolean`."}}}}}},"responses":{"200":{"description":"Generation result","content":{"application/json":{"example":{"success":true,"data":{"business_id":2,"service_date":"2026-09-16","dry_run":false,"templates":[{"template_id":4,"template_name":"Downtown morning collection","sequence_mode":"fixed","status":"generated","route_id":98765,"stops_due":6,"stops_generated":6,"stops_skipped":0,"orders":[{"pickup_schedule_id":31,"customer_name":"Northside Bakery","order_id":555001,"created":true,"planned":true}],"error":null}],"unassigned":[],"error":null}}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"Choose at least one weekday.","errors":{"weekdays":["Choose at least one weekday."]}}}}},"403":{"description":"Not allowed to use recurring pickups, or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}}}}},"/v1/client/recurring-pickups/suggestions":{"get":{"tags":["Client"],"summary":"List recurring pickup suggestions from pickup history","description":"Schedules and templates proposed from the business's completed pickups (type P, and the pickup leg of deliveries at their sender address) of a period: at most 26 weeks, 8 weeks up to yesterday by default, read one week at a time with a cap per page and in total (truncated tells when the cap was reached). A location visited on a recognisable rhythm (weekdays, every N days, days of the month) becomes a proposed schedule with its evidence and a confidence (0-1); schedules usually served by one driver become a proposed template in their usual stop order. Locations an active schedule already covers, orders generated by the module, and dismissed suggestions are left out. Nothing is created until a suggestion is accepted. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403). Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientRecurringPickupSuggestions","security":[{"bearerAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"First date analysed; default 8 weeks before to\n\n**Details:** Optional · Type `string`, format `date`."},"description":"First date analysed; default 8 weeks before to\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Last date analysed; default yesterday\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Last date analysed; default yesterday\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"include_dismissed","in":"query","required":false,"schema":{"type":"boolean","description":"Also list dismissed schedule suggestions, flagged dismissed\n\n**Details:** Optional · Type `boolean`."},"description":"Also list dismissed schedule suggestions, flagged dismissed\n\n**Details:** Optional · Type `boolean`."}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"example":{"success":true,"data":{"period":{"from":"2026-07-20","to":"2026-09-13"},"scanned_orders":412,"truncated":false,"schedules":[{"kind":"schedule","fingerprint":"3f1c9a0d7e5b4c2a1908f6e3d2c1b0a9f8e7d6c5","confidence":0.94,"pattern":{"type":"weekly","weekdays":[1,3,5],"interval_days":null,"month_days":[]},"proposed":{"customer_name":"Northside Bakery","company_name":null,"telephone":"+1 604 555 0101","email":null,"customer_user_id":null,"address_1":"120 Main St","address_2":null,"city":"Vancouver","province":"BC","postcode":"V6B 1A1","country":"CA","lat":49.2827,"lng":-123.1207,"recurrence_type":"weekly","weekdays":[1,3,5],"interval_days":null,"month_days":[],"starts_on":"2026-09-14","window_start":"09:00","window_end":"11:00","service_minutes":5,"expected_packages":3},"evidence":{"occurrences":18,"first_seen":"2026-08-03","last_seen":"2026-09-11","dates":["2026-08-03","2026-08-05","2026-08-07"],"order_ids":[550101,550214,550330]},"usual":{"driver_id":77,"driver_name":"Dana Driver","driver_share":1,"median_stop_position":2},"dismissed":false}],"templates":[{"kind":"template","fingerprint":"9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b","confidence":0.92,"proposed":{"name":"Dana Driver pickups","driver_id":77,"driver_name":"Dana Driver","sequence_mode":"fixed","weekdays":[1,3,5],"starts_on":"2026-09-14"},"members":[{"fingerprint":"0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d","customer_name":"Harbour Deli","address":"9 Water St, Vancouver","sequence":1,"median_stop_position":1},{"fingerprint":"3f1c9a0d7e5b4c2a1908f6e3d2c1b0a9f8e7d6c5","customer_name":"Northside Bakery","address":"120 Main St, Vancouver","sequence":2,"median_stop_position":2}],"dismissed":false}]}}}}},"403":{"description":"Not allowed (contractors included), or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}},"409":{"description":"The module's migrations have not run (error_code schema_not_ready)","content":{"application/json":{"example":{"success":false,"error_code":"schema_not_ready","message":"The recurring pickup tables are not migrated yet."}}}}}}},"/v1/client/recurring-pickups/suggestions/accept":{"post":{"tags":["Client"],"summary":"Accept a recurring pickup suggestion","description":"Creates what the suggestion proposes, with the client's edits, through the ordinary schedule and template validation: kind schedule creates the schedule; kind template creates its schedules and the template with them as members in the proposed order, in one transaction. The suggestion is recomputed for the given period; one no longer proposed answers 404 with error_code suggestion_not_found. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403). Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientAcceptRecurringPickupSuggestion","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","fingerprint"],"properties":{"kind":{"type":"string","enum":["schedule","template"],"description":"**Required.**\n\nAllowed values: `schedule` · `template`.\n\n**Details:** Type `string`."},"fingerprint":{"type":"string","description":"**Required.**\n\nThe suggestion fingerprint (40 hex characters)\n\n**Details:** Type `string`."},"overrides":{"type":"object","description":"Edits. Schedule: customer_name, starts_on, window_start, window_end, service_minutes, expected_packages, telephone, email, instructions. Template: name, sequence_mode, starts_on (for its schedules).\n\n**Details:** Type `object`."},"from":{"type":"string","format":"date","description":"The period the suggestion was listed for\n\n**Details:** Type `string`, format `date`."},"to":{"type":"string","format":"date","description":"To. Field in the JSON request body.\n\n**Details:** Type `string`, format `date`."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"example":{"success":true,"data":{"kind":"schedule","schedules":[{"id":41,"status":"active","customer_name":"Northside Bakery","recurrence_type":"weekly","weekdays":[1,3,5],"starts_on":"2026-09-14","window_start":"09:00","window_end":"11:00"}],"template":null}}}}},"404":{"description":"The suggestion is no longer proposed","content":{"application/json":{"example":{"success":false,"error_code":"suggestion_not_found","message":"The suggestion is no longer available. Analyse again."}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"kind must be one of: schedule, template.","errors":{"kind":["kind must be one of: schedule, template."]}}}}},"403":{"description":"Not allowed (contractors included), or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}},"409":{"description":"The module's migrations have not run (error_code schema_not_ready)","content":{"application/json":{"example":{"success":false,"error_code":"schema_not_ready","message":"The recurring pickup tables are not migrated yet."}}}}}}},"/v1/client/recurring-pickups/suggestions/dismiss":{"post":{"tags":["Client"],"summary":"Dismiss a recurring pickup suggestion","description":"Remembers the suggestion by its fingerprint so it is not proposed again (include_dismissed lists it again, flagged). Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403). Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientDismissRecurringPickupSuggestion","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","fingerprint"],"properties":{"kind":{"type":"string","enum":["schedule","template"],"description":"**Required.**\n\nAllowed values: `schedule` · `template`.\n\n**Details:** Type `string`."},"fingerprint":{"type":"string","description":"**Required.**\n\nThe suggestion fingerprint (40 hex characters)\n\n**Details:** Type `string`."},"label":{"type":["string","null"],"description":"Optional label kept with the dismissal\n\n**Details:** Type `string` · Nullable."}}}}}},"responses":{"200":{"description":"Dismissed","content":{"application/json":{"example":{"success":true,"data":{"kind":"schedule","fingerprint":"3f1c9a0d7e5b4c2a1908f6e3d2c1b0a9f8e7d6c5","dismissed":true}}}}},"422":{"description":"Validation failed","content":{"application/json":{"example":{"success":false,"message":"kind must be one of: schedule, template.","errors":{"kind":["kind must be one of: schedule, template."]}}}}},"403":{"description":"Not allowed (contractors included), or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}},"409":{"description":"The module's migrations have not run (error_code schema_not_ready)","content":{"application/json":{"example":{"success":false,"error_code":"schema_not_ready","message":"The recurring pickup tables are not migrated yet."}}}}}}},"/v1/client/recurring-pickups/schedules/{id}/self-service":{"get":{"tags":["Client"],"summary":"Get the customer self-service of a recurring pickup schedule","description":"What the customer of a schedule may change themselves (customer self-service): the rights resolved from the template's defaults and the schedule's overrides, the cut-off, the current signed self-service link (valid 30 days; null while the customer may do nothing) and the upcoming dates with the actions still open on each. The rights are edited with the schedule and template create / update operations. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403). Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientRecurringPickupSelfService","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Self-service","content":{"application/json":{"example":{"success":true,"data":{"pickup_schedule_id":31,"can_skip":true,"can_change_window":true,"can_request_extra":false,"cutoff_hours":12,"cutoff_basis":"generation","overrides":{"customer_can_skip":null,"customer_can_change_window":1,"customer_can_request_extra":null,"customer_cutoff_hours":null,"customer_cutoff_basis":null},"link":"https://www.superroute.ca/pickup-schedule/Vq3T0s9Xk2LmN8pQ4rS6uW1yZ5aB7cD9eF0gH2iJ4kL6mN8p?expires=1760400000&signature=5c2f0e8d","link_valid_days":30,"self_service_token_rotated_at":"2026-09-14 10:00:00","upcoming":[{"date":"2026-09-16","due":true,"exception":null,"window_start":"09:00","window_end":"11:00","cutoff_at":"2026-09-15 06:00:00","open":true,"can_skip":true,"can_unskip":false,"can_change_window":true,"can_request_extra":false,"started":false,"order_id":null}]}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed (contractors included), or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}},"409":{"description":"The module's migrations have not run (error_code schema_not_ready)","content":{"application/json":{"example":{"success":false,"error_code":"schema_not_ready","message":"The recurring pickup tables are not migrated yet."}}}}}}},"/v1/client/recurring-pickups/schedules/{id}/self-service/rotate-link":{"post":{"tags":["Client"],"summary":"Rotate the customer self-service link of a recurring pickup schedule","description":"A new self-service token: every link handed out before (in reminders, on tracking pages) stops working. The answer is the self-service view with the new link. Requires Recurring Pickups to be enabled for the account by the platform administrator; while it is off every recurring pickup operation answers 403 with error_code recurring_pickups_not_enabled. Contractors (brokers) are refused (403). Before the module's migrations have run the answer is 409 with error_code schema_not_ready.","operationId":"clientRotateRecurringPickupSelfServiceLink","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Schedule id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Self-service with the new link","content":{"application/json":{"example":{"success":true,"data":{"pickup_schedule_id":31,"can_skip":true,"can_change_window":true,"can_request_extra":false,"cutoff_hours":12,"cutoff_basis":"generation","overrides":{"customer_can_skip":null,"customer_can_change_window":1,"customer_can_request_extra":null,"customer_cutoff_hours":null,"customer_cutoff_basis":null},"link":"https://www.superroute.ca/pickup-schedule/Vq3T0s9Xk2LmN8pQ4rS6uW1yZ5aB7cD9eF0gH2iJ4kL6mN8p?expires=1760400000&signature=5c2f0e8d","link_valid_days":30,"self_service_token_rotated_at":"2026-09-14 10:00:00","upcoming":[{"date":"2026-09-16","due":true,"exception":null,"window_start":"09:00","window_end":"11:00","cutoff_at":"2026-09-15 06:00:00","open":true,"can_skip":true,"can_unskip":false,"can_change_window":true,"can_request_extra":false,"started":false,"order_id":null}]}}}}},"404":{"description":"Not found","content":{"application/json":{"example":{"success":false,"message":"Not found."}}}},"403":{"description":"Not allowed (contractors included), or Recurring Pickups is not enabled for the account (error_code recurring_pickups_not_enabled)","content":{"application/json":{"example":{"success":false,"error_code":"recurring_pickups_not_enabled","message":"Recurring pickups are not enabled for this account. Please ask the platform administrator to enable them."}}}},"409":{"description":"The module's migrations have not run (error_code schema_not_ready)","content":{"application/json":{"example":{"success":false,"error_code":"schema_not_ready","message":"The recurring pickup tables are not migrated yet."}}}}}}},"/device-orders":{"get":{"tags":["Device Orders"],"summary":"List device orders","description":"Ledger rows the caller may see, newest first. Internal staff see every handling of their business; a supplier sees only its own partner deliveries; a venue partner sees what is in the machines at its sites.","operationId":"deviceOrdersIndex","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},{"name":"status","in":"query","required":false,"schema":{"type":"string","description":"created / reserved / depositing / stored / retrieving / collected / removed / failed / cancelled.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},"description":"created / reserved / depositing / stored / retrieving / collected / removed / failed / cancelled.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Optional · Type `string`."},{"name":"kind","in":"query","required":false,"schema":{"type":"string","description":"Device order kind, e.g. shipout_pickup, partner_delivery, smart_drop_return.\n\n**Details:** Optional · Type `string`."},"description":"Device order kind, e.g. shipout_pickup, partner_delivery, smart_drop_return.\n\n**Details:** Optional · Type `string`."},{"name":"device_type","in":"query","required":false,"schema":{"type":"string","description":"smart_locker / kiosk / smart_drop.\n\n**Details:** Optional · Type `string`."},"description":"smart_locker / kiosk / smart_drop.\n\n**Details:** Optional · Type `string`."},{"name":"device_id","in":"query","required":false,"schema":{"type":"integer","description":"Device id (with device_type).\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Optional · Type `integer`."},"description":"Device id (with device_type).\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Optional · Type `integer`."},{"name":"next_actor","in":"query","required":false,"schema":{"type":"string","description":"Who the handling waits on: recipient / customer / courier / operator / partner / nobody.\n\n**Details:** Optional · Type `string`."},"description":"Who the handling waits on: recipient / customer / courier / operator / partner / nobody.\n\n**Details:** Optional · Type `string`."},{"name":"overdue","in":"query","required":false,"schema":{"type":"boolean","description":"true = only overdue handlings, false = only ones not overdue.\n\n**Details:** Optional · Type `boolean`."},"description":"true = only overdue handlings, false = only ones not overdue.\n\n**Details:** Optional · Type `boolean`."},{"name":"order_id","in":"query","required":false,"schema":{"type":"integer","description":"Delivery order id.\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`."},"description":"Delivery order id.\n\nSuperroute order id (`orders.id`).\n\n**Details:** Optional · Type `integer`."},{"name":"reference","in":"query","required":false,"schema":{"type":"string","description":"Search in the reference (tracking) number and external order id.\n\nExternal or internal reference string for correlation.\n\n**Details:** Optional · Type `string`."},"description":"Search in the reference (tracking) number and external order id.\n\nExternal or internal reference string for correlation.\n\n**Details:** Optional · Type `string`."},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d, inclusive, on stored_at, in the caller’s timezone.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d, inclusive, on stored_at, in the caller’s timezone.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","format":"date","description":"Y-m-d, inclusive, on stored_at, in the caller’s timezone.\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Y-m-d, inclusive, on stored_at, in the caller’s timezone.\n\n**Details:** Optional · Type `string`, format `date`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"1-based page number.\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"1-based page number.\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","description":"Default 20, maximum 100.\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"Default 20, maximum 100.\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Paginated device orders.","content":{"application/json":{"example":{"success":true,"data":[{"id":4812,"device_type":"smart_locker","device_id":11,"device_name":"Locker A","warehouse_id":5,"section_id":2,"grid_id":501,"grid_code":"A-12","locker_compartment_number":12,"kind":"shipout_pickup","owner_side":"operator","partner_provider_id":null,"customer_id":318,"source_table":"shipping_orders","source_id":90211,"order_id":77120,"external_order_id":null,"reference_number":"SR123456789CA","group_ref":null,"status":"stored","next_actor":"recipient","is_terminal":false,"is_overdue":false,"code_attempts":0,"code_locked":false,"depositor_type":"driver","depositor_id":45,"collector_type":null,"collector_id":null,"removal_reason":null,"failure_code":null,"due_at":"2026-09-18T10:02:00-04:00","overdue_at":null,"reminded_at":null,"reminder_count":0,"reserved_at":"2026-09-15T09:58:12-04:00","deposit_opened_at":"2026-09-15T10:01:40-04:00","stored_at":"2026-09-15T10:02:00-04:00","retrieve_opened_at":null,"ended_at":null,"created_at":"2026-09-15T09:58:12-04:00","updated_at":"2026-09-15T10:02:00-04:00"}],"pagination":{"current_page":1,"per_page":20,"total":1,"last_page":1}},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"device_type":{"type":["string","null"],"description":"Device type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"device_id":{"type":["integer","null"],"description":"Stable device identifier from the mobile / kiosk client.\n\n**Details:** Type `integer` · Nullable."},"device_name":{"type":["string","null"],"description":"Device name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"warehouse_id":{"type":["integer","null"],"description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `integer` · Nullable."},"section_id":{"type":["integer","null"],"description":"Section id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"grid_id":{"type":["integer","null"],"description":"Grid id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"grid_code":{"type":["string","null"],"description":"Grid code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"locker_compartment_number":{"type":["integer","null"],"description":"Locker compartment number. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"kind":{"type":["string","null"],"description":"Kind. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"owner_side":{"type":["string","null"],"description":"Owner side. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"partner_provider_id":{"type":["string","null"],"description":"Partner provider id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"customer_id":{"type":["integer","null"],"description":"Customer id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"source_table":{"type":["string","null"],"description":"Source table. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"source_id":{"type":["integer","null"],"description":"Source id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"external_order_id":{"type":["string","null"],"description":"Merchant / upstream order reference stored on the Superroute order.\n\n**Details:** Type `string` · Nullable."},"reference_number":{"type":["string","null"],"description":"Reference number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"group_ref":{"type":["string","null"],"description":"Group ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"next_actor":{"type":["string","null"],"description":"Next actor. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"is_terminal":{"type":"boolean","description":"Is terminal. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"is_overdue":{"type":"boolean","description":"Is overdue. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"code_attempts":{"type":["integer","null"],"description":"Code attempts. Stable machine-readable code.\n\n**Details:** Type `integer` · Nullable."},"code_locked":{"type":"boolean","description":"Code locked. Stable machine-readable code.\n\n**Details:** Type `boolean`."},"depositor_type":{"type":["string","null"],"description":"Depositor type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"depositor_id":{"type":["integer","null"],"description":"Depositor id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"collector_type":{"type":["string","null"],"description":"Collector type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"collector_id":{"type":["string","null"],"description":"Collector id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"removal_reason":{"type":["string","null"],"description":"Removal reason. Free-text note.\n\n**Details:** Type `string` · Nullable."},"failure_code":{"type":["string","null"],"description":"Failure code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"due_at":{"type":["string","null"],"description":"Due at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"overdue_at":{"type":["string","null"],"description":"Overdue at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"reminded_at":{"type":["string","null"],"description":"Reminded at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"reminder_count":{"type":["integer","null"],"description":"Reminder count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"reserved_at":{"type":["string","null"],"description":"Reserved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"deposit_opened_at":{"type":["string","null"],"description":"Deposit opened at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"stored_at":{"type":["string","null"],"description":"Stored at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"retrieve_opened_at":{"type":["string","null"],"description":"Retrieve opened at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"ended_at":{"type":["string","null"],"description":"Ended at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"created_at":{"type":["string","null"],"description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"updated_at":{"type":["string","null"],"description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}},"description":"pickup_code_hash and code_locked_until are never exposed; code_locked reports whether the pickup code is locked now. Timestamps are ISO 8601 in the caller’s timezone."},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"pagination":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page. Field in the JSON request body.\n\n**Details:** Type `integer`."},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"last_page":{"type":"integer","description":"Last page. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Pagination. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"The caller may not use the device order module (not staff, supplier or venue partner; contractors always refused).","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}},"422":{"description":"A filter is invalid.","content":{"application/json":{"example":{"success":false,"message":"The selected status is invalid."}}}}}}},"/device-orders/{id}":{"get":{"tags":["Device Orders"],"summary":"Show a device order","description":"One ledger row. Hidden rows answer 404 exactly like missing ones.","operationId":"deviceOrderShow","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Device order id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Device order id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The device order.","content":{"application/json":{"example":{"success":true,"data":{"id":4812,"device_type":"smart_locker","device_id":11,"device_name":"Locker A","warehouse_id":5,"section_id":2,"grid_id":501,"grid_code":"A-12","locker_compartment_number":12,"kind":"shipout_pickup","owner_side":"operator","partner_provider_id":null,"customer_id":318,"source_table":"shipping_orders","source_id":90211,"order_id":77120,"external_order_id":null,"reference_number":"SR123456789CA","group_ref":null,"status":"stored","next_actor":"recipient","is_terminal":false,"is_overdue":false,"code_attempts":0,"code_locked":false,"depositor_type":"driver","depositor_id":45,"collector_type":null,"collector_id":null,"removal_reason":null,"failure_code":null,"due_at":"2026-09-18T10:02:00-04:00","overdue_at":null,"reminded_at":null,"reminder_count":0,"reserved_at":"2026-09-15T09:58:12-04:00","deposit_opened_at":"2026-09-15T10:01:40-04:00","stored_at":"2026-09-15T10:02:00-04:00","retrieve_opened_at":null,"ended_at":null,"created_at":"2026-09-15T09:58:12-04:00","updated_at":"2026-09-15T10:02:00-04:00"}},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"device_type":{"type":["string","null"],"description":"Device type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"device_id":{"type":["integer","null"],"description":"Stable device identifier from the mobile / kiosk client.\n\n**Details:** Type `integer` · Nullable."},"device_name":{"type":["string","null"],"description":"Device name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"warehouse_id":{"type":["integer","null"],"description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `integer` · Nullable."},"section_id":{"type":["integer","null"],"description":"Section id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"grid_id":{"type":["integer","null"],"description":"Grid id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"grid_code":{"type":["string","null"],"description":"Grid code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"locker_compartment_number":{"type":["integer","null"],"description":"Locker compartment number. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"kind":{"type":["string","null"],"description":"Kind. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"owner_side":{"type":["string","null"],"description":"Owner side. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"partner_provider_id":{"type":["string","null"],"description":"Partner provider id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"customer_id":{"type":["integer","null"],"description":"Customer id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"source_table":{"type":["string","null"],"description":"Source table. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"source_id":{"type":["integer","null"],"description":"Source id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"external_order_id":{"type":["string","null"],"description":"Merchant / upstream order reference stored on the Superroute order.\n\n**Details:** Type `string` · Nullable."},"reference_number":{"type":["string","null"],"description":"Reference number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"group_ref":{"type":["string","null"],"description":"Group ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"next_actor":{"type":["string","null"],"description":"Next actor. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"is_terminal":{"type":"boolean","description":"Is terminal. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"is_overdue":{"type":"boolean","description":"Is overdue. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"code_attempts":{"type":["integer","null"],"description":"Code attempts. Stable machine-readable code.\n\n**Details:** Type `integer` · Nullable."},"code_locked":{"type":"boolean","description":"Code locked. Stable machine-readable code.\n\n**Details:** Type `boolean`."},"depositor_type":{"type":["string","null"],"description":"Depositor type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"depositor_id":{"type":["integer","null"],"description":"Depositor id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"collector_type":{"type":["string","null"],"description":"Collector type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"collector_id":{"type":["string","null"],"description":"Collector id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"removal_reason":{"type":["string","null"],"description":"Removal reason. Free-text note.\n\n**Details:** Type `string` · Nullable."},"failure_code":{"type":["string","null"],"description":"Failure code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"due_at":{"type":["string","null"],"description":"Due at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"overdue_at":{"type":["string","null"],"description":"Overdue at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"reminded_at":{"type":["string","null"],"description":"Reminded at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"reminder_count":{"type":["integer","null"],"description":"Reminder count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"reserved_at":{"type":["string","null"],"description":"Reserved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"deposit_opened_at":{"type":["string","null"],"description":"Deposit opened at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"stored_at":{"type":["string","null"],"description":"Stored at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"retrieve_opened_at":{"type":["string","null"],"description":"Retrieve opened at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"ended_at":{"type":["string","null"],"description":"Ended at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"created_at":{"type":["string","null"],"description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"updated_at":{"type":["string","null"],"description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}},"description":"pickup_code_hash and code_locked_until are never exposed; code_locked reports whether the pickup code is locked now. Timestamps are ISO 8601 in the caller’s timezone.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"The caller may not use the device order module (not staff, supplier or venue partner; contractors always refused).","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}},"404":{"description":"No such device order, or one the caller may not see (the two are indistinguishable).","content":{"application/json":{"example":{"success":false,"message":"Not Found"}}}}}}},"/device-orders/{id}/events":{"get":{"tags":["Device Orders"],"summary":"Device order history","description":"The append-only history of one device order, oldest first. Pickup codes never appear in payloads.","operationId":"deviceOrderEvents","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Device order id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Device order id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The events.","content":{"application/json":{"example":{"success":true,"data":[{"id":99120,"device_order_id":4812,"event_type":"stored","from_status":"depositing","to_status":"stored","actor_type":"driver","actor_id":45,"channel":"device","smart_locker_log_id":551203,"device_operation_log_id":null,"payload":{"door_verified":true},"occurred_at":"2026-09-15T10:02:00-04:00"}]},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"device_order_id":{"type":["integer","null"],"description":"Device order id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"event_type":{"type":["string","null"],"description":"Event type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"from_status":{"type":["string","null"],"description":"From status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string` · Nullable."},"to_status":{"type":["string","null"],"description":"To status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string` · Nullable."},"actor_type":{"type":["string","null"],"description":"Actor type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"actor_id":{"type":["integer","null"],"description":"Actor id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"channel":{"type":["string","null"],"description":"Channel. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"smart_locker_log_id":{"type":["integer","null"],"description":"Smart locker log id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"device_operation_log_id":{"type":["string","null"],"description":"Device operation log id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"payload":{"type":["object","null"],"description":"Payload. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"occurred_at":{"type":["string","null"],"description":"When the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string` · Nullable."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"403":{"description":"The caller may not use the device order module (not staff, supplier or venue partner; contractors always refused).","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}},"404":{"description":"No such device order, or one the caller may not see (the two are indistinguishable).","content":{"application/json":{"example":{"success":false,"message":"Not Found"}}}}}}},"/device-orders/{id}/exceptions":{"get":{"tags":["Device Orders"],"summary":"Device order exceptions","description":"The exceptions raised on one device order, newest first. actionable says whether this caller may acknowledge or resolve each one.","operationId":"deviceOrderExceptions","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Device order id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Device order id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"The exceptions.","content":{"application/json":{"example":{"success":true,"data":[{"id":310,"device_order_id":4812,"device_type":"smart_locker","device_id":11,"grid_id":501,"type":"door_open_failed","severity":"attention","status":"open","detected_by":"system","detail":{"occurrences":1,"error":"Door did not open"},"resolution":null,"resolution_action":null,"opened_at":"2026-09-15T10:01:45-04:00","acknowledged_by":null,"acknowledged_at":null,"resolved_by":null,"resolved_at":null,"actionable":true}]},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"device_order_id":{"type":["integer","null"],"description":"Device order id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"device_type":{"type":["string","null"],"description":"Device type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"device_id":{"type":["integer","null"],"description":"Stable device identifier from the mobile / kiosk client.\n\n**Details:** Type `integer` · Nullable."},"grid_id":{"type":["integer","null"],"description":"Grid id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"type":{"type":["string","null"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string` · Nullable."},"severity":{"type":["string","null"],"description":"Severity. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"detected_by":{"type":["string","null"],"description":"Detected by. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"detail":{"type":["object","null"],"description":"Detail. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"resolution":{"type":["string","null"],"description":"Resolution. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"resolution_action":{"type":["string","null"],"description":"Resolution action. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"opened_at":{"type":["string","null"],"description":"Opened at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"acknowledged_by":{"type":["string","null"],"description":"Acknowledged by. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"acknowledged_at":{"type":["string","null"],"description":"Acknowledged at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"resolved_by":{"type":["string","null"],"description":"Resolved by. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"resolved_at":{"type":["string","null"],"description":"Resolved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"actionable":{"type":"boolean","description":"Actionable. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"403":{"description":"The caller may not use the device order module (not staff, supplier or venue partner; contractors always refused).","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}},"404":{"description":"No such device order, or one the caller may not see (the two are indistinguishable).","content":{"application/json":{"example":{"success":false,"message":"Not Found"}}}}}}},"/device-orders/exceptions/{id}/acknowledge":{"post":{"tags":["Device Orders"],"summary":"Acknowledge a device order exception","description":"Marks an open exception as acknowledged. Requires smart locker management permission (client admins always; employees when enabled; contractors never).","operationId":"deviceOrderExceptionAcknowledge","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Exception id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Exception id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Acknowledged.","content":{"application/json":{"example":{"success":true,"message":"Acknowledged.","data":{"id":310,"device_order_id":4812,"device_type":"smart_locker","device_id":11,"grid_id":501,"type":"door_open_failed","severity":"attention","status":"acknowledged","detected_by":"system","detail":{"occurrences":1,"error":"Door did not open"},"resolution":null,"resolution_action":null,"opened_at":"2026-09-15T10:01:45-04:00","acknowledged_by":2,"acknowledged_at":"2026-09-15T10:05:00-04:00","resolved_by":null,"resolved_at":null,"actionable":true}},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"device_order_id":{"type":["integer","null"],"description":"Device order id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"device_type":{"type":["string","null"],"description":"Device type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"device_id":{"type":["integer","null"],"description":"Stable device identifier from the mobile / kiosk client.\n\n**Details:** Type `integer` · Nullable."},"grid_id":{"type":["integer","null"],"description":"Grid id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"type":{"type":["string","null"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string` · Nullable."},"severity":{"type":["string","null"],"description":"Severity. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"detected_by":{"type":["string","null"],"description":"Detected by. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"detail":{"type":["object","null"],"description":"Detail. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"resolution":{"type":["string","null"],"description":"Resolution. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"resolution_action":{"type":["string","null"],"description":"Resolution action. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"opened_at":{"type":["string","null"],"description":"Opened at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"acknowledged_by":{"type":["string","null"],"description":"Acknowledged by. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"acknowledged_at":{"type":["string","null"],"description":"Acknowledged at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"resolved_by":{"type":["string","null"],"description":"Resolved by. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"resolved_at":{"type":["string","null"],"description":"Resolved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"actionable":{"type":"boolean","description":"Actionable. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"Not allowed, or no such exception in the caller’s business.","content":{"application/json":{"example":{"success":false,"message":"You are not allowed to act on this exception."}}}},"422":{"description":"The exception is not open.","content":{"application/json":{"example":{"success":false,"message":"This exception is no longer open."}}}}}}},"/device-orders/exceptions/{id}/resolve":{"post":{"tags":["Device Orders"],"summary":"Resolve or dismiss a device order exception","description":"Closes an unresolved exception with what was done about it. dismiss=true marks a report that turned out to be nothing; the action is still recorded. Same permission as acknowledge.","operationId":"deviceOrderExceptionResolve","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Exception id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Exception id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["reopened","took_out","reassigned","emptied","marked_ok","escalated"],"description":"**Required.**\n\nAllowed values: `reopened` · `took_out` · `reassigned` · `emptied` · `marked_ok` · `escalated`.\n\n**Details:** Type `string`."},"note":{"type":"string","maxLength":2000,"description":"Note. Free-text note.\n\n**Details:** Type `string` · maxLength `2000`."},"dismiss":{"type":"boolean","default":false,"description":"Dismiss. Field in the JSON request body.\n\n**Details:** Type `boolean` · Default: `false`."}}},"example":{"action":"reopened","note":"Door reopened from the console","dismiss":false}}}},"responses":{"200":{"description":"Resolved.","content":{"application/json":{"example":{"success":true,"message":"Resolved.","data":{"id":310,"device_order_id":4812,"device_type":"smart_locker","device_id":11,"grid_id":501,"type":"door_open_failed","severity":"attention","status":"resolved","detected_by":"system","detail":{"occurrences":1,"error":"Door did not open"},"resolution":"Door reopened from the console","resolution_action":"reopened","opened_at":"2026-09-15T10:01:45-04:00","acknowledged_by":2,"acknowledged_at":"2026-09-15T10:05:00-04:00","resolved_by":2,"resolved_at":"2026-09-15T10:07:00-04:00","actionable":true}},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"device_order_id":{"type":["integer","null"],"description":"Device order id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"device_type":{"type":["string","null"],"description":"Device type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"device_id":{"type":["integer","null"],"description":"Stable device identifier from the mobile / kiosk client.\n\n**Details:** Type `integer` · Nullable."},"grid_id":{"type":["integer","null"],"description":"Grid id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"type":{"type":["string","null"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string` · Nullable."},"severity":{"type":["string","null"],"description":"Severity. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"detected_by":{"type":["string","null"],"description":"Detected by. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"detail":{"type":["object","null"],"description":"Detail. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"resolution":{"type":["string","null"],"description":"Resolution. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"resolution_action":{"type":["string","null"],"description":"Resolution action. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"opened_at":{"type":["string","null"],"description":"Opened at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"acknowledged_by":{"type":["string","null"],"description":"Acknowledged by. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"acknowledged_at":{"type":["string","null"],"description":"Acknowledged at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"resolved_by":{"type":["string","null"],"description":"Resolved by. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"resolved_at":{"type":["string","null"],"description":"Resolved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."},"actionable":{"type":"boolean","description":"Actionable. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}}}}},"403":{"description":"Not allowed, or no such exception in the caller’s business.","content":{"application/json":{"example":{"success":false,"message":"You are not allowed to act on this exception."}}}},"422":{"description":"Unknown action, note too long, or the exception is already closed.","content":{"application/json":{"example":{"success":false,"message":"This exception is already closed."}}}}}}},"/device-orders/{id}/resend-code":{"post":{"tags":["Device Orders"],"summary":"Resend a device order pickup code","description":"Sends the pickup code again to whoever is meant to collect the parcel and clears any attempt lock. Requires the row to be visible and smart locker management permission.","operationId":"deviceOrderCodeResend","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Device order id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Device order id.\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Sent.","content":{"application/json":{"example":{"success":true,"message":"Code sent.","channel":"sms"},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"channel":{"type":["string","null"],"description":"Channel. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}}}}},"403":{"description":"The caller may see the row but may not manage smart lockers.","content":{"application/json":{"example":{"success":false,"message":"Not Authorized"}}}},"404":{"description":"No such device order, or one the caller may not see (the two are indistinguishable).","content":{"application/json":{"example":{"success":false,"message":"Not Found"}}}},"422":{"description":"The code could not be resent for this handling.","content":{"application/json":{"example":{"success":false,"message":"not_supported","channel":null}}}}}}},"/device-orders/code-locks":{"get":{"tags":["Device Orders"],"summary":"List machines with a pickup-code lock","description":"Smart lockers and kiosks of the caller's business whose pickup-by-code is locked right now after too many codes that matched nothing, or that are counting such codes in an open window. Internal staff only.","operationId":"deviceOrderCodeLocks","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."}],"responses":{"200":{"description":"The machines, locked first.","content":{"application/json":{"example":{"success":true,"data":[{"device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A1","locked":true,"locked_until":"2026-09-15T10:15:00-04:00","minutes_remaining":12,"failed_count":0,"window_started_at":null,"last_failed_at":"2026-09-15T10:00:00-04:00","locked_at":"2026-09-15T10:00:00-04:00","lock_count":1,"unlocked_by":null,"unlocked_at":null,"actionable":true}]},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"array","items":{"type":"object","properties":{"device_type":{"type":"string","enum":["smart_locker","kiosk","smart_drop"],"description":"Allowed values: `smart_locker` · `kiosk` · `smart_drop`.\n\n**Details:** Type `string`."},"device_id":{"type":"integer","description":"Shelf id for a smart locker, kiosk id for a kiosk.\n\n**Details:** Type `integer`."},"device_name":{"type":["string","null"],"description":"Device name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"locked":{"type":"boolean","description":"Whether pickup-by-code on the machine is locked right now.\n\n**Details:** Type `boolean`."},"locked_until":{"type":["string","null"],"format":"date-time","description":"Locked until. Field in the JSON request body.\n\n**Details:** Type `string`, format `date-time` · Nullable."},"minutes_remaining":{"type":"integer","description":"Minutes remaining. Field in the JSON request body.\n\n**Details:** Type `integer`."},"failed_count":{"type":"integer","description":"Codes that matched nothing in the current window.\n\n**Details:** Type `integer`."},"window_started_at":{"type":["string","null"],"format":"date-time","description":"Window started at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"last_failed_at":{"type":["string","null"],"format":"date-time","description":"Last failed at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"locked_at":{"type":["string","null"],"format":"date-time","description":"Locked at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"lock_count":{"type":"integer","description":"Times the machine has been locked (lifetime).\n\n**Details:** Type `integer`."},"unlocked_by":{"type":["integer","null"],"description":"Unlocked by. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"unlocked_at":{"type":["string","null"],"format":"date-time","description":"Unlocked at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"actionable":{"type":"boolean","description":"Whether the caller may unlock (re-checked on unlock).\n\n**Details:** Type `boolean`."}}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}}}}},"403":{"description":"The caller is not operator staff of the business.","content":{"application/json":{"example":{"success":false,"message":"You are not allowed to act on this exception."}}}}}}},"/device-orders/code-locks/unlock":{"post":{"tags":["Device Orders"],"summary":"Unlock pickup-by-code on a machine","description":"Lifts the pickup-code lock of one smart locker or kiosk, resets its counters and closes its open code_attempts_exceeded exception as marked OK. Requires smart locker management permission and a machine of the caller's business.","operationId":"deviceOrderCodeLockUnlock","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."},"description":"Bearer <business API token>.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_type","device_id"],"properties":{"device_type":{"type":"string","enum":["smart_locker","kiosk","smart_drop"],"description":"**Required.**\n\nAllowed values: `smart_locker` · `kiosk` · `smart_drop`.\n\n**Details:** Type `string`."},"device_id":{"type":"integer","description":"**Required.**\n\nShelf id for a smart locker, kiosk id for a kiosk.\n\n**Details:** Type `integer`."}}},"example":{"device_type":"smart_locker","device_id":11}}}},"responses":{"200":{"description":"Unlocked.","content":{"application/json":{"example":{"success":true,"message":"Pickup by code unlocked.","data":{"device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A1","locked":false,"locked_until":null,"minutes_remaining":0,"failed_count":0,"window_started_at":null,"last_failed_at":"2026-09-15T10:00:00-04:00","locked_at":"2026-09-15T10:00:00-04:00","lock_count":1,"unlocked_by":2,"unlocked_at":"2026-09-15T10:03:00-04:00","actionable":true}},"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":["object","null"],"properties":{"device_type":{"type":"string","enum":["smart_locker","kiosk","smart_drop"],"description":"Allowed values: `smart_locker` · `kiosk` · `smart_drop`.\n\n**Details:** Type `string`."},"device_id":{"type":"integer","description":"Shelf id for a smart locker, kiosk id for a kiosk.\n\n**Details:** Type `integer`."},"device_name":{"type":["string","null"],"description":"Device name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"locked":{"type":"boolean","description":"Whether pickup-by-code on the machine is locked right now.\n\n**Details:** Type `boolean`."},"locked_until":{"type":["string","null"],"format":"date-time","description":"Locked until. Field in the JSON request body.\n\n**Details:** Type `string`, format `date-time` · Nullable."},"minutes_remaining":{"type":"integer","description":"Minutes remaining. Field in the JSON request body.\n\n**Details:** Type `integer`."},"failed_count":{"type":"integer","description":"Codes that matched nothing in the current window.\n\n**Details:** Type `integer`."},"window_started_at":{"type":["string","null"],"format":"date-time","description":"Window started at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"last_failed_at":{"type":["string","null"],"format":"date-time","description":"Last failed at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"locked_at":{"type":["string","null"],"format":"date-time","description":"Locked at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"lock_count":{"type":"integer","description":"Times the machine has been locked (lifetime).\n\n**Details:** Type `integer`."},"unlocked_by":{"type":["integer","null"],"description":"Unlocked by. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"unlocked_at":{"type":["string","null"],"format":"date-time","description":"Unlocked at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"actionable":{"type":"boolean","description":"Whether the caller may unlock (re-checked on unlock).\n\n**Details:** Type `boolean`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."}}}}}},"403":{"description":"No smart locker management permission, or the machine belongs to another business (the two are indistinguishable).","content":{"application/json":{"example":{"success":false,"message":"You are not allowed to unlock this machine."}}}},"422":{"description":"Invalid input, or the machine is not locked and has nothing to reset.","content":{"application/json":{"example":{"success":false,"message":"This machine is not locked."}}}}}}},"/v1/warehouse-mobile/carrier-receive":{"post":{"tags":["Warehouse Mobile"],"summary":"Receive one pre-advised carrier package","description":"Records the handover of a pre-advised carrier package at an authorized warehouse, matched by carrier tracking number or member number. The package is not moved: its staging row keeps naming the destination the carrier gave, so shelving at that location is unchanged. Optional carrier_id narrows the match. A code that is a member number is refused with code carrier_required (422) until carrier_id is given: a member number identifies a parcel only within its carrier.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["warehouse_id","search"],"properties":{"warehouse_id":{"type":"integer","description":"**Required.**\n\nWarehouse id used as the location / stock context.\n\n**Details:** Type `integer`.\n\n**Example:** `276`.","examples":[276]},"search":{"type":"string","description":"**Required.**\n\nCarrier tracking number or member number\n\n**Details:** Type `string`.\n\n**Example:** `1Z999AA10123456784`.","examples":["1Z999AA10123456784"]},"carrier_id":{"type":["integer","null"],"description":"Carrier id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `12`.","examples":[12]},"operation_id":{"type":"string","format":"uuid","description":"Operation id. Identifier referencing the related record.\n\n**Details:** Type `string`, format `uuid`.\n\n**Example:** `6ba7b810-9dad-11d1-80b4-00c04fd430c8`.","examples":["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]}}}}}},"responses":{"200":{"description":"Package received, or already received (code already_received)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Carrier package received.","data":{"outcome":"received","package":{"inventory_id":501,"package_no":"12-77","carrier_name":"Test Carrier","carrier_reference_number":"1Z999AA10123456784","member_number":null,"destination_id":703,"destination_name":"Point A","received_warehouse_id":276,"received_at":"2026-09-20 09:00:00"},"matches":null,"pending_total":3,"duplicate":false}}}}},"403":{"description":"Receive capability denied"},"404":{"description":"No pre-advised package matches"},"409":{"description":"Ambiguous match, or the carrier does not hand over at this warehouse"},"422":{"description":"Validation error, or the code is a member number and carrier_id was not given (code carrier_required)"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/carriers":{"get":{"tags":["Warehouse Mobile"],"summary":"List the carriers of the business","description":"Active carriers, for the optional filter on the carrier receive screen.","parameters":[{"name":"warehouse_id","in":"query","required":true,"schema":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."},"description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Carriers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Carriers are ready.","data":{"carriers":[{"id":12,"name":"Test Carrier","has_member_number":true,"has_tracking_number":true}]}}}}},"403":{"description":"Warehouse access denied"},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/distribution/pending":{"get":{"tags":["Warehouse Mobile"],"summary":"Distribution page of a warehouse","description":"Pre-advised carrier packages received at the warehouse and not yet placed on a distribution order, grouped by the destination the carrier named, plus the open distribution orders that left from it (docs/CARRIER-PACKAGE-DISTRIBUTION-DESIGN.md).","parameters":[{"name":"warehouse_id","in":"query","required":true,"schema":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."},"description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Pending destinations and open orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Distribution list is ready.","data":{"warehouse":{"id":276,"name":"Central"},"pending":[{"destination_id":703,"destination_name":"Point A","destination_address":"1 A St, Town, A1A 1A1","lat":45.5,"lng":-73.5,"count":2,"packages":[{"inventory_id":501,"package_no":"12-77","carrier_name":"Test Carrier","carrier_reference_number":"1Z999AA10123456784","received_at":"2026-09-20 09:00:00"}]}],"orders":[{"order_id":9001,"ref":"DIST-276-705-20260920-1","status":"pending_route","sealed":false,"destination_id":705,"destination_name":"Point B","counts":{"expected":1,"loaded":0,"delivered":0,"shelved":0},"route":null}]}}}}},"403":{"description":"Ship capability denied"},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/distribution/generate":{"post":{"tags":["Warehouse Mobile"],"summary":"Generate distribution orders","description":"One ordinary delivery order per selected destination, addressed to that destination, with one package row per parcel (the carrier barcode as tracking number). Orders enter the normal planning pool with today's date. A destination with nothing left to distribute is reported under skipped (code nothing_generated when none was created).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["warehouse_id","destination_ids"],"properties":{"warehouse_id":{"type":"integer","description":"**Required.**\n\nWarehouse id used as the location / stock context.\n\n**Details:** Type `integer`.\n\n**Example:** `276`.","examples":[276]},"destination_ids":{"type":"array","items":{"type":"integer","description":"Destination ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nDestination ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`.","examples":[[703,705]]},"operation_id":{"type":"string","format":"uuid","description":"Operation id. Identifier referencing the related record.\n\n**Details:** Type `string`, format `uuid`."}}}}}},"responses":{"200":{"description":"Generated orders and skipped destinations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Distribution orders generated.","data":{"orders":[{"order_id":9002,"ref":"DIST-276-703-20260920-1","status":"pending_route","destination_id":703,"destination_name":"Point A","counts":{"expected":2,"loaded":0,"delivered":0,"shelved":0}}],"skipped":[{"destination_id":705,"reason":"nothing_to_distribute"}]}}}}},"403":{"description":"Ship capability denied"},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/distribution/{order}":{"get":{"tags":["Warehouse Mobile"],"summary":"One distribution order","description":"A distribution order that left from the warehouse: derived status, reconciliation counts (expected, loaded, delivered, shelved), route and packages.","parameters":[{"name":"order","in":"path","required":true,"schema":{"type":"integer","description":"Sort direction: typically `asc` or `desc`.\n\n**Details:** Required · Type `integer`."},"description":"Sort direction: typically `asc` or `desc`.\n\n**Details:** Required · Type `integer`."},{"name":"warehouse_id","in":"query","required":true,"schema":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."},"description":"Warehouse id used as the location / stock context.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Distribution order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Distribution order is ready.","data":{"order_id":9002,"ref":"DIST-276-703-20260920-1","status":"routed","sealed":true,"destination_name":"Point A","route":{"id":55,"name":"R-55","date":"2026-09-20","drivers":["Alex"]},"counts":{"expected":2,"loaded":1,"delivered":0,"shelved":0},"items":[{"id":1,"inventory_id":501,"package_id":7001,"package_no":"12-77","carrier_name":"Test Carrier","carrier_reference_number":"1Z999AA10123456784","loaded_at":"2026-09-20 10:12:00","delivered_at":null,"shelved_at":null,"active":true,"overdue":false}]}}}}},"403":{"description":"Ship capability denied"},"404":{"description":"Not a distribution order of this warehouse"},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/driver/bootstrap":{"get":{"tags":["Warehouse Mobile"],"summary":"Driver mode bootstrap","description":"For a driver account: the distribution orders of pre-advised carrier packages the driver carried that are out for delivery or delivered within the shelving window, each with its destination, route and reconciliation counts. A driver has no warehouse list; the right to shelve at a location is derived from these orders (docs/CARRIER-PACKAGE-DISTRIBUTION-DESIGN.md §5.6).","responses":{"200":{"description":"Driver mode data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Driver mode is ready.","data":{"api_version":"1.0","user":{"id":77,"name":"Alex","email":"alex@example.com","group":"driver"},"driver_id":7,"shelving_window_days":2,"distribution_orders":[{"order_id":9002,"ref":"DIST-276-703-20260920-1","status":"delivered","destination_id":703,"destination_name":"Point A","counts":{"expected":2,"loaded":2,"delivered":2,"shelved":0},"route":{"id":55,"name":"R-55","date":"2026-09-20","drivers":["Alex"]},"items":[]}]}}}}},"401":{"description":"Not a driver, client or admin token"},"403":{"description":"Not a driver account"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/driver/locker/resolve":{"post":{"tags":["Warehouse Mobile"],"summary":"Resolve a cabinet code for a driver","description":"Turns the management code shown on a smart locker's screen into the device id the stock-in flow drives, for a driver who carried a distribution order to that location. No management session is opened; a driver manages nothing. The locker operator endpoints then accept the driver for the parcels of those orders only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"**Required.**\n\nStable machine code for this resource.\n\n**Details:** Type `string`.\n\n**Example:** `slm1|31|1758380000.abc123`.","examples":["slm1|31|1758380000.abc123"]}}}}}},"responses":{"200":{"description":"Cabinet the driver may shelve at","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Cabinet recognised. Scan the parcels to shelve them.","data":{"device_id":"SL-0001","shelf_id":31,"shelf_code":"L-1","warehouse_id":703,"warehouse_name":"Point A","pending_count":2}}}}},"403":{"description":"Not a driver, or no distribution order to shelve at this location"},"404":{"description":"Code invalid, expired or another business's cabinet"},"422":{"description":"Validation error"}},"security":[{"bearerAuth":[]}]}},"/v1/warehouse-mobile/driver/locker/take-out":{"post":{"operationId":"driverLockerTakeOut","tags":["Warehouse Mobile"],"summary":"Take a relayed bag out of a cabinet (driver)","description":"Luggage relay (docs/LUGGAGE-LOGISTICS-DESIGN.md D8): the driver holding a relay's out order opens the bag's compartment at the cabinet and takes it out for the hub. The storage rental becomes relayed, the renter is told that staff are keeping the bag, and the renter's code stays valid. The cabinet and relay come from the driver locker resolve (relay_take_outs). The right to open the door is derived from the order the driver carries, never configured.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_id","relay_id"],"properties":{"device_id":{"type":"string","description":"**Required.**\n\nStable device identifier from the mobile / kiosk client.\n\n**Details:** Type `string`.\n\n**Example:** `SL-0001`.","examples":["SL-0001"]},"relay_id":{"type":"integer","description":"**Required.**\n\nRelay id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `12`.","examples":[12]}}}}}},"responses":{"200":{"description":"The compartment opened and the bag is recorded as taken out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseMobileEnvelope"},"example":{"result":true,"code":"ok","message":"Bag taken out. It travels to the hub on the pickup order.","data":{"relay_id":12,"rental_id":3401,"grid_id":88,"compartment_number":"B07","taken":true,"failed":[]}}}}},"403":{"description":"Not a driver, or the driver does not hold this relay's out order"},"404":{"description":"Unknown cabinet, or another business's"},"409":{"description":"The bag is not in a compartment of this cabinet"},"422":{"description":"Validation error"},"502":{"description":"The cabinet did not open"}},"security":[{"bearerAuth":[]}]}},"/v1/documents/verify":{"post":{"operationId":"documentsVerify","tags":["Documents"],"summary":"Verify a PDF fingerprint","description":"Check whether a PDF was issued by this system and whether it is intact. Every PDF the system issues or stores (shipping labels, carrier labels, invoices, PODs, manifests, merged batch files) carries an encrypted fingerprint inside the file itself; no registry is consulted. status: authentic = issued by us and unmodified; tampered = issued by us, modified since; unknown = no fingerprint of ours (not issued by us, issued before fingerprinting started, or re-saved by another program); not_pdf. document is returned only when the caller may see it (own business, the label-service customer of the order, or admin); otherwise visible=false and document=null.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The PDF to check\n\n**Details:** Type `string`, format `binary`."}}}},"application/json":{"schema":{"type":"object","properties":{"file_base64":{"type":"string","description":"Base64-encoded PDF (used when no multipart file is sent)\n\n**Details:** Type `string`."}}},"example":{"file_base64":"JVBERi0xLjQK..."}}}},"responses":{"200":{"description":"Verdict","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"data":{"type":"object","properties":{"status":{"type":"string","enum":["authentic","tampered","unknown","not_pdf"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `authentic` · `tampered` · `unknown` · `not_pdf`.\n\n**Details:** Type `string`."},"issued_by_us":{"type":"boolean","description":"Issued by us. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"intact":{"type":"boolean","description":"Intact. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"visible":{"type":"boolean","description":"Visible. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"document":{"type":["object","null"],"properties":{"document_type":{"type":["string","null"],"description":"Internal document type (view or sealer name)\n\n**Details:** Type `string` · Nullable."},"document_type_label":{"type":"string","description":"Document type in the caller's language\n\n**Details:** Type `string`."},"source":{"type":"string","enum":["generated","stored","merged"],"description":"Document or data source selector for this developer-center export.\n\nAllowed values: `generated` · `stored` · `merged`.\n\n**Details:** Type `string`."},"documentable_type":{"type":["string","null"],"description":"orders, storage_orders, moving_orders, shipping_orders, return_requests, invoices, manifest, ...\n\n**Details:** Type `string` · Nullable."},"documentable_id":{"type":["integer","null"],"description":"Documentable id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"issued_at":{"type":["string","null"],"format":"date-time","description":"Issue time in the caller's timezone (ISO 8601)\n\n**Details:** Type `string`, format `date-time` · Nullable."},"issued_at_display":{"type":["string","null"],"description":"Issue time in the caller's timezone, Y-m-d H:i:s with the zone abbreviation\n\n**Details:** Type `string` · Nullable."},"original_sha256":{"type":"string","description":"SHA-256 of the file as it was before the fingerprint was added\n\n**Details:** Type `string`."},"original_byte_size":{"type":"integer","description":"Original byte size. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Document. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"data":{"status":"tampered","issued_by_us":true,"intact":false,"visible":true,"document":{"document_type":"orders.shippinglabelpdf","document_type_label":"Shipping label","source":"generated","documentable_type":"orders","documentable_id":1488150,"issued_at":"2026-09-22T10:15:00-04:00","issued_at_display":"2026-09-22 10:15:00 EDT","original_sha256":"9f2b...","original_byte_size":48213}}}}}},"400":{"description":"No file, or invalid base64","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":false,"message":"A PDF is required in file or file_base64."}}}},"401":{"description":"Unauthenticated"},"413":{"description":"File exceeds the size limit (20 MB by default)","content":{"application/json":{"example":{"result":false,"message":"The file exceeds the size limit."}}}}},"security":[{"bearerAuth":[]}]}},"/v1/fleets":{"get":{"tags":["Fleets"],"summary":"List fleets","description":"Fleets of the business with owner, code, captain and driver count. An owner sees the fleets it manages (a contractor only its own); a Fleet Captain employee sees the fleets he leads. Mirrored by GraphQL fleets. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"query","name":"owner_user_id","required":false,"schema":{"type":"integer","description":"Only this owner: 0 for the client's own, else the contractor's user id (ignored for contractor accounts)\n\n**Details:** Optional · Type `integer`."},"description":"Only this owner: 0 for the client's own, else the contractor's user id (ignored for contractor accounts)\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"status","required":false,"schema":{"type":"integer","enum":[0,1],"description":"1 active, 0 closed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"description":"1 active, 0 closed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"page","required":false,"schema":{"type":"integer","description":"Page number, from 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Page number, from 1\n\nPage number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","description":"Rows per page, 1-200 (default 50)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"Rows per page, 1-200 (default 50)\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"Fleets","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"page":{"type":"integer","description":"Page number for paginated results (1-based).\n\n**Details:** Type `integer`."},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`."},"fleets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"owner_user_id":{"type":"integer","description":"0 for the client's own fleet, else the contractor's user id\n\n**Details:** Type `integer`."},"owner_type":{"type":"string","enum":["own","contractor"],"description":"Allowed values: `own` · `contractor`.\n\n**Details:** Type `string`."},"owner_name":{"type":["string","null"],"description":"Owner name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"code":{"type":["string","null"],"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable."},"captain_user_id":{"type":["integer","null"],"description":"Captain user id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"captain_name":{"type":["string","null"],"description":"Captain name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"captain_type":{"type":["string","null"],"enum":["driver","employee",null],"description":"Allowed values: `driver` · `employee`.\n\n**Details:** Type `string` · Nullable."},"drivers_count":{"type":["integer","null"],"description":"Drivers count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"status":{"type":"integer","description":"1 active, 0 closed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."}}},"description":"Fleets. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"total":1,"page":1,"per_page":50,"fleets":[{"id":12,"owner_user_id":0,"owner_type":"own","owner_name":null,"name":"North","code":"NTH","captain_user_id":3850,"captain_name":"Bob Lee","captain_type":"driver","drivers_count":6,"status":1,"sort_order":0}]}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"503":{"description":"The fleets migration has not run yet","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}},"post":{"tags":["Fleets"],"summary":"Create a fleet","description":"Creates a fleet under an owner: the client itself (owner_user_id 0) or one of its contractors. A contractor account always creates under itself. The code is optional, carries no spaces and is unique across the business's fleets. Mirrored by GraphQL createFleet. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"owner_user_id":{"type":"integer","description":"0 for the client's own fleet, else the contractor's user id\n\n**Details:** Type `integer`."},"name":{"type":"string","maxLength":100,"description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string` · maxLength `100`."},"code":{"type":["string","null"],"maxLength":50,"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable · maxLength `50`."},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."}}},"example":{"owner_user_id":0,"name":"North","code":"NTH"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"fleet":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"owner_user_id":{"type":"integer","description":"0 for the client's own fleet, else the contractor's user id\n\n**Details:** Type `integer`."},"owner_type":{"type":"string","enum":["own","contractor"],"description":"Allowed values: `own` · `contractor`.\n\n**Details:** Type `string`."},"owner_name":{"type":["string","null"],"description":"Owner name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"code":{"type":["string","null"],"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable."},"captain_user_id":{"type":["integer","null"],"description":"Captain user id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"captain_name":{"type":["string","null"],"description":"Captain name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"captain_type":{"type":["string","null"],"enum":["driver","employee",null],"description":"Allowed values: `driver` · `employee`.\n\n**Details:** Type `string` · Nullable."},"drivers_count":{"type":["integer","null"],"description":"Drivers count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"status":{"type":"integer","description":"1 active, 0 closed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Fleet. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"message":"Fleet saved.","fleet":{"id":12,"owner_user_id":0,"owner_type":"own","owner_name":null,"name":"North","code":"NTH","captain_user_id":3850,"captain_name":"Bob Lee","captain_type":"driver","drivers_count":6,"status":1,"sort_order":0}}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"422":{"description":"Invalid name, code or owner","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/fleets/{id}":{"put":{"tags":["Fleets"],"summary":"Update a fleet","description":"Rename, re-code, re-order or close/reopen a fleet. A fleet with drivers or capacity rows cannot be closed. Owners only. Mirrored by GraphQL updateFleet. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"name":{"type":"string","maxLength":100,"description":"Human-readable name.\n\n**Details:** Type `string` · maxLength `100`."},"code":{"type":["string","null"],"maxLength":50,"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable · maxLength `50`."},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."},"status":{"type":"integer","enum":[0,1],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]}}},"example":{"name":"North East","code":"NE"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"fleet":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"owner_user_id":{"type":"integer","description":"0 for the client's own fleet, else the contractor's user id\n\n**Details:** Type `integer`."},"owner_type":{"type":"string","enum":["own","contractor"],"description":"Allowed values: `own` · `contractor`.\n\n**Details:** Type `string`."},"owner_name":{"type":["string","null"],"description":"Owner name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"code":{"type":["string","null"],"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable."},"captain_user_id":{"type":["integer","null"],"description":"Captain user id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"captain_name":{"type":["string","null"],"description":"Captain name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"captain_type":{"type":["string","null"],"enum":["driver","employee",null],"description":"Allowed values: `driver` · `employee`.\n\n**Details:** Type `string` · Nullable."},"drivers_count":{"type":["integer","null"],"description":"Drivers count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"status":{"type":"integer","description":"1 active, 0 closed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Fleet. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"message":"Fleet saved.","fleet":{"id":12,"owner_user_id":0,"owner_type":"own","owner_name":null,"name":"North","code":"NTH","captain_user_id":3850,"captain_name":"Bob Lee","captain_type":"driver","drivers_count":6,"status":1,"sort_order":0}}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"422":{"description":"Invalid name, code or status","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}},"delete":{"tags":["Fleets"],"summary":"Delete a fleet","description":"Deletes a fleet that has no drivers and no capacity rows. Owners only. Mirrored by GraphQL deleteFleet. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Fleet deleted."}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"422":{"description":"The fleet still has drivers or capacity rows","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/fleets/{id}/members":{"get":{"tags":["Fleets"],"summary":"List a fleet's drivers","description":"The fleet's drivers with their work window, duty and whether they are the captain, plus (for an owner) the drivers of the same owner that could still be added. Mirrored by GraphQL fleetMembers. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"Members","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"fleet":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"owner_user_id":{"type":"integer","description":"0 for the client's own fleet, else the contractor's user id\n\n**Details:** Type `integer`."},"owner_type":{"type":"string","enum":["own","contractor"],"description":"Allowed values: `own` · `contractor`.\n\n**Details:** Type `string`."},"owner_name":{"type":["string","null"],"description":"Owner name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"code":{"type":["string","null"],"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable."},"captain_user_id":{"type":["integer","null"],"description":"Captain user id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"captain_name":{"type":["string","null"],"description":"Captain name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"captain_type":{"type":["string","null"],"enum":["driver","employee",null],"description":"Allowed values: `driver` · `employee`.\n\n**Details:** Type `string` · Nullable."},"drivers_count":{"type":["integer","null"],"description":"Drivers count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"status":{"type":"integer","description":"1 active, 0 closed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Fleet. Field in the JSON request body.\n\n**Details:** Type `object`."},"manages":{"type":"boolean","description":"Manages. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"members":{"type":"array","items":{"type":"object","properties":{"driver_id":{"type":"integer","description":"Driver id.\n\n**Details:** Type `integer`."},"user_id":{"type":"integer","description":"User id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"alias":{"type":["string","null"],"description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"status":{"type":"integer","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"work_to":{"type":["string","null"],"description":"Work to. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"on_duty":{"type":["boolean","null"],"description":"On duty. Field in the JSON request body.\n\n**Details:** Type `boolean` · Nullable."},"is_captain":{"type":"boolean","description":"Is captain. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."}}},"description":"Members. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."},"addable":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"alias":{"type":["string","null"],"description":"Alias. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}},"description":"Addable. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"fleet":{"id":12,"owner_user_id":0,"owner_type":"own","owner_name":null,"name":"North","code":"NTH","captain_user_id":3850,"captain_name":"Bob Lee","captain_type":"driver","drivers_count":6,"status":1,"sort_order":0},"manages":true,"members":[{"driver_id":565,"user_id":3850,"name":"Bob Lee","alias":"BL","email":"bob@example.com","status":1,"work_from":"08:00","work_to":"17:00","on_duty":true,"is_captain":true}],"addable":[{"id":566,"name":"Adnan K","alias":"AK"}]}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}},"post":{"tags":["Fleets"],"summary":"Add drivers to a fleet","description":"Puts drivers into the fleet. Each must belong to the fleet's owner and be in no fleet yet; a driver is in at most one fleet. Owners only. Mirrored by GraphQL addFleetMembers. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["driver_ids"],"properties":{"driver_ids":{"type":"array","items":{"type":"integer","description":"Driver ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nDriver ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."}}},"example":{"driver_ids":[565,566]}}}},"responses":{"200":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"added":{"type":"integer","description":"Added. Field in the JSON request body.\n\n**Details:** Type `integer`."}}},"example":{"result":true,"message":"2 driver(s) added.","added":2}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"422":{"description":"A driver is of another owner or already in a fleet","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}},"delete":{"tags":["Fleets"],"summary":"Remove drivers from a fleet","description":"Takes drivers out of the fleet, back under the owner directly. The fleet's captain stays until the captaincy is handed on. Owners only. Mirrored by GraphQL removeFleetMembers. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["driver_ids"],"properties":{"driver_ids":{"type":"array","items":{"type":"integer","description":"Driver ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nDriver ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."}}},"example":{"driver_ids":[566]}}}},"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"removed":{"type":"integer","description":"Removed. Field in the JSON request body.\n\n**Details:** Type `integer`."}}},"example":{"result":true,"message":"1 driver(s) removed.","removed":1}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"422":{"description":"The captain cannot be removed","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/fleets/{id}/captain":{"post":{"tags":["Fleets"],"summary":"Set a fleet's captain","description":"Names the captain: a driver of the fleet's owner (a driver in no fleet joins this one) or an employee of the company (owned by the client, or by this fleet's contractor). Send no captain_user_id, or 0, to clear. Owners only. Mirrored by GraphQL setFleetCaptain. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"captain_user_id":{"type":["integer","null"],"description":"Captain user id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."}}},"example":{"captain_user_id":3850}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"fleet":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"owner_user_id":{"type":"integer","description":"0 for the client's own fleet, else the contractor's user id\n\n**Details:** Type `integer`."},"owner_type":{"type":"string","enum":["own","contractor"],"description":"Allowed values: `own` · `contractor`.\n\n**Details:** Type `string`."},"owner_name":{"type":["string","null"],"description":"Owner name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"code":{"type":["string","null"],"description":"Stable machine code for this resource.\n\n**Details:** Type `string` · Nullable."},"captain_user_id":{"type":["integer","null"],"description":"Captain user id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"captain_name":{"type":["string","null"],"description":"Captain name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"captain_type":{"type":["string","null"],"enum":["driver","employee",null],"description":"Allowed values: `driver` · `employee`.\n\n**Details:** Type `string` · Nullable."},"drivers_count":{"type":["integer","null"],"description":"Drivers count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer` · Nullable."},"status":{"type":"integer","description":"1 active, 0 closed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`."},"sort_order":{"type":"integer","description":"Sort order. Field in the JSON request body.\n\n**Details:** Type `integer`."}},"description":"Fleet. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"message":"Captain saved.","fleet":{"id":12,"owner_user_id":0,"owner_type":"own","owner_name":null,"name":"North","code":"NTH","captain_user_id":3850,"captain_name":"Bob Lee","captain_type":"driver","drivers_count":6,"status":1,"sort_order":0}}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"422":{"description":"The captain is not of this owner or is in another fleet he does not lead","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/fleets/{id}/shifts":{"get":{"tags":["Fleets"],"summary":"A week of the fleet shift calendar","description":"Seven dates from the Monday of the requested week, and for each driver of the fleet the resolved day (a dated exception, then the weekly pattern, then the driver's own window) plus the raw weekly pattern. The owner and the captain may edit (can_edit). Mirrored by GraphQL fleetShifts. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},{"in":"query","name":"week","required":false,"schema":{"type":"string","format":"date","description":"Any date of the wanted week (default this week)\n\n**Details:** Optional · Type `string`, format `date`."},"description":"Any date of the wanted week (default this week)\n\n**Details:** Optional · Type `string`, format `date`."}],"responses":{"200":{"description":"Week","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"fleet_id":{"type":"integer","description":"Fleet id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"dates":{"type":"array","items":{"type":"string","description":"Dates. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Dates. Field in the JSON request body.\n\n**Details:** Type `array`, items `string`."},"can_edit":{"type":"boolean","description":"Can edit. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"drivers":{"type":"array","items":{"type":"object","properties":{"driver_id":{"type":"integer","description":"Driver id.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"weekly":{"type":"object","description":"Keyed 1-7 (Monday-Sunday): {is_off, work_from, work_to}\n\n**Details:** Type `object`."},"days":{"type":"object","description":"Keyed by date\n\n**Details:** Type `object`.","additionalProperties":{"type":"object","properties":{"off":{"type":"boolean","description":"Off. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"work_to":{"type":["string","null"],"description":"Work to. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."},"source":{"type":"string","enum":["exception","weekly","driver"],"description":"Document or data source selector for this developer-center export.\n\nAllowed values: `exception` · `weekly` · `driver`.\n\n**Details:** Type `string`."}},"description":"Days. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."}}}},"description":"Drivers. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"example":{"result":true,"fleet_id":12,"dates":["2026-10-05","2026-10-06","2026-10-07","2026-10-08","2026-10-09","2026-10-10","2026-10-11"],"can_edit":true,"drivers":[{"driver_id":565,"name":"Bob Lee","weekly":{"6":{"is_off":true,"work_from":null,"work_to":null}},"days":{"2026-10-05":{"off":false,"work_from":"08:00","work_to":"17:00","reason":null,"source":"weekly"},"2026-10-10":{"off":true,"work_from":null,"work_to":null,"reason":null,"source":"weekly"}}}]}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/fleets/{id}/shifts/weekly":{"post":{"tags":["Fleets"],"summary":"Replace a driver's weekly shift pattern","description":"Replaces the weekly pattern of one driver of the fleet. days is keyed 1-7 (Monday-Sunday); a weekday absent, or with neither is_off nor a window, keeps the driver's own work window. The fleet's owner or captain. Mirrored by GraphQL saveFleetWeeklyShift. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["driver_id"],"properties":{"driver_id":{"type":"integer","description":"**Required.**\n\nDriver id.\n\n**Details:** Type `integer`."},"days":{"type":"object","additionalProperties":{"type":"object","properties":{"is_off":{"type":"boolean","description":"Is off. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"work_from":{"type":"string","description":"HH:MM\n\n**Details:** Type `string`."},"work_to":{"type":"string","description":"HH:MM\n\n**Details:** Type `string`."}},"description":"Days. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Days. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"driver_id":565,"days":{"1":{"work_from":"07:00","work_to":"15:00"},"6":{"is_off":true},"7":{"is_off":true}}}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}},"example":{"result":true,"message":"Calendar saved."}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet or driver not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"422":{"description":"A time is not HH:MM","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/fleets/{id}/shifts/exception":{"post":{"tags":["Fleets"],"summary":"Set what a driver does on one date","description":"A dated exception: the driver is off that day (action off), or works that day in the given window (action work; a missing time falls back to the weekly pattern, then the driver's own window). Saving the same date again replaces it. The fleet's owner or captain. Mirrored by GraphQL saveFleetShiftException. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["driver_id","local_date","action"],"properties":{"driver_id":{"type":"integer","description":"**Required.**\n\nDriver id.\n\n**Details:** Type `integer`."},"local_date":{"type":"string","format":"date","description":"**Required.**\n\nLocal date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date`."},"action":{"type":"string","enum":["off","work"],"description":"**Required.**\n\nAllowed values: `off` · `work`.\n\n**Details:** Type `string`."},"work_from":{"type":"string","description":"HH:MM\n\n**Details:** Type `string`."},"work_to":{"type":"string","description":"HH:MM\n\n**Details:** Type `string`."},"reason":{"type":"string","maxLength":120,"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · maxLength `120`."}}},"example":{"driver_id":565,"local_date":"2026-10-06","action":"off","reason":"Sick"}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"day":{"type":"object","properties":{"off":{"type":"boolean","description":"Off. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"work_to":{"type":["string","null"],"description":"Work to. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."},"source":{"type":"string","enum":["exception","weekly","driver"],"description":"Document or data source selector for this developer-center export.\n\nAllowed values: `exception` · `weekly` · `driver`.\n\n**Details:** Type `string`."}},"description":"Day. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"example":{"result":true,"message":"Calendar saved.","day":{"off":true,"work_from":null,"work_to":null,"reason":"Sick","source":"exception"}}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet or driver not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"422":{"description":"Invalid date, action or time","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}},"delete":{"tags":["Fleets"],"summary":"Remove a dated exception","description":"Removes the exception on that date so the weekly pattern, then the driver's own window, speaks again. The fleet's owner or captain. Mirrored by GraphQL clearFleetShiftException. Client and employee accounts; a contractor manages only the fleets it owns and a Fleet Captain employee reads the fleets he leads and keeps their calendar (docs/FLEET-CAPTAIN-DESIGN.md).","parameters":[{"in":"path","name":"id","schema":{"type":"integer","description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"required":true,"description":"The fleet\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["driver_id","local_date"],"properties":{"driver_id":{"type":"integer","description":"**Required.**\n\nDriver id.\n\n**Details:** Type `integer`."},"local_date":{"type":"string","format":"date","description":"**Required.**\n\nLocal date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`, format `date`."}}},"example":{"driver_id":565,"local_date":"2026-10-06"}}}},"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"removed":{"type":"integer","description":"Removed. Field in the JSON request body.\n\n**Details:** Type `integer`."},"day":{"type":["object","null"],"properties":{"off":{"type":"boolean","description":"Off. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"work_from":{"type":["string","null"],"description":"Work from. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"work_to":{"type":["string","null"],"description":"Work to. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."},"source":{"type":"string","enum":["exception","weekly","driver"],"description":"Document or data source selector for this developer-center export.\n\nAllowed values: `exception` · `weekly` · `driver`.\n\n**Details:** Type `string`."}},"description":"Day. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."}}},"example":{"result":true,"message":"Calendar saved.","removed":1,"day":{"off":false,"work_from":"08:00","work_to":"17:00","reason":null,"source":"weekly"}}}}},"403":{"description":"Not authorised","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}},"404":{"description":"Fleet or driver not found","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`.","examples":[false]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."}}}}}}}}},"/v1/luggage/relays/{id}/onward-quote":{"post":{"operationId":"quoteLuggageRelayOnward","tags":["Luggage Relay"],"summary":"Price own delivery and carrier shipment of a relayed bag to an address","description":"Price the renter's onward choices for an address before choosing one: delivery by the operator's own drivers (own_delivery: offered, fee) and shipment by a carrier (shipment: one option per carrier service, cheapest first, priced for the weight band given in weight_tier_kg from the operator's price list or the carriers' live rates with markup). A read: nothing is chosen until POST /v1/luggage/relays/{id}/return with shipment. When weight_tier_kg is missing, shipment.reason is weight_tier_required and shipment.weight_tiers_kg lists the bands to choose from. Refused with 409 once the relay is closed. Each option carries channel: label (one of the operator's shipping methods, a carrier label bought at shipping) or courier (one of the operator's own Shipping Services, priced by that service's plan and fulfilled as a shipping order). Both appear in one list, cheapest first.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Relay id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Relay id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"object","description":"**Required.**\n\nDestination: name, telephone, address_1, address_2, city, province, country, postcode, lat, lng, note. postcode is required for a price.\n\n**Details:** Type `object`.","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Grand Hotel reception`.","examples":["Grand Hotel reception"]},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`.\n\n**Example:** `100 King St W`.","examples":["100 King St W"]},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`.\n\n**Example:** `Toronto`.","examples":["Toronto"]},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`.","examples":["ON"]},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `M5X 1A9`.","examples":["M5X 1A9"]}}},"weight_tier_kg":{"type":"integer","description":"The weight band the bag fits in (one of shipment.weight_tiers_kg). Without it only own delivery is priced.\n\n**Details:** Type `integer`.\n\n**Example:** `10`.","examples":[10]},"weight_kg":{"type":"number","description":"Declared weight in kg (optional). Given, the weight band is the smallest one it fits and couriers are priced on it.\n\n**Details:** Type `number`.\n\n**Example:** `8.5`.","examples":[8.5]},"dimensions_cm":{"type":"object","description":"Declared dimensions in cm, {length, width, height} (optional). Given, carriers and couriers are priced on them instead of the compartment's size.\n\n**Details:** Type `object`.","properties":{"length":{"type":"number","description":"Length dimension.\n\n**Details:** Type `number`.\n\n**Example:** `70`.","examples":[70]},"width":{"type":"number","description":"Width dimension.\n\n**Details:** Type `number`.\n\n**Example:** `45`.","examples":[45]},"height":{"type":"number","description":"Height dimension.\n\n**Details:** Type `number`.\n\n**Example:** `30`.","examples":[30]}}}}},"example":{"address":{"name":"Grand Hotel reception","address_1":"100 King St W","city":"Toronto","province":"ON","country":"CA","postcode":"M5X 1A9"},"weight_kg":8.5,"dimensions_cm":{"length":70,"width":45,"height":30}}}}},"responses":{"200":{"description":"prices","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"own_delivery":{"available":true,"reason":null,"fee":12,"currency":"CAD","mode":"flat"},"shipment":{"available":true,"reason":null,"mode":"markup","currency":"CAD","weight_tier_kg":10,"weight_tiers_kg":[5,10,20,32],"options":[{"key":"s601","mode":"courier","channel":"courier","carrier":null,"service":"City Courier","service_code":"CITY","transit_days":null,"price":18.5,"currency":"CAD"},{"key":"m12:DOM.EP","mode":"markup","carrier":"Canada Post","service":"Expedited Parcel","service_code":"DOM.EP","transit_days":2,"price":24.5,"currency":"CAD","channel":"label"},{"key":"m12:DOM.XP","mode":"markup","carrier":"Canada Post","service":"Xpresspost","service_code":"DOM.XP","transit_days":1,"price":31,"currency":"CAD","channel":"label"}],"measure":{"weight_kg":8.5,"length_cm":70,"width_cm":45,"height_cm":30}}}}}},"401":{"description":"unauthenticated"},"404":{"description":"not found, or the luggage relay is not enabled for this business"},"409":{"description":"the relay is closed"},"422":{"description":"address missing"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals":{"get":{"tags":["Platform Apps"],"summary":"List the renter's stored luggage","description":"Bags the signed-in customer stored in the business's smart lockers, newest first. A rental is the customer's when it is bound to the account, or bound to nobody and stored under the account's e-mail or a verified phone number. scope=current lists bags still held (in a compartment or away with the operator), scope=past the rest. Each item carries its bill (amount so far, and how to pay it), its relay (where a bag away from its cabinet is) and any weight difference owed. No pickup code and no contact are returned; the compartment number only while the bag is in it. Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStorageRentals","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"scope","in":"query","required":false,"schema":{"type":"string","description":"current | past\n\n**Details:** Optional · Type `string`."},"description":"current | past\n\n**Details:** Optional · Type `string`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},"description":"Page number for paginated results (1-based).\n\n**Details:** Optional · Type `integer`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","description":"1–50, default 20\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."},"description":"1–50, default 20\n\nNumber of items returned per page.\n\n**Details:** Optional · Type `integer`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"items":[{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"}}],"pagination":{"current_page":1,"last_page":1,"per_page":20,"total":1,"has_more":false}}}}}},"403":{"description":"The app assignment or the locker.storage capability is not effective"},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/{id}":{"get":{"tags":["Platform Apps"],"summary":"Show one stored bag","description":"One of the renter's stored bags, with the choices open now under options: keep it during the warning window, collect at another cabinet (pickup_site), change the return cabinet or time while it is away, have it delivered, ship it, resend the code. Times are ISO 8601; timezone is the business's, in which times the renter types are read. Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStorageRental","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"},"options":{"keep":false,"warn_until":null,"pickup_site":{"choices":[],"fee":0,"cancellable":false},"return_site":{"changeable":false,"choices":[]},"return_time":{"changeable":true,"latest":"2026-10-08T17:40:00-04:00"},"delivery":{"available":false,"fee":null,"chosen":false,"paid":false,"default_country":"CA"},"shipment":{"available":false,"channels":["label","courier"],"weight_tiers_kg":[5,10,20,32],"tier_required":false,"chosen":true,"paid":false,"shipped":false},"resend_code":true},"timezone":"America/Toronto"}}}}},"404":{"description":"No stored bag with that id belongs to this customer","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"LOCKER_STORAGE_NOT_FOUND","message":"This stored item was not found."}}}},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/claim":{"post":{"tags":["Platform Apps"],"summary":"Add a stored bag by its code","description":"For a bag stored under a contact the account does not hold: the pickup code plus the last four digits of the phone it was stored under, or that whole e-mail. Binds the rental to the account; from then on a pickup at the cabinet is paid from the balance when it covers the bill. Every miss answers the same 404. Throttled to 5 requests a minute. Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStorageClaim","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","contact"],"properties":{"code":{"type":"string","maxLength":32,"description":"**Required.**\n\nStable machine code for this resource.\n\n**Details:** Type `string` · maxLength `32`."},"contact":{"type":"string","maxLength":191,"description":"**Required.**\n\nContact. Field in the JSON request body.\n\n**Details:** Type `string` · maxLength `191`."}}},"example":{"code":"K7Q2M9","contact":100}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"},"options":{"keep":false,"warn_until":null,"pickup_site":{"choices":[],"fee":0,"cancellable":false},"return_site":{"changeable":false,"choices":[]},"return_time":{"changeable":true,"latest":"2026-10-08T17:40:00-04:00"},"delivery":{"available":false,"fee":null,"chosen":false,"paid":false,"default_country":"CA"},"shipment":{"available":false,"channels":["label","courier"],"weight_tiers_kg":[5,10,20,32],"tier_required":false,"chosen":true,"paid":false,"shipped":false},"resend_code":true},"timezone":"America/Toronto"}}}}},"404":{"description":"The code and contact do not match a live stored bag of this business that is free to add","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"LOCKER_STORAGE_CODE_NOT_RECOGNISED","message":"The code and contact do not match a stored item."}}}},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/{id}/pickup-site":{"post":{"tags":["Platform Apps"],"summary":"Collect at another cabinet","description":"While the bag is in its compartment: collect it at one of options.pickup_site.choices instead (the operator carries it through its hub; options.pickup_site.fee is added to the bill, paid at pickup). While it is away and its return is not yet planned: bring it back to one of options.return_site.choices. Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStoragePickupSite","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["warehouse_id"],"properties":{"warehouse_id":{"type":"integer","description":"**Required.**\n\nWarehouse id used as the location / stock context.\n\n**Details:** Type `integer`."}}},"example":{"warehouse_id":701}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"Your luggage will be moved to the chosen cabinet. Your code stays the same.","data":{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"},"options":{"keep":false,"warn_until":null,"pickup_site":{"choices":[],"fee":0,"cancellable":false},"return_site":{"changeable":false,"choices":[]},"return_time":{"changeable":true,"latest":"2026-10-08T17:40:00-04:00"},"delivery":{"available":false,"fee":null,"chosen":false,"paid":false,"default_country":"CA"},"shipment":{"available":false,"channels":["label","courier"],"weight_tiers_kg":[5,10,20,32],"tier_required":false,"chosen":true,"paid":false,"shipped":false},"resend_code":true},"timezone":"America/Toronto"}}}}},"409":{"description":"Not a choice for this bag now","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"LOCKER_STORAGE_ACTION_UNAVAILABLE","message":"This action is not available right now."}}}},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/{id}/pickup-site/cancel":{"post":{"tags":["Platform Apps"],"summary":"Collect where the bag is after all","description":"Undo a pickup-site choice before the bag has left its compartment. Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStoragePickupSiteCancel","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"The move is cancelled. Collect your luggage where you left it.","data":{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"},"options":{"keep":false,"warn_until":null,"pickup_site":{"choices":[],"fee":0,"cancellable":false},"return_site":{"changeable":false,"choices":[]},"return_time":{"changeable":true,"latest":"2026-10-08T17:40:00-04:00"},"delivery":{"available":false,"fee":null,"chosen":false,"paid":false,"default_country":"CA"},"shipment":{"available":false,"channels":["label","courier"],"weight_tiers_kg":[5,10,20,32],"tier_required":false,"chosen":true,"paid":false,"shipped":false},"resend_code":true},"timezone":"America/Toronto"}}}}},"409":{"description":"The bag has already left, or no such choice was made","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"LOCKER_STORAGE_ACTION_UNAVAILABLE","message":"This action is not available right now."}}}},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/{id}/keep":{"post":{"tags":["Platform Apps"],"summary":"Keep the bag in its compartment","description":"Answers the warning sent before an operator rule moves a long-stored bag to the hub (options.keep is true until options.warn_until). Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStorageKeep","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"Your luggage stays in its compartment.","data":{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"},"options":{"keep":false,"warn_until":null,"pickup_site":{"choices":[],"fee":0,"cancellable":false},"return_site":{"changeable":false,"choices":[]},"return_time":{"changeable":true,"latest":"2026-10-08T17:40:00-04:00"},"delivery":{"available":false,"fee":null,"chosen":false,"paid":false,"default_country":"CA"},"shipment":{"available":false,"channels":["label","courier"],"weight_tiers_kg":[5,10,20,32],"tier_required":false,"chosen":true,"paid":false,"shipped":false},"resend_code":true},"timezone":"America/Toronto"}}}}},"409":{"description":"No warning is open for this bag","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"LOCKER_STORAGE_ACTION_UNAVAILABLE","message":"This action is not available right now."}}}},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/{id}/return-time":{"post":{"tags":["Platform Apps"],"summary":"Change when you come back","description":"For a bag that is away: when the renter will come back for it, in the business's local time (Y-m-d H:i), no later than options.return_time.latest. The return trip is re-planned to arrive before it. Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStorageReturnTime","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["return_at"],"properties":{"return_at":{"type":"string","description":"**Required.**\n\nReturn at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`.\n\n**Example:** `2026-09-28 14:00`.","examples":["2026-09-28 14:00"]}}},"example":{"return_at":"2026-09-28 14:00"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"Your return time has been changed.","data":{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"},"options":{"keep":false,"warn_until":null,"pickup_site":{"choices":[],"fee":0,"cancellable":false},"return_site":{"changeable":false,"choices":[]},"return_time":{"changeable":true,"latest":"2026-10-08T17:40:00-04:00"},"delivery":{"available":false,"fee":null,"chosen":false,"paid":false,"default_country":"CA"},"shipment":{"available":false,"channels":["label","courier"],"weight_tiers_kg":[5,10,20,32],"tier_required":false,"chosen":true,"paid":false,"shipped":false},"resend_code":true},"timezone":"America/Toronto"}}}}},"422":{"description":"Not a time"},"409":{"description":"Outside the allowed window, or the return is already on its way","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"LOCKER_STORAGE_ACTION_UNAVAILABLE","message":"This action is not available right now."}}}},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/{id}/onward-quote":{"post":{"tags":["Platform Apps"],"summary":"Price delivery and shipment to an address","description":"Reads only. own_delivery answers delivery by the operator's drivers (only inside its delivery area); shipment lists carrier label and courier options by price, for the weight band given or derived from weight_kg. A choice is made with /delivery or /shipment. Throttled to 20 requests a minute. Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStorageOnwardQuote","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."}},"description":"**Required.**\n\nAddress. Address component used for geocoding and delivery.\n\n**Details:** Type `object`."},"weight_tier_kg":{"type":"integer","description":"Weight tier kg. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer`."},"weight_kg":{"type":"number","description":"Weight kg. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number`."},"dimensions_cm":{"type":"object","properties":{"length":{"type":"number","description":"Length dimension.\n\n**Details:** Type `number`."},"width":{"type":"number","description":"Width dimension.\n\n**Details:** Type `number`."},"height":{"type":"number","description":"Height dimension.\n\n**Details:** Type `number`."}},"description":"Dimensions cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `object`."}}},"example":{"address":{"name":"A. Renter","telephone":"+15145550100","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"weight_kg":9.5}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"data":{"own_delivery":{"available":true,"reason":null,"fee":18,"currency":"CAD","mode":"flat"},"shipment":{"available":true,"reason":null,"mode":"table","currency":"CAD","weight_tier_kg":10,"weight_tiers_kg":[5,10,20,32],"measure":{"weight_kg":9.5,"length_cm":null,"width_cm":null,"height_cm":null},"options":[{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},{"key":"s4","mode":"courier","channel":"courier","carrier":"City Courier","service":"Same day","service_code":null,"transit_days":0,"price":41.5,"currency":"CAD"}]}}}}}},"422":{"description":"Address missing name, address_1 or city"},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/{id}/delivery":{"post":{"tags":["Platform Apps"],"summary":"Have the bag delivered to an address","description":"Delivery by the operator's own drivers, by deliver_at (business local time). The bag leaves its compartment if it is still there; the bill, including the delivery fee, is due before the delivery is planned — see data.bill.payment (pay in the app with pay/requests when payable_in_app, or at pay_url). Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStorageDelivery","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","deliver_at"],"properties":{"address":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."}},"description":"**Required.**\n\nAddress. Address component used for geocoding and delivery.\n\n**Details:** Type `object`."},"deliver_at":{"type":"string","description":"**Required.**\n\nDeliver at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`."}}},"example":{"address":{"name":"A. Renter","telephone":"+15145550100","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"deliver_at":"2026-09-27 18:00"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"Delivery to the address is requested. Pay the bill on this page to confirm it.","data":{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"},"options":{"keep":false,"warn_until":null,"pickup_site":{"choices":[],"fee":0,"cancellable":false},"return_site":{"changeable":false,"choices":[]},"return_time":{"changeable":true,"latest":"2026-10-08T17:40:00-04:00"},"delivery":{"available":false,"fee":null,"chosen":false,"paid":false,"default_country":"CA"},"shipment":{"available":false,"channels":["label","courier"],"weight_tiers_kg":[5,10,20,32],"tier_required":false,"chosen":true,"paid":false,"shipped":false},"resend_code":true},"timezone":"America/Toronto"}}}}},"422":{"description":"Address or time missing"},"409":{"description":"LOCKER_STORAGE_ADDRESS_NOT_COVERED, LOCKER_STORAGE_ADDRESS_UNPRICED, or not offered now","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"LOCKER_STORAGE_ACTION_UNAVAILABLE","message":"This action is not available right now."}}}},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/{id}/shipment":{"post":{"tags":["Platform Apps"],"summary":"Ship the bag with a carrier or courier","description":"One option key from onward-quote, with the same address and weight. The option is re-quoted and must still be offered. Paid before the bag ships; if the hub weighs it heavier than declared, the difference appears as data.hold and must be paid before it leaves. Needs name, telephone, address_1, city, postcode and country. Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStorageShipment","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","option"],"properties":{"address":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."}},"description":"**Required.**\n\nAddress. Address component used for geocoding and delivery.\n\n**Details:** Type `object`."},"option":{"type":"string","description":"**Required.**\n\nOption. Field in the JSON request body.\n\n**Details:** Type `string`."},"weight_tier_kg":{"type":"integer","description":"Weight tier kg. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `integer`."},"weight_kg":{"type":"number","description":"Weight kg. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `number`."},"dimensions_cm":{"type":"object","properties":{"length":{"type":"number","description":"Length dimension.\n\n**Details:** Type `number`."},"width":{"type":"number","description":"Width dimension.\n\n**Details:** Type `number`."},"height":{"type":"number","description":"Height dimension.\n\n**Details:** Type `number`."}},"description":"Dimensions cm. Physical measurement; unit is endpoint-specific (see schema / packing rules).\n\n**Details:** Type `object`."}}},"example":{"address":{"name":"A. Renter","telephone":"+15145550100","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"option":"t12","weight_kg":9.5}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"Your shipment is set. Pay the bill on this page to confirm it.","data":{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"},"options":{"keep":false,"warn_until":null,"pickup_site":{"choices":[],"fee":0,"cancellable":false},"return_site":{"changeable":false,"choices":[]},"return_time":{"changeable":true,"latest":"2026-10-08T17:40:00-04:00"},"delivery":{"available":false,"fee":null,"chosen":false,"paid":false,"default_country":"CA"},"shipment":{"available":false,"channels":["label","courier"],"weight_tiers_kg":[5,10,20,32],"tier_required":false,"chosen":true,"paid":false,"shipped":false},"resend_code":true},"timezone":"America/Toronto"}}}}},"422":{"description":"LOCKER_STORAGE_WEIGHT_REQUIRED or an incomplete address"},"409":{"description":"LOCKER_STORAGE_OPTION_GONE, LOCKER_STORAGE_SHIPMENT_UNPRICED, or not changeable any more","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"LOCKER_STORAGE_ACTION_UNAVAILABLE","message":"This action is not available right now."}}}},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/locker-storage/rentals/{id}/resend-code":{"post":{"tags":["Platform Apps"],"summary":"Send the pickup code again","description":"To the contact the bag was stored under, never to the account asking. Throttled to 3 requests in 10 minutes. Requires the locker.storage capability (403 APP_CAPABILITY_DISABLED otherwise).","operationId":"platformAppLockerStorageResendCode","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},{"name":"id","in":"path","required":true,"schema":{"type":"integer","description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."},"description":"Rental id\n\nResource identifier.\n\n**Details:** Required · Type `integer`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"message":"Your code has been sent again.","data":{"id":8801,"status":"relayed","status_label":"Relayed","site":{"id":700,"name":"Central Station","address":"1 Main St","city":"Montreal","province":"QC","postcode":"H3B 1A1","country":"CA","latitude":45.5,"longitude":-73.57},"cabinet":{"id":312,"code":"CAB-A"},"compartment_number":null,"compartment_type":"Medium","bound_to_account":true,"started_at":"2026-09-24T09:10:00-04:00","expires_at":"2026-09-26T09:10:00-04:00","ended_at":null,"declared_return_at":"2026-09-27T12:00:00-04:00","bill":{"charged":true,"paid":false,"amount":24,"currency":"CAD","paid_at":null,"due_now":true,"payment":{"subject_type":"locker","subject_id":8801,"amount":24,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=…"}},"relay":{"id":55,"rental_id":8801,"rental_status":"relayed","status":"at_hub","from_site":{"id":700,"name":"Central Station"},"return":{"kind":"shipment","site":null,"address":{"name":"A. Renter","address_1":"10 Rue Sainte-Catherine","city":"Montreal","province":"QC","postcode":"H2X 1K4","country":"CA"},"address_line":"10 Rue Sainte-Catherine, Montreal QC H2X 1K4","paid":false,"shipment":{"carrier":null,"tracking_number":null}},"onward":{"kind":"shipment","status":"weight_hold","mode":"table","channel":"label","weight_tier_kg":10,"weighed_kg":12.4,"declared":{"weight_kg":9.5},"measured":{"weight_kg":12.4},"option":{"key":"t12","mode":"table","channel":"label","carrier":"Canada Post","service":"Expedited","service_code":"DOM.EP","transit_days":2,"price":32,"currency":"CAD"},"price":32,"currency":"CAD","valid_until":"2026-10-01T09:10:00-04:00","hold":{"from_tier_kg":10,"tier_kg":20,"extra":8,"paid":false}},"return_by":"2026-09-27T10:00:00-04:00","declared_return_at":"2026-09-27T12:00:00-04:00","warn_until":null,"taken_out_at":"2026-09-24T15:02:00-04:00","hub_received_at":"2026-09-24T17:40:00-04:00","hub_shipped_at":null,"returned_at":null,"cancelled_at":null,"cancel_reason":null,"hub_days":null,"price":{"hub_per_day":3,"relay_fee":5,"address_return_fee":null,"alt_site_fee":null,"shipment_fee":32,"free_hub_hours":24,"currency":"CAD"},"created_at":"2026-09-24T14:00:00-04:00"},"hold":{"from_tier_kg":10,"tier_kg":20,"subject_type":"luggage_hold","subject_id":55,"amount":8,"currency":"CAD","payable_in_app":true,"pay_url":"https://app.example.com/luggage-relay/8801/hold-pay?expires=1790000000&signature=…"},"options":{"keep":false,"warn_until":null,"pickup_site":{"choices":[],"fee":0,"cancellable":false},"return_site":{"changeable":false,"choices":[]},"return_time":{"changeable":true,"latest":"2026-10-08T17:40:00-04:00"},"delivery":{"available":false,"fee":null,"chosen":false,"paid":false,"default_country":"CA"},"shipment":{"available":false,"channels":["label","courier"],"weight_tiers_kg":[5,10,20,32],"tier_required":false,"chosen":true,"paid":false,"shipped":false},"resend_code":true},"timezone":"America/Toronto"}}}}},"409":{"description":"The bag is no longer held, or has no contact","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":false,"code":"LOCKER_STORAGE_ACTION_UNAVAILABLE","message":"This action is not available right now."}}}},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}},"/v1/apps/{appCode}/clients/{clientCode}/pay/links":{"post":{"tags":["Platform Apps"],"summary":"Pay the code shown on a cabinet screen","description":"The payment code a smart locker screen shows when a pickup — or a relayed bag's delivery or shipment — has to be paid is a signed link to one bill (/pay/locker-storage/{rental}?expires=…&signature=…), not a sticker token. The app posts the scanned link; the signature is the authorisation, as it is in a browser, so the payer need not be the renter. Raises the payment request and answers in the request shape, ready for pay/requests/{token}/pay. A link from another business answers OTHER_BUSINESS with pay_url (also data.pay_url) for a browser. Throttled to 30 requests a minute. Requires the pay.scan capability.","operationId":"platformAppPayResolveLink","security":[{"bearerAuth":[]}],"parameters":[{"name":"appCode","in":"path","required":true,"schema":{"type":"string","description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`.","examples":["mibox"]},"description":"Standalone app code that selects the public app configuration.\n\n**Details:** Required · Type `string`.\n\n**Example:** `mibox`."},{"name":"clientCode","in":"path","required":true,"schema":{"type":"string","description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."},"description":"Client (business) code the app is bound to for this session.\n\n**Details:** Required · Type `string`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["link"],"properties":{"link":{"type":"string","maxLength":2048,"description":"**Required.**\n\nLink. Absolute or relative URL.\n\n**Details:** Type `string` · maxLength `2048`."}}},"example":{"link":"https://app.example.com/pay/locker-storage/8801?expires=1790000000&signature=5d1c…"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"result":true,"request":{"token":"3f9c2a7be51d4c08a6f1e2d3b4c5a6e7","subject_type":"locker","subject_id":8801,"amount_cents":1250,"amount":12.5,"currency":"CAD","description":"Locker storage — CAB-A · 12","status":"pending","expires_at":"2026-09-25T10:30:00-04:00","paid_at":null,"pay_url":"https://app.example.com/pay/r/3f9c2a7be51d4c08a6f1e2d3b4c5a6e7"},"methods":[{"kind":"wallet","gateway":null,"method":"wallet","label":"Pay with balance","completion":"redirect","available":true,"reason":null},{"kind":"gateway","gateway":"stripe","method":"card","label":"Credit / Debit Card","completion":"sheet","available":true,"reason":null}]}}}},"422":{"description":"LINK_NOT_USABLE (bad signature, expired, not a cabinet payment link), NOTHING_TO_PAY, OTHER_BUSINESS or REQUEST_HELD_ELSEWHERE (both with pay_url, also as data.pay_url)"},"403":{"description":"The app assignment or capability is not effective","content":{"application/json":{"example":{"result":false,"code":"APP_CAPABILITY_DISABLED","message":"This wallet feature is not enabled for this app and client."}}}},"401":{"description":"unauthenticated"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Dataset":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"business_id":{"type":"integer","description":"Business id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"created_by":{"type":"integer","description":"Created by. Field in the JSON request body.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Customer List`.","examples":["Customer List"]},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`.\n\n**Example:** `List of all customers with addresses`.","examples":["List of all customers with addresses"]},"status":{"type":"string","enum":["active","inactive"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `inactive`.\n\n**Details:** Type `string`."},"sort_columns":{"type":["array","null"],"items":{"type":"object","description":"Sort columns. Element of a list or map in the request/response payload.\n\n**Details:** Type `object`."},"description":"Sort columns. Field in the JSON request body.\n\n**Details:** Type `array`, items `object` · Nullable."},"search_fields":{"type":["array","null"],"items":{"type":"string","description":"Search fields. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Search fields. Field in the JSON request body.\n\n**Details:** Type `array`, items `string` · Nullable."},"columns":{"type":"array","items":{"$ref":"#/components/schemas/DatasetColumn","description":"Columns. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `DatasetColumn`."},"description":"Columns. Field in the JSON request body.\n\n**Details:** Type `array`."},"groups":{"type":"array","items":{"$ref":"#/components/schemas/DatasetGroup","description":"Groups. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `DatasetGroup`."},"description":"Groups. Field in the JSON request body.\n\n**Details:** Type `array`."},"created_at":{"type":"string","format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"updated_at":{"type":"string","format":"date-time","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}}},"DatasetCreate":{"type":"object","required":["name","columns"],"properties":{"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Customer List`.","examples":["Customer List"]},"description":{"type":"string","description":"Free-text description.\n\n**Details:** Type `string`.\n\n**Example:** `List of all customers`.","examples":["List of all customers"]},"columns":{"type":"array","items":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string","description":"**Required.**\n\nHuman-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Customer Name`.","examples":["Customer Name"]},"code":{"type":"string","pattern":"^[a-zA-Z][a-zA-Z0-9_]*$","description":"**Required.**\n\nStable machine code for this resource.\n\n**Details:** Type `string` · pattern `^[a-zA-Z][a-zA-Z0-9_]*$`.\n\n**Example:** `customer_name`.","examples":["customer_name"]},"original_name":{"type":"string","description":"Original name. Human-readable label.\n\n**Details:** Type `string`."},"data_type":{"type":"string","enum":["text","number","date","address"],"default":"text","description":"Allowed values: `text` · `number` · `date` · `address`.\n\n**Details:** Type `string` · Default: `text`."},"is_required":{"type":"boolean","default":false,"description":"Is required. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean` · Default: `false`."},"required_action":{"type":"string","enum":["skip","error"],"default":"skip","description":"Allowed values: `skip` · `error`.\n\n**Details:** Type `string` · Default: `skip`."},"is_address_part":{"type":"boolean","default":false,"description":"Is address part. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean` · Default: `false`."},"address_order":{"type":"integer","description":"Order for combining address parts\n\n**Details:** Type `integer`."},"is_geocode_source":{"type":"boolean","default":false,"description":"Is geocode source. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean` · Default: `false`."}}},"description":"**Required.**\n\nColumns. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"DatasetColumn":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"dataset_id":{"type":"integer","description":"Dataset id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Customer Name`.","examples":["Customer Name"]},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`.\n\n**Example:** `customer_name`.","examples":["customer_name"]},"original_name":{"type":"string","description":"Original name. Human-readable label.\n\n**Details:** Type `string`."},"column_index":{"type":"integer","description":"Column index. Field in the JSON request body.\n\n**Details:** Type `integer`."},"data_type":{"type":"string","enum":["text","number","date","address"],"description":"Allowed values: `text` · `number` · `date` · `address`.\n\n**Details:** Type `string`."},"is_required":{"type":"boolean","description":"Is required. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"required_action":{"type":"string","enum":["skip","error"],"description":"Allowed values: `skip` · `error`.\n\n**Details:** Type `string`."},"is_address_part":{"type":"boolean","description":"Is address part. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."},"address_order":{"type":["integer","null"],"description":"Address order. Address component used for geocoding and delivery.\n\n**Details:** Type `integer` · Nullable."},"is_geocode_source":{"type":"boolean","description":"Is geocode source. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`."}}},"DatasetGroup":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"dataset_id":{"type":"integer","description":"Dataset id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Import 2024-01-15`.","examples":["Import 2024-01-15"]},"import_status":{"type":"string","enum":["pending","processing","completed","failed","geocoding","updating"],"description":"Allowed values: `pending` · `processing` · `completed` · `failed` · `geocoding` · `updating`.\n\n**Details:** Type `string`."},"total_records":{"type":"integer","description":"Total records. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"processed_records":{"type":"integer","description":"Processed records. Field in the JSON request body.\n\n**Details:** Type `integer`."},"error_count":{"type":"integer","description":"Error count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"error_messages":{"type":["array","null"],"items":{"type":"string","description":"Error messages. Free-text note.\n\n**Details:** Type `string`."},"description":"Error messages. Free-text note.\n\n**Details:** Type `array`, items `string` · Nullable."},"records_count":{"type":"integer","description":"Total records in group\n\n**Details:** Type `integer`."},"geocode_stats":{"type":"object","description":"Geocode status counts\n\n**Details:** Type `object`.","properties":{"pending":{"type":"integer","description":"Pending. Field in the JSON request body.\n\n**Details:** Type `integer`."},"success":{"type":"integer","description":"Success. Field in the JSON request body.\n\n**Details:** Type `integer`."},"failed":{"type":"integer","description":"Failed. Field in the JSON request body.\n\n**Details:** Type `integer`."},"skipped":{"type":"integer","description":"Skipped. Field in the JSON request body.\n\n**Details:** Type `integer`."}}},"created_at":{"type":"string","format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"updated_at":{"type":"string","format":"date-time","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}}},"DatasetRecord":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"dataset_group_id":{"type":"integer","description":"Dataset group id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"data":{"type":"object","description":"Record data with column codes as keys\n\n**Details:** Type `object`."},"address_combined":{"type":["string","null"],"description":"Address combined. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"latitude":{"type":["number","null"],"format":"float","description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`, format `float` · Nullable."},"longitude":{"type":["number","null"],"format":"float","description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`, format `float` · Nullable."},"geocode_status":{"type":"string","enum":["pending","success","failed","skipped"],"description":"Allowed values: `pending` · `success` · `failed` · `skipped`.\n\n**Details:** Type `string`."},"geocode_error":{"type":["string","null"],"description":"Geocode error. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"row_number":{"type":"integer","description":"Row number. Field in the JSON request body.\n\n**Details:** Type `integer`."},"group_name":{"type":"string","description":"Group name (only in search results)\n\n**Details:** Type `string`."},"created_at":{"type":"string","format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"updated_at":{"type":"string","format":"date-time","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}}},"SearchCriteria":{"type":"object","required":["column","operator"],"properties":{"column":{"type":"string","description":"**Required.**\n\nColumn code to search\n\n**Details:** Type `string`."},"operator":{"type":"string","description":"**Required.**\n\nSearch operator\n\nAllowed values: `contains` · `not_contains` · `equals` · `not_equals` · `starts_with` · `ends_with` · `is_empty` · `is_not_empty` · `in_list` · `regex` · `greater_than` · `greater_than_or_equal` · `less_than` · `less_than_or_equal` · `between` · `before` · `after` · `today` · `this_week` · `this_month` · `last_week` · `last_month` · `near` · `in_bounds`.\n\n**Details:** Type `string`.","enum":["contains","not_contains","equals","not_equals","starts_with","ends_with","is_empty","is_not_empty","in_list","regex","greater_than","greater_than_or_equal","less_than","less_than_or_equal","between","before","after","today","this_week","this_month","last_week","last_month","near","in_bounds"]},"value":{"description":"Search value (type depends on operator)"},"value2":{"description":"Second value for range operators like 'between'"}}},"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`.\n\n**Example:** `15`.","examples":[15]},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`.\n\n**Example:** `100`.","examples":[100]},"last_page":{"type":"integer","description":"Last page. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `7`.","examples":[7]}}},"orderId":{"type":"integer","examples":[12345]},"PackageItem":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Existing package id (`packages.id`). On create omit this field. On modify: entries with an id are updated; existing packages whose ids are omitted from `packagesDetail` are deleted (blocked after dispatch / tracking history).\n\n**Details:** Type `integer` · Nullable."},"ref":{"type":["string","null"],"maxLength":255,"description":"Merchant package reference (unique within the order when provided). Used for deduplication when `auto_deduplication` is enabled.\n\n**Details:** Type `string` · Nullable · maxLength `255`."},"length":{"type":["number","null"],"description":"Package length in the unit selected by `dimension_unit` (default unit code 1 = mm).\n\n**Details:** Type `number` · Nullable."},"width":{"type":["number","null"],"description":"Package width in the unit selected by `dimension_unit` (default unit code 1 = mm).\n\n**Details:** Type `number` · Nullable."},"height":{"type":["number","null"],"description":"Package height in the unit selected by `dimension_unit` (default unit code 1 = mm).\n\n**Details:** Type `number` · Nullable."},"weight":{"type":["number","null"],"description":"Package weight in the unit selected by `weight_unit` (default unit code 1 = g).\n\n**Details:** Type `number` · Nullable."},"dimension_unit":{"type":"integer","enum":[1,2,3,4],"default":1,"x-enumDescriptions":["MM (code 1)","CM (code 2)","M (code 3)","INCH (code 4)"],"description":"Dimension unit for length/width/height. Source: `Packages::DIMENSION_UNIT`. Default `1` (mm).\n\nEnum values (from deployed code):\n- `1` — MM (code 1)\n- `2` — CM (code 2)\n- `3` — M (code 3)\n- `4` — INCH (code 4)\n\n**Details:** Type `integer` · Default: `1`.","examples":[1]},"weight_unit":{"type":"integer","enum":[1,2,3,4],"default":1,"x-enumDescriptions":["G (code 1)","KG (code 2)","OZ (code 3)","LB (code 4)"],"description":"Weight unit. Source: `Packages::WEIGHT_UNIT`. Default `1` (g).\n\nEnum values (from deployed code):\n- `1` — G (code 1)\n- `2` — KG (code 2)\n- `3` — OZ (code 3)\n- `4` — LB (code 4)\n\n**Details:** Type `integer` · Default: `1`.","examples":[1]},"external_tracking_number":{"type":["string","null"],"maxLength":255,"description":"Carrier or upstream tracking number stored on the package (optional).\n\n**Details:** Type `string` · Nullable · maxLength `255`."},"insurance_value":{"type":["number","null"],"description":"Declared insurance value for this package (currency = business currency). Used when insurance is enabled at order or package level.\n\n**Details:** Type `number` · Nullable."},"package_value":{"type":["number","null"],"description":"Declared content value of the package (currency = business currency).\n\n**Details:** Type `number` · Nullable."},"notes":{"type":["string","null"],"description":"Free-text note for this package (shown on labels / driver tools when configured).\n\n**Details:** Type `string` · Nullable."}}},"ModifyOrderRequest":{"type":"object","properties":{"customer_id":{"type":["integer","null"],"description":"Customer id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"postcode":{"type":["string","null"],"description":"Postal / ZIP code.\n\n**Details:** Type `string` · Nullable."},"order_channel_code":{"type":["string","null"],"description":"Order channel code. The channel must be enabled for Local Delivery orders and, when the order has a customer-specific whitelist, must be assigned to that customer. Use empty value for Default Channel only when the business Default Channel Local Delivery setting is enabled and Default Channel is allowed for the customer.\n\n**Details:** Type `string` · Nullable."},"carrier_name":{"type":["string","null"],"description":"Carrier name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"ref":{"type":["string","null"],"description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"address_1":{"type":["string","null"],"description":"Primary street address line for the stop.\n\n**Details:** Type `string` · Nullable."},"address_2":{"type":["string","null"],"description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string` · Nullable."},"street_number":{"type":["string","null"],"description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable."},"street_name":{"type":["string","null"],"description":"Street name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"city":{"type":["string","null"],"description":"City / locality.\n\n**Details:** Type `string` · Nullable."},"province":{"type":["string","null"],"description":"Province / state / region.\n\n**Details:** Type `string` · Nullable."},"country":{"type":["string","null"],"description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string` · Nullable."},"name":{"type":["string","null"],"description":"Human-readable name.\n\n**Details:** Type `string` · Nullable."},"email":{"type":["string","null"],"format":"email","description":"Account email address.\n\n**Details:** Type `string`, format `email` · Nullable."},"telephone":{"type":["string","null"],"description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string` · Nullable."},"note":{"type":["string","null"],"description":"Note. Free-text note.\n\n**Details:** Type `string` · Nullable."},"pickup_instruction":{"type":["string","null"],"description":"Pickup instruction. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"delivery_instruction":{"type":["string","null"],"description":"Delivery instruction. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"signature_option":{"type":["integer","null"],"description":"Signature option. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"insurance_option":{"type":["integer","null"],"description":"Insurance option. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"need_pick_up":{"type":["integer","null"],"description":"Pickup mode: 0=none, 1=need pickup, 2=inbound scan required, 3=need batch pickup.\n\n**Details:** Type `integer` · Nullable."},"allow_dropoff":{"type":["integer","null"],"description":"Allow dropoff. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"self_pickup":{"type":["integer","null"],"description":"Self-pickup flag: 0=delivery, 1=self-pickup (account must allow self-pickup).\n\n**Details:** Type `integer` · Nullable."},"auto_deduplication":{"type":["integer","null"],"description":"Auto deduplication. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable."},"strict_duplicate_check":{"type":["integer","null"],"description":"Optional, default 0. When 1, a detected duplicate returns HTTP 409 instead of the legacy 200 result:false envelope.\n\n**Details:** Type `integer` · Nullable."},"service_time":{"type":["number","null"],"description":"Service time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `number` · Nullable."},"pickup_service_time":{"type":["number","null"],"description":"Pickup service time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `number` · Nullable."},"type":{"type":["string","null"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string` · Nullable."},"sorting_code":{"type":["string","null"],"description":"Sorting code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"notification_language":{"type":["string","null"],"description":"Notification language. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"packagesDetail":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PackageItem","description":"Packages detail. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `PackageItem`."},"description":"Replaces the order's full package set: packages with an id are updated, entries without an id are created, and existing packages whose ids are omitted from this array are deleted. Deletion is refused (HTTP 400) once the order has been dispatched/processed, or when an omitted package already has tracking history (received, handed over, stocked out, or a purchased label) — always include the ids of all packages you want to keep.\n\nPer-package details for this order. Each element is a `PackageItem` (`ref`, dimensions, weight, units, value, notes, optional `id` on update). On **create**: every entry is inserted as a new package (omit `id`). On **modify**: entries with `id` are updated, entries without `id` are created, and existing packages whose ids are **omitted** from this array are deleted — deletion is refused (HTTP 400) once the order has been dispatched/processed or a package has tracking history; always include the ids of packages you want to keep. Package `ref` values must be unique within the order when provided.\n\nPer-package details (`PackageItem` array). Create inserts every entry; modify updates by `id`, creates without `id`, and deletes packages whose ids are omitted (blocked after dispatch / tracking history).\n\n**Details:** Type `array` · Nullable."},"pin_verification_required":{"type":["integer","null"],"description":"Override PIN verification requirement for this order. null=Use Default, 0=Disabled, 1=Enabled\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","enum":[0,1,null],"x-enumDescriptions":["No / false / off","Yes / true / on"],"examples":[1]},"max_ride_minutes":{"type":["integer","null"],"minimum":1,"maximum":1440,"description":"Optional. Longest time in minutes the goods may be on board between pickup and delivery. Null clears it.\n\n**Details:** Type `integer` · Nullable · min `1` · max `1440`.\n\n**Example:** `90`.","examples":[90]},"dispatch_ready_at":{"type":["string","null"],"description":"Optional. When the goods are ready to leave the depot (Y-m-d H:i:s). Not the same as ready for customer pickup. Null clears it.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-20 07:30:00`.","examples":["2026-09-20 07:30:00"]},"route_group_key":{"type":["string","null"],"maxLength":64,"description":"Optional. Orders with the same key are planned on the same vehicle. Null clears it.\n\n**Details:** Type `string` · Nullable · maxLength `64`.\n\n**Example:** `STORE-42`.","examples":["STORE-42"]},"goods_class_id":{"type":["integer","null"],"description":"Optional. Goods class id of the business (Settings > Goods Classes); orders of incompatible classes never share a vehicle. Wins over goods_class. Null clears it.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `3`.","examples":[3]},"goods_class":{"type":["string","null"],"description":"Optional. Goods class name, alternative to goods_class_id. An unknown class is rejected with HTTP 400.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Food`.","examples":["Food"]},"delivery_alternatives":{"type":["array","null"],"maxItems":10,"items":{"type":"object","properties":{"addressbook_id":{"type":["integer","null"],"description":"Address book entry of the order's business (or of its customer). Either this or latitude/longitude is required.\n\n**Details:** Type `integer` · Nullable."},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `43.6532`.","examples":[43.6532]},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `-79.3832`.","examples":[-79.3832]},"address":{"type":["string","null"],"maxLength":500,"description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable · maxLength `500`.\n\n**Example:** `200 Front St W, Toronto`.","examples":["200 Front St W, Toronto"]},"time_window_start":{"type":["string","null"],"description":"Y-m-d H:i:s; send together with time_window_end\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-20 09:00:00`.","examples":["2026-09-20 09:00:00"]},"time_window_end":{"type":["string","null"],"description":"Y-m-d H:i:s; after time_window_start\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-20 12:00:00`.","examples":["2026-09-20 12:00:00"]}}},"description":"Optional. Alternative delivery locations; the order is delivered at its own address or at one of these. Replaces the stored list when sent; an empty list clears it; omitted leaves it unchanged.\n\n**Details:** Type `array`, items `object` · Nullable · maxItems `10`."},"packages":{"type":["integer","null"],"description":"Legacy package count. Prefer `packagesDetail` for real dimensions/weights. When `packagesDetail` is present it takes precedence.\n\n**Details:** Type `integer` · Nullable."}}},"ModifyOrderResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"shipping_price":{"type":["number","null"],"description":"Shipping price. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `number` · Nullable."},"price_details":{"type":["object","null"],"description":"Price details. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `object` · Nullable."},"currency":{"type":["string","null"],"description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"tracking_number":{"type":"array","items":{"type":"string","description":"Tracking number. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"description":"Superroute or carrier tracking number.\n\n**Details:** Type `array`, items `string`."},"packages":{"type":"array","items":{"$ref":"#/components/schemas/PackageItem","description":"Packages. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `PackageItem`."},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`."}}},"UserLogin":{"type":"object","properties":{"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`."},"password":{"type":"string","description":"Account password (never logged or returned by the API).\n\n**Details:** Type `string`."}}},"OperationEvents":{"type":"object","properties":{"order_id":{"type":"array","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `array`.","examples":[[1,2,3]]}}},"OrderStatusUpdate":{"type":"object","properties":{"orderId":{"$ref":"#/components/schemas/orderId","description":"Superroute order id (`orders.id`).\n\n**Details:** Schema `$ref` → `orderId`."},"packageIds":{"type":"array","description":"Package ids. List of identifiers for the related records.\n\n**Details:** Type `array`.","examples":[[1,2,3]]},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`.\n\n**Example:** `NR`.","examples":["NR"]},"return_reason_id":{"type":"integer","description":"Return reason id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"gps_tracking_id":{"type":"integer","description":"Gps tracking id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"routeId":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"delivery_pin":{"type":"string","description":"6-digit delivery PIN code for proof of delivery verification\n\n**Details:** Type `string` · minLength `6` · maxLength `6`.\n\n**Example:** `123456`.","minLength":6,"maxLength":6,"examples":[123456]}}},"OrderNotesSave":{"type":"object","properties":{"orderId":{"$ref":"#/components/schemas/orderId","description":"Superroute order id (`orders.id`).\n\n**Details:** Schema `$ref` → `orderId`."},"notes":{"type":"string","description":"Free-text notes.\n\n**Details:** Type `string`.\n\n**Example:** `this is an example`.","examples":["this is an example"]}}},"OrderNotesUpdate":{"type":"object","properties":{"noteId":{"type":"integer","description":"Note id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `204`.","examples":[204]},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `this is an example`.","examples":["this is an example"]}}},"MoveOrderFromRoute":{"type":"object","properties":{"from_route_id":{"type":"integer","description":"From route id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"order_ids":{"type":"array","description":"List of Superroute order ids.\n\n**Details:** Type `array`.","examples":[[1,2,3]]},"to_route_id":{"type":"integer","description":"To route id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `456`.","examples":[456]},"to_driver_id":{"type":"integer","description":"To driver id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `789`.","examples":[789]}}},"OptimizeRoute":{"type":"object","properties":{"async":{"type":"boolean","default":true,"description":"Async. Field in the JSON request body.\n\n**Details:** Type `boolean` · Default: `true`.\n\n**Example:** `true`.","examples":[true]},"routeId":{"type":"integer","description":"**Required.**\n\nThe ID of the route to assign drivers to\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"driverIds":{"type":"array","items":{"type":"integer","description":"Driver ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"**Required.**\n\nList of driver IDs to assign to the route\n\n**Details:** Type `array`, items `integer`.","examples":[[11,22,33]]},"driverAddresses":{"type":"object","description":"Optional per-driver address info\n\n**Details:** Type `object`.","additionalProperties":{"type":"object","properties":{"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1001`.","examples":[1001]},"start_address":{"type":["object","null"],"properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Warehouse A`.","examples":["Warehouse A"]},"lat":{"type":"number","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `43.65107`.","examples":[43.65107]},"lng":{"type":"number","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `-79.347015`.","examples":[-79.347015]},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`.\n\n**Example:** `123 Main St`.","examples":["123 Main St"]},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`.\n\n**Example:** `Toronto`.","examples":["Toronto"]},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`.","examples":["ON"]},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `M5V2T6`.","examples":["M5V2T6"]}},"description":"Start address. Address component used for geocoding and delivery.\n\n**Details:** Type `object` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1002`.","examples":[1002]},"end_address":{"type":["object","null"],"properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Dropoff Point Z`.","examples":["Dropoff Point Z"]},"lat":{"type":"number","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `43.70011`.","examples":[43.70011]},"lng":{"type":"number","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `-79.4163`.","examples":[-79.4163]},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`.\n\n**Example:** `456 King St`.","examples":["456 King St"]},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`.\n\n**Example:** `Toronto`.","examples":["Toronto"]},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`.","examples":["ON"]},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `M5V1K1`.","examples":["M5V1K1"]}},"description":"End address. Address component used for geocoding and delivery.\n\n**Details:** Type `object` · Nullable."}},"description":"Driver addresses. Address component used for geocoding and delivery.\n\n**Details:** Type `object`."},"examples":[{"11":{"start_address_id":1001,"start_address":{"name":"Warehouse A","lat":43.65107,"lng":-79.347015},"end_address":{"name":"Dropoff Point Z","address_1":"456 King St","city":"Toronto","province":"ON","country":"CA","postcode":"M5V1K1"}}}]}},"required":["routeId","driverIds"]},"OptimizeRouteForDriver":{"type":"object","properties":{"async":{"type":"boolean","default":true,"description":"Async. Field in the JSON request body.\n\n**Details:** Type `boolean` · Default: `true`.\n\n**Example:** `true`.","examples":[true]},"routeId":{"type":"integer","description":"**Required.**\n\nThe ID of the route to assign drivers to\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"driverAddresses":{"type":"object","description":"Optional per-driver address info\n\n**Details:** Type `object`.","additionalProperties":{"type":"object","properties":{"start_address_id":{"type":["integer","null"],"description":"Start address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1001`.","examples":[1001]},"start_address":{"type":["object","null"],"properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Warehouse A`.","examples":["Warehouse A"]},"lat":{"type":"number","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `43.65107`.","examples":[43.65107]},"lng":{"type":"number","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `-79.347015`.","examples":[-79.347015]},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`.\n\n**Example:** `123 Main St`.","examples":["123 Main St"]},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`.\n\n**Example:** `Toronto`.","examples":["Toronto"]},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`.","examples":["ON"]},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `M5V2T6`.","examples":["M5V2T6"]}},"description":"Start address. Address component used for geocoding and delivery.\n\n**Details:** Type `object` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"End address id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1002`.","examples":[1002]},"end_address":{"type":["object","null"],"properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Dropoff Point Z`.","examples":["Dropoff Point Z"]},"lat":{"type":"number","description":"Lat. Geographic latitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `43.70011`.","examples":[43.70011]},"lng":{"type":"number","description":"Lng. Geographic longitude in decimal degrees.\n\n**Details:** Type `number`.\n\n**Example:** `-79.4163`.","examples":[-79.4163]},"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`.\n\n**Example:** `456 King St`.","examples":["456 King St"]},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`.\n\n**Example:** `Toronto`.","examples":["Toronto"]},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`.","examples":["ON"]},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `M5V1K1`.","examples":["M5V1K1"]}},"description":"End address. Address component used for geocoding and delivery.\n\n**Details:** Type `object` · Nullable."}},"description":"Driver addresses. Address component used for geocoding and delivery.\n\n**Details:** Type `object`."},"examples":[{"start_address_id":1001,"start_address":{"name":"Warehouse A","lat":43.65107,"lng":-79.347015},"end_address_id":1002,"end_address":{"name":"Dropoff Point Z","address_1":"456 King St","city":"Toronto","province":"ON","country":"CA","postcode":"M5V1K1"}}]}},"required":["routeId"]},"CancelRoute":{"type":"object","properties":{"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]}}},"AddOrderToRoute":{"type":"object","properties":{"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"driver_id":{"type":"integer","description":"Driver id.\n\n**Details:** Type `integer`.\n\n**Example:** `456`.","examples":[456]},"order_ids":{"type":"array","description":"List of Superroute order ids.\n\n**Details:** Type `array`.","examples":[[1,2,3]]},"after_stop_number":{"type":["integer","null"],"minimum":0,"description":"Insert the orders after this stop number on that driver's run instead of appending them at the end; 0 puts them first, and every stop behind the position is renumbered. Omit the field to append after the driver's last stop, which is what this endpoint has always done. This is the only way to add a stop to a route that is already being driven: once its orders leave 'waiting to plan' the route cannot be re-solved, so re-planning it would produce a route holding only the new stop. A position before a stop the driver has already attempted is refused.\n\n**Details:** Type `integer` · Nullable · min `0`.\n\n**Example:** `13`.","examples":[13]}}},"RemoveOrderFromRoute":{"type":"object","properties":{"route_id":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"order_ids":{"type":"array","description":"List of Superroute order ids.\n\n**Details:** Type `array`.","examples":[[1,2,3]]},"cancel_order":{"type":"integer","description":"Cancel order. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `0`.","examples":[0]}}},"BuildRouteV3":{"type":"object","required":["route_name","route_date","drivers"],"properties":{"route_name":{"type":"string","description":"**Required.**\n\nName for the route\n\n**Details:** Type `string`.\n\n**Example:** `Morning Route`.","examples":["Morning Route"]},"route_date":{"type":"string","format":"date","description":"**Required.**\n\nRoute date in YYYY-MM-DD format\n\n**Details:** Type `string`, format `date`.\n\n**Example:** `2025-03-14`.","examples":["2025-03-14"]},"routing_engine":{"type":"integer","description":"Routing engine: 1=sRoute (default), 2=sRoute 2, 3=sRoute 2T (sRoute 2T, a separate engine enabled per business). Must be allowed by your business configuration. Use GET /v3/client/build-route/options to list available engines.\n\n**Details:** Type `integer`.","examples":[1]},"balance_mode":{"type":"string","description":"Unified balance mode. For sRoute: '1'=equal order counts, '2'=working hours, '3'=no balancing, '4'=balanced within tolerance, '5'=balanced by zone (compact non-crossing zones), '6'=working hours within tolerance, '7'=balanced by zone and working hours (compact non-crossing zones cut on time, corrected from measured working hours). For sRoute 2 and sRoute 2T: preset name string (each engine has its own preset list). Use GET /v3/client/build-route/options to list available values per engine. Defaults to '1'.\n\n**Details:** Type `string`.","examples":[1]},"balance_tolerance":{"type":"integer","description":"sRoute balance_mode '4' only: how far a driver's order count may sit from the average, as a percent (1-100). Ignored by the other balance modes. Defaults to the business route-settings value, then 15.\n\n**Details:** Type `integer`.","examples":[15]},"capacity_type":{"type":"integer","description":"Capacity type: 1=Orders (default), 2=Packages, 3=Load Units\n\n**Details:** Type `integer`.","examples":[1]},"load_check":{"type":"boolean","description":"Consider vehicle load (0/1). When 1, planning also constrains each driver by the assigned vehicle's cargo volume, load weight and maximum item length, in addition to the count-based capacity. Defaults to the business route-settings value.\n\n**Details:** Type `boolean`.","examples":[false]},"service_time":{"type":"integer","description":"Service time per stop in minutes (default: 5)\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","examples":[3]},"pickup_time":{"type":"integer","description":"Pickup time per stop in minutes (defaults to service_time)\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","examples":[3]},"package_processing_time":{"type":"integer","description":"Package processing time in seconds (default: 30)\n\n**Details:** Type `integer`.","examples":[30]},"package_pickup_time":{"type":"integer","description":"Package pickup time in seconds (defaults to package_processing_time)\n\n**Details:** Type `integer`.\n\n**Example:** `30`.","examples":[30]},"order_number":{"type":"integer","description":"Maximum number of orders (optional)\n\n**Details:** Type `integer`.\n\n**Example:** `100`.","examples":[100]},"need_approval":{"type":"integer","description":"0 or 1, whether route needs approval after planning\n\n**Details:** Type `integer`.","examples":[1]},"notify_at":{"type":"integer","minimum":0,"maximum":23,"description":"Hour (0-23) in the user time zone when advance email/SMS reminders should be sent. Leave null/omitted to allow any hour.\n\n**Details:** Type `integer` · min `0` · max `23`.\n\n**Example:** `9`.","examples":[9]},"notification_enabled":{"type":"boolean","description":"Master switch: enable all email/SMS notifications for this route. Defaults to true. Set to false to suppress every notification for this route, even when the global switch is on.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"advance_notification_enabled":{"type":"boolean","description":"Enable the pre-delivery advance reminder (day-before email/SMS) for this route. Defaults to true. Set to false to skip the day-before reminder while keeping other notifications.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"territory_id":{"type":"integer","description":"Territory ID (required if business has territories)\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"order_batch":{"type":"string","description":"Comma-separated order batch filter\n\n**Details:** Type `string`.\n\n**Example:** `W1,W2,W3`.","examples":["W1,W2,W3"]},"sorting_code":{"type":"string","description":"Comma-separated sorting code filter\n\n**Details:** Type `string`.\n\n**Example:** `607,304,021`.","examples":["607,304,021"]},"label_code":{"type":"string","description":"Label code filter\n\n**Details:** Type `string`.\n\n**Example:** `X2,X3,X4`.","examples":["X2,X3,X4"]},"warehouse_id":{"type":"integer","description":"Warehouse ID filter (used with territory)\n\n**Details:** Type `integer`.\n\n**Example:** `12`.","examples":[12]},"max_distance":{"type":"number","description":"Maximum route distance\n\n**Details:** Type `number`.\n\n**Example:** `120`.","examples":[120]},"order_type":{"type":"string","description":"Order type filter (D:Delivery, P:Pickup, DP:Delivery+Pickup, DD:Direct Delivery, P2P:Peer to Peer)\n\nOrder type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nEnum values (from deployed code):\n- `D` — Delivery\n- `P` — Pickup\n- `L` — Label Service\n- `P2P` — Peer to Peer\n- `S` — Storage Order\n- `M` — Moving Order\n- `SH` — Shipping Service\n- `SO` — Shipout\n- `LTL` — LTL Service\n- `I` — Instant Delivery\n\n**Details:** Type `string`.\n\n**Example:** `D,P,DP,DD,P2P`.","enum":["D","P","L","P2P","S","M","SH","SO","LTL","I"],"x-enumDescriptions":["Delivery","Pickup","Label Service","Peer to Peer","Storage Order","Moving Order","Shipping Service","Shipout","LTL Service","Instant Delivery"],"examples":["D,P,DP,DD,P2P"]},"related_order_type":{"type":"string","description":"Related order type filter (comma-separated). Values: NONE (no related type), 1=Batch Pickup, 2=Super Proxy, 3=Storage Order, 4=Return Request, 5=Moving Order, 6=Kiosk Pickup, 7=Smart Locker Pickup, 8=Product Purchase\n\nHow this order links to another business document (`orders.related_order_type`). Source: `RelatedOrderTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Batch Pickup\n- `2` — Super Proxy\n- `3` — Storage Order\n- `4` — Return Request\n- `5` — Moving Order\n- `6` — Kiosk Pickup\n- `7` — Smart Locker Pickup\n- `8` — Product Purchase\n- `9` — Shipping Order\n- `10` — Storage Shipout\n- `11` — Return Label\n- `12` — Third-party Delivery Transfer\n- `16` — Sales Order\n- `17` — Third-party Partial Delivery Split\n- `18` — Order Split\n\n**Details:** Type `string`.\n\n**Example:** `NONE,1,3`.","enum":[1,2,3,4,5,6,7,8,9,10,11,12,16,17,18],"x-enumDescriptions":["Batch Pickup","Super Proxy","Storage Order","Return Request","Moving Order","Kiosk Pickup","Smart Locker Pickup","Product Purchase","Shipping Order","Storage Shipout","Return Label","Third-party Delivery Transfer","Sales Order","Third-party Partial Delivery Split","Order Split"],"examples":["NONE,1,3"]},"order_source":{"type":"string","description":"Order source filter (comma-separated). Values: 1=Import, 2=Web, 3=API, 4=Shopify, 5=WooCommerce, 6=Magento, 7=BigCommerce, 8=Amazon, 9=Walmart, 10=Etsy, 11=SPS Commerce, 12=EDI\n\n**Details:** Type `string`.\n\n**Example:** `1,2,3`.","examples":["1,2,3"]},"drivers":{"type":"array","description":"**Required.**\n\nArray of driver objects. Only 'id' is required — all other fields are optional and will fall back to the driver's default settings (start_location_id, end_location_id, capacity, work_from, work_to, max_distance, vehicle_type, region_group_id, skills) if not provided.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","required":["id"],"properties":{"id":{"type":"integer","description":"**Required.**\n\nDriver ID\n\n**Details:** Type `integer`."},"start_address_id":{"type":"integer","description":"Existing address book ID for start address (falls back to driver's default start_location_id)\n\n**Details:** Type `integer`."},"start_address":{"type":"object","description":"New start address (alternative to start_address_id)\n\n**Details:** Type `object`.","properties":{"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."}}},"end_address_id":{"type":"integer","description":"Existing address book ID for end address (falls back to driver's default end_location_id)\n\n**Details:** Type `integer`."},"end_address":{"type":"object","description":"New end address (alternative to end_address_id)\n\n**Details:** Type `object`.","properties":{"address_1":{"type":"string","description":"Primary street address line for the stop.\n\n**Details:** Type `string`."},"address_2":{"type":"string","description":"Secondary address line (apartment / suite).\n\n**Details:** Type `string`."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."}}},"start_time":{"type":"string","description":"Work start time, e.g. 09:00 (falls back to driver's default work_from)\n\n**Details:** Type `string`."},"end_time":{"type":"string","description":"Work end time, e.g. 17:00 (falls back to driver's default work_to)\n\n**Details:** Type `string`."},"capacity":{"type":"integer","description":"Driver capacity (falls back to driver's default capacity)\n\n**Details:** Type `integer`."},"max_distance":{"type":"number","description":"Per-driver maximum distance (falls back to driver's default max_distance)\n\n**Details:** Type `number`."},"skill_ids":{"type":"array","items":{"type":"integer","description":"Skill ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Array of skill IDs (falls back to driver's configured skills)\n\n**Details:** Type `array`, items `integer`."},"vehicle_type":{"type":"integer","description":"1:Car, 2:Truck, 3:Motorcycle, 4:Bicycle, 5:Pedestrian (falls back to driver's default vehicle_type)\n\nVehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `integer`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"]},"region_group_id":{"type":"integer","description":"Region group ID (falls back to driver's default region_group_id)\n\n**Details:** Type `integer`."},"shifts":{"type":["array","null"],"maxItems":6,"description":"Optional (phase P3). Two or more shifts plan the driver shift by shift on every engine: each shift is its own vehicle that starts empty (capacity per shift), a driver break goes to the shift its window falls in, and the route keeps one run per driver (the boundaries are stored as planned stops). Shifts are sorted, may not overlap and each ends after it starts; an invalid list is refused with 422. Omitted, null or one shift: planned as before from start_time to end_time.\n\n**Details:** Type `array`, items `object` · Nullable · maxItems `6`.","items":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","pattern":"^([01]?\\d|2[0-3]):[0-5]\\d$","description":"**Required.**\n\nStart. Field in the JSON request body.\n\n**Details:** Type `string` · pattern `^([01]?\\d|2[0-3]):[0-5]\\d$`.\n\n**Example:** `08:00`.","examples":["08:00"]},"end":{"type":"string","pattern":"^([01]?\\d|2[0-3]):[0-5]\\d$","description":"**Required.**\n\nEnd. Field in the JSON request body.\n\n**Details:** Type `string` · pattern `^([01]?\\d|2[0-3]):[0-5]\\d$`.\n\n**Example:** `12:00`.","examples":["12:00"]},"start_address_id":{"type":["integer","null"],"description":"Address book id the shift starts from; null = the driver's start address.\n\n**Details:** Type `integer` · Nullable."},"end_address_id":{"type":["integer","null"],"description":"Address book id the shift ends at; null = the driver's end address.\n\n**Details:** Type `integer` · Nullable."}}}}}},"examples":[[{"id":2,"start_address_id":1,"end_address_id":2,"start_time":"09:00","end_time":"17:00","capacity":50,"max_distance":120,"skill_ids":[1,2],"vehicle_type":1,"region_group_id":2001},{"id":5}]]},"route_avoid_tolls":{"type":"integer","enum":[0,1],"description":"Keep this route off toll roads. 1 to avoid, 0 to allow. Omit to follow the vehicle model, then the business setting. Ignored unless Road Preferences is enabled for the account by the platform administrator: while it is off the field is accepted, not stored, and the route plans on the engine default roads; the request still succeeds.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"],"examples":[1]},"route_avoid_highways":{"type":"integer","enum":[0,1],"description":"Keep this route off motorways. 1 to avoid, 0 to allow. Omit to follow the vehicle model, then the business setting. Ignored unless Road Preferences is enabled for the account by the platform administrator: while it is off the field is accepted, not stored, and the route plans on the engine default roads; the request still succeeds.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"route_avoid_ferries":{"type":"integer","enum":[0,1],"description":"Keep this route off ferries. 1 to avoid, 0 to allow. Only matters where a ferry is part of the road network. Omit to follow the vehicle model, then the business setting. Ignored unless Road Preferences is enabled for the account by the platform administrator: while it is off the field is accepted, not stored, and the route plans on the engine default roads; the request still succeeds.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"route_prefer_shortest":{"type":"integer","enum":[0,1],"description":"Optimise this route for distance rather than time. 1 to prefer shortest, 0 for fastest. Omit to follow the vehicle model, then the business setting. Ignored unless Road Preferences is enabled for the account by the platform administrator: while it is off the field is accepted, not stored, and the route plans on the engine default roads; the request still succeeds.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer`.","x-enumDescriptions":["No / false / off","Yes / true / on"]},"route_optimize_for":{"type":"integer","enum":[0,1,2],"description":"What to optimise this route for. 0 fastest, 1 balanced (a shorter drive for about the same time; cars only, trucks and motorcycles plan it as fastest), 2 shortest. Takes precedence over route_prefer_shortest when both are sent. Omit to follow the vehicle model, then the business setting. Ignored unless Road Preferences is enabled for the account by the platform administrator: while it is off the field is accepted, not stored, and the route plans on the engine default roads; the request still succeeds.\n\nAllowed values: `0` · `1` · `2`.\n\n**Details:** Type `integer`."},"route_residential_access":{"type":"integer","enum":[0,1,2,3],"description":"How freely trucks on this route enter residential and service streets. 0 enter freely (small vans), 1 moderate (medium trucks), 2 standard (regular trucks), 3 avoid where possible (large trucks). Trucks only. Omit to follow the vehicle model, then the business setting. Ignored unless Road Preferences is enabled for the account by the platform administrator: while it is off the field is accepted, not stored, and the route plans on the engine default roads; the request still succeeds.\n\nEnum values:\n- `0` — Pending\n- `1` — Completed\n- `2` — Failed\n- `3` — Cancelled\n\n**Details:** Type `integer`.","x-enumDescriptions":["Pending","Completed","Failed","Cancelled"]},"exclusion_zone_set_ids":{"type":["array","null"],"items":{"type":"integer","description":"Exclusion zone set ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"maxItems":50,"description":"Exclusion zone sets this route must drive around (see /v3/client/exclusion-zone-sets). Only zones in force on route_date count, identical shapes count once, and together they may not exceed 100 km of circumference, or the build is refused with 422. Orders inside a zone, or walled off by zones, come back unassigned with reason inside_exclusion_zone or enclosed_by_exclusion_zone. Omit for no zones. Ignored unless Exclusion Zones is enabled for the account by the platform administrator: while it is off the ids are accepted, not checked, and the route plans without zones; the request still succeeds.\n\n**Details:** Type `array`, items `integer` · Nullable · maxItems `50`.","examples":[[12]]},"route_advanced_options":{"type":["object","null"],"additionalProperties":false,"description":"Advanced road options for this route. Every key is optional: omit a key, or the whole object, to follow the business Route Settings; blank there too leaves the routing engine's own default. Stored on the route, so rebuild, optimize and Live Replan use them too. Applies to sRoute, sRoute 2 and sRoute 2T. Whole seconds from 0 to 43200: maneuver_penalty (per turn onto a differently named road; engine default 5), gate_penalty (300), private_access_penalty (450), destination_only_penalty (600), service_penalty (75 for cars, 0 for trucks), toll_booth_penalty (0; also steers trucks, not motor scooters), country_crossing_cost (600; added to arrival times), country_crossing_penalty (0). true or false: exclude_unpaved (cars, buses, trucks), exclude_cash_only_tolls, include_hov2, include_hov3, include_hot (cars only). A key a vehicle type cannot use is left out for that vehicle. Truck-only routing (designated truck routes, roads closed to heavy vehicles) is set on the vehicle model, not here. Unknown keys and out-of-range values are refused with 422. Ignored unless Road Preferences is enabled for the account by the platform administrator: while it is off the field is accepted, not stored, and the route plans on the engine default roads; the request still succeeds.\n\n**Details:** Type `object` · Nullable.","properties":{"maneuver_penalty":{"type":"integer","minimum":0,"maximum":43200,"description":"Seconds; omit to follow Route Settings.\n\n**Details:** Type `integer` · min `0` · max `43200`."},"gate_penalty":{"type":"integer","minimum":0,"maximum":43200,"description":"Seconds; omit to follow Route Settings.\n\n**Details:** Type `integer` · min `0` · max `43200`."},"private_access_penalty":{"type":"integer","minimum":0,"maximum":43200,"description":"Seconds; omit to follow Route Settings.\n\n**Details:** Type `integer` · min `0` · max `43200`."},"destination_only_penalty":{"type":"integer","minimum":0,"maximum":43200,"description":"Seconds; omit to follow Route Settings.\n\n**Details:** Type `integer` · min `0` · max `43200`."},"service_penalty":{"type":"integer","minimum":0,"maximum":43200,"description":"Seconds; omit to follow Route Settings.\n\n**Details:** Type `integer` · min `0` · max `43200`."},"toll_booth_penalty":{"type":"integer","minimum":0,"maximum":43200,"description":"Seconds; omit to follow Route Settings.\n\n**Details:** Type `integer` · min `0` · max `43200`."},"country_crossing_cost":{"type":"integer","minimum":0,"maximum":43200,"description":"Seconds; omit to follow Route Settings.\n\n**Details:** Type `integer` · min `0` · max `43200`."},"country_crossing_penalty":{"type":"integer","minimum":0,"maximum":43200,"description":"Seconds; omit to follow Route Settings.\n\n**Details:** Type `integer` · min `0` · max `43200`."},"exclude_unpaved":{"type":"boolean","description":"Omit to follow Route Settings; false sends nothing.\n\n**Details:** Type `boolean`."},"exclude_cash_only_tolls":{"type":"boolean","description":"Omit to follow Route Settings; false sends nothing.\n\n**Details:** Type `boolean`."},"include_hov2":{"type":"boolean","description":"Omit to follow Route Settings; false sends nothing.\n\n**Details:** Type `boolean`."},"include_hov3":{"type":"boolean","description":"Omit to follow Route Settings; false sends nothing.\n\n**Details:** Type `boolean`."},"include_hot":{"type":"boolean","description":"Omit to follow Route Settings; false sends nothing.\n\n**Details:** Type `boolean`."}},"examples":[{"maneuver_penalty":30,"toll_booth_penalty":600,"exclude_unpaved":true}]},"solver_rules":{"type":["object","null"],"additionalProperties":false,"description":"Planning rules for this route. Every key is optional: omit a key, or the whole object, to follow the business Route Settings, and then the built-in default, which plans exactly as before. The rules are stored on the route, so rebuild, optimize and Live Replan use them too. objective and breaks apply to sRoute, sRoute 2 and sRoute 2T; lateness_tolerance_minutes to sRoute 2T only; preferred_driver, preferred_driver_days and keep_assignments to sRoute 2T and sRoute 2 (1.2.11 or later); solve_time and balance_strength to sRoute 2 (1.2.11 or later) and sRoute 2T (1.0.8 or later). Engines that do not honour a rule, or run an older version, ignore it. Unknown keys and out-of-range values are refused with 422. sRoute 2T 1.0.10 or later only (an older sRoute 2T, sRoute and sRoute 2 are sent nothing for them): overtime_minutes (0-240, default 0 = off) lets each driver work that long past the shift end, and overtime_cost (off | low | normal | high, default normal) prices an hour of it as 0, 0.5, 1 or 2 hours of driving; familiar_zones (off | soft, default off) keeps region groups a hard rule (off) or makes them a preference (soft) whose strength is familiar_zones_strength (low | normal | high, about 2.5, 5 or 15 minutes of driving per stop); vip_must_serve (on | off, default off) drops stops of VIP consignees and orders with priority Emergency or higher only when nothing else makes room, and flags the ones still left out in route.plan_explanation.must_serve_unmet; deferrable_low_priority (on | off, default off) drops orders with priority Flexible or Hold first, returned unassigned with reason deferred. vip_must_serve and deferrable_low_priority also accept true / false. breaks_during_wait (on | off, default off, sRoute 2T 1.0.16 or later) lets a driver's break be taken while the driver waits for a stop's time window, when that does not make the stop later; it also accepts true / false. sRoute 2T 1.0.19 or later only (an older sRoute 2T, sRoute and sRoute 2 are sent nothing for them, and the build lists them in data.rule_notices): max_ride_minutes (0-1440, default 0 = no default) is the longest ride, in minutes, of a pickup-and-delivery order from leaving its pickup to arriving at its delivery; an order's own max_ride_minutes outranks it and applies even without this rule; latest_departure_minutes (0-720, default 0 = off) makes each driver with working hours leave the start by that many minutes after the shift start when the route is built; order_groups (on | off, default off) keeps orders that share a route_group_key on one vehicle, all of them or none; goods_class_separation (on | off, default off) keeps orders of incompatible goods classes off the same vehicle; deliveries_before_pickups (on | off, default off) serves delivery-only stops before pickup-only stops on every route; waiting_cost (off | low | normal | high, default off) prices an hour of waiting at stops as 0.25, 0.5 or 1 hour of driving; use_all_vehicles (off | low | normal | high, default off) makes each idle vehicle cost about 0.5, 1 or 2 hours of driving. Without any rule, a driver whose vehicle model has an EV range filled is planned within the range less its reserve on sRoute 2T 1.0.19 or later (elsewhere listed in data.rule_notices as ev_range). Stops these rules leave out return with reason max_ride_time, latest_departure, group, incompatible_goods, deliveries_first or range. The three switches also accept true / false. Ignored unless Planning Rules is enabled for the account by the platform administrator: while it is off the object is accepted, not stored, and the route plans with the built-in defaults; the request still succeeds. Rules the chosen engine cannot apply are reported in the response as data.rule_notices. Phase P3 (Superroute plans these for the engines): merge_stops ({radius_m 0-1000, max_orders 2-50 default 10, same_window_only on | off}; [] or radius_m 0 = off; all three engines) sends orders whose stops lie within the radius as one stop and gives every order its own stop back; reload ({depot_addressbook_ids: address book ids of the business's warehouses or fulfilment centres, loading_minutes 0-240 default 15, max_reloads 1-5 default 1, slot_minutes 5-240 default 30}; [] = no reloads) on sRoute and sRoute 2 is approximated by sequential trips, planning the stops a first trip leaves out on further trips from the nearest chosen depot, and on sRoute 2T 1.0.20 or later is planned by the engine itself: each driver may go back to a chosen depot up to max_reloads times, unloading what was picked up and loading the next trip's deliveries, on the thorough solve time unless solve_time is set (rule notice solve_time_raised), and a depot whose address has loading_bays lets at most that many drivers load in each slot of slot_minutes; the reloads are stored with the run and returned as reload_stops by GET /v1/driver/routes/{routeId}/points; goods_class_vehicle_overrides ({driver id: goods class id}) fixes the goods class a vehicle carries when goods_class_separation is approximated on sRoute or sRoute 2; each breaks entry may carry skip_policy (if_no_intersection | if_route_ends_before_window_end): on sRoute and sRoute 2 a break the planned route makes unnecessary is left out after a first solve and the route solved again, and sRoute 2T 1.0.21 or later decides it while planning; and place_addressbook_ids (at most 10 address book ids; sRoute 2T 1.0.21 or later): the break is taken at one of those places, a detour the engine plans. On sRoute and sRoute 2, order_groups, goods_class_separation and use_all_vehicles on sRoute are approximated (reported as approximated in data.rule_notices), use_all_vehicles on sRoute 2 is its orders balance unless the route has its own balance_preset (then reported with reason balance_preset), and a vehicle model's EV range becomes the vehicle's max_distance. Orders' ready-for-dispatch time (dispatch_ready_at) is applied by sRoute 2T 1.0.20 or later (a delivery's goods are loaded no earlier, at the start or at a reload) and approximated on sRoute and sRoute 2; alternative delivery locations are approximated on sRoute and sRoute 2 (one picked before the solve) and chosen by sRoute 2T 1.0.21 or later among all of them (rule_notices delivery_alternatives on an older sRoute 2T); the stop is stored at the place chosen, the order's address is unchanged. From sRoute 2T 1.0.21 data.rule_notices may also carry reason place_unreachable (break places no driver can reach were left out) and precomputed_matrix for delivery_alternatives and break_places. A stop left out for its ready time returns with reason release_time, and one left out because every loading bay was taken with reason loading_bay. From sRoute 2T 1.0.20 data.rule_notices may also carry status adjusted (the rule was applied with a change): solve_time_raised, precomputed_matrix (depots that are no point of the precomputed road matrices were left out; status dropped when none was left), depot_unreachable, depot_limit (at most 20 reload options per driver) and shipment (ready times of pickup-and-delivery orders are not applied). Phase P5b: respect_schedules (on | off, default on; true / false accepted; all three engines) decides whether planning honours operating hours and holiday calendars, holiday calendar scopes included: order stops, and reload depots and break places whose address links operating hours or a holiday calendar; data.rule_notices may carry reason depot_closed (rule reload) and break_place_closed (rule break_places). Phase P6: live_solve_progress (on | off, default off; sRoute 2T 1.0.22 or later) shows the improving plan on the web routes list while the route is planned, with a Use current plan button; web only, the request and the plan written are unchanged.\n\n**Details:** Type `object` · Nullable.","properties":{"objective":{"type":"string","enum":["balanced","fastest","shortest","fewest_vehicles"],"description":"What the plan keeps as low as possible (sRoute, sRoute 2 and sRoute 2T). balanced: the engine default, driving time. fastest: driving time only. shortest: distance weighs far above time. fewest_vehicles: another vehicle is used only when it saves more than about two hours of driving. route_optimize_for still chooses the road network.\n\nAllowed values: `balanced` · `fastest` · `shortest` · `fewest_vehicles`.\n\n**Details:** Type `string`."},"lateness_tolerance_minutes":{"type":"integer","minimum":0,"maximum":120,"description":"sRoute 2T only. Minutes a stop may run past its time window, at a cost, instead of being left unassigned. 0 keeps time windows strict.\n\n**Details:** Type `integer` · min `0` · max `120`."},"preferred_driver":{"type":"string","enum":["off","low","normal","high"],"description":"sRoute 2T, and sRoute 2 from version 1.2.11 (where it steers which driver gets a stop, not the stop order). Prefer a driver of this build who delivered to the same recipient (same phone number, or the same email when there is no phone) within preferred_driver_days. low, normal and high let the preference cost about 5, 10 and 30 minutes of extra driving.\n\nAllowed values: `off` · `low` · `normal` · `high`.\n\n**Details:** Type `string`."},"preferred_driver_days":{"type":"integer","minimum":1,"maximum":365,"description":"sRoute 2T, and sRoute 2 from version 1.2.11. Delivery history window for preferred_driver, in days. Default 90.\n\n**Details:** Type `integer` · min `1` · max `365`."},"keep_assignments":{"type":"string","enum":["off","soft","strong"],"description":"sRoute 2T, and sRoute 2 from version 1.2.11. On rebuild and optimize, keep stops with their current driver: soft unless moving them saves driving, strong much harder (sRoute 2T replans with minimal-change balancing; sRoute 2 weighs a moved stop at 10 minutes of driving for soft and 30 for strong). Stops already delivered are always pinned on sRoute 2T rebuilds and optimizations.\n\nAllowed values: `off` · `soft` · `strong`.\n\n**Details:** Type `string`."},"solve_time":{"type":"string","enum":["fast","standard","thorough"],"description":"sRoute 2 (1.2.11 or later) and sRoute 2T (1.0.8 or later). How long the planner searches: fast returns sooner, standard is the engine default, thorough searches longer (sRoute 2 up to about 3.5 minutes, sRoute 2T up to 2 minutes). sRoute ignores it.\n\nAllowed values: `fast` · `standard` · `thorough`.\n\n**Details:** Type `string`."},"balance_strength":{"type":"string","enum":["off","low","normal","high"],"description":"sRoute 2 (1.2.11 or later) and sRoute 2T (1.0.8 or later). Scales the route's balance setting against driving time: off 0 (minimum balancing), low 0.5, normal 1 (engine default), high 2. sRoute ignores it.\n\nAllowed values: `off` · `low` · `normal` · `high`.\n\n**Details:** Type `string`."},"breaks":{"type":"array","maxItems":3,"description":"All engines. Driver breaks: each break of minutes length starts between window_from and window_to on the route date (clipped to the driver's working hours; a window before the start of a night shift falls on the next day). Stop arrival times include the break and it never becomes a stop. An empty list means no breaks and overrides the Route Settings default; omit the key to follow Route Settings.\n\n**Details:** Type `array`, items `object` · maxItems `3`.","items":{"type":"object","additionalProperties":false,"required":["window_from","window_to","minutes"],"properties":{"window_from":{"type":"string","pattern":"^([01]?\\d|2[0-3]):[0-5]\\d$","description":"**Required.**\n\nEarliest start of the break, HH:MM.\n\n**Details:** Type `string` · pattern `^([01]?\\d|2[0-3]):[0-5]\\d$`.\n\n**Example:** `11:00`.","examples":["11:00"]},"window_to":{"type":"string","pattern":"^([01]?\\d|2[0-3]):[0-5]\\d$","description":"**Required.**\n\nLatest start of the break, HH:MM, after window_from.\n\n**Details:** Type `string` · pattern `^([01]?\\d|2[0-3]):[0-5]\\d$`.\n\n**Example:** `14:00`.","examples":["14:00"]},"minutes":{"type":"integer","minimum":5,"maximum":240,"description":"**Required.**\n\nLength of the break in minutes.\n\n**Details:** Type `integer` · min `5` · max `240`.\n\n**Example:** `30`.","examples":[30]},"skip_policy":{"type":"string","enum":["if_no_intersection","if_route_ends_before_window_end"],"description":"Optional. When the planned route makes the break unnecessary: if_no_intersection skips it when the driver's working time does not reach its window; if_route_ends_before_window_end skips it when the route ends before the window closes. On sRoute and sRoute 2 (phase P3) the skipped breaks are left out after a first solve and the route is solved again; sRoute 2T 1.0.21 or later decides it while planning and the plan explanation lists the skipped breaks per driver (routes[].skipped_breaks). An older sRoute 2T is sent nothing (data.rule_notices break_skip_policy). Omitted: the break is always planned.\n\nAllowed values: `if_no_intersection` · `if_route_ends_before_window_end`.\n\n**Details:** Type `string`."},"place_addressbook_ids":{"type":"array","maxItems":10,"items":{"type":"integer","minimum":1,"description":"Place addressbook ids. Address component used for geocoding and delivery.\n\n**Details:** Type `integer` · min `1`."},"description":"Optional, sRoute 2T 1.0.21 or later. Address book ids of the business (at most 10) where the break may be taken: the engine plans the drive to one of them and back, and the planned break carries its place (route map, GET /v1/driver/routes/{routeId}/points breaks[].addressbook_id, name, latitude, longitude). Places at no point of precomputed road matrices, or that no driver can reach, are left out (data.rule_notices break_places with reason precomputed_matrix or place_unreachable); a break left without places is taken along the route. Not used when the route keeps the dispatcher's sequence. sRoute and sRoute 2 ignore it (data.rule_notices break_places). Omitted: stored exactly as before.\n\n**Details:** Type `array`, items `integer` · maxItems `10`.","examples":[[12,31]]}}}},"overtime_minutes":{"type":"integer","minimum":0,"maximum":240,"description":"sRoute 2T 1.0.10 or later. Minutes each driver may work past the end of the shift, used only when that serves a stop that would otherwise be left out or saves more driving than it costs. The driver's maximum working time grows by the same allowance. 0 (default) keeps the shift end strict.\n\n**Details:** Type `integer` · min `0` · max `240`."},"overtime_cost":{"type":"string","enum":["off","low","normal","high"],"description":"sRoute 2T 1.0.10 or later. What an hour of overtime costs, as seconds of driving: off 0, low 1800, normal 3600 (default), high 7200. Only matters with overtime_minutes above 0.\n\nAllowed values: `off` · `low` · `normal` · `high`.\n\n**Details:** Type `string`."},"familiar_zones":{"type":"string","enum":["off","soft"],"description":"sRoute 2T 1.0.10 or later. off (default): a driver's region group stays a hard rule, on every engine, as before. soft: the region skill is lifted and the drivers of a stop's region are preferred instead, so another driver may take the stop when that works out better.\n\nAllowed values: `off` · `soft`.\n\n**Details:** Type `string`."},"familiar_zones_strength":{"type":"string","enum":["low","normal","high"],"description":"sRoute 2T 1.0.10 or later, with familiar_zones soft. Soft cost of serving a stop outside its zone's drivers: low 150, normal 300 (default), high 900 seconds of driving.\n\nAllowed values: `low` · `normal` · `high`.\n\n**Details:** Type `string`."},"vip_must_serve":{"type":"string","enum":["off","on"],"description":"sRoute 2T 1.0.10 or later. on: stops of consignees marked VIP in Consignee Profiles (matched on the normalised phone or email) and orders whose own or channel priority is Emergency (70) or higher are dropped only when nothing else makes room. The build never fails because of it; a must-serve stop still left out is listed in route.plan_explanation.must_serve_unmet. true / false are accepted too.\n\nAllowed values: `off` · `on`.\n\n**Details:** Type `string`."},"deferrable_low_priority":{"type":"string","enum":["off","on"],"description":"sRoute 2T 1.0.10 or later. on: orders whose own or channel priority is Flexible (20) or lower (Hold) are dropped before any other stop and return unassigned with reason deferred. A stop that is also must-serve stays must-serve. true / false are accepted too.\n\nAllowed values: `off` · `on`.\n\n**Details:** Type `string`."},"breaks_during_wait":{"type":"string","enum":["off","on"],"description":"sRoute 2T 1.0.16 or later. on: when a driver arrives early and waits for a stop's time window, a driver break is taken during that wait when it does not make the stop later; off (default) keeps each break's timing as before. Sent to sRoute 2T as sroute2t.breaks_during_wait on build, rebuild, optimize and Live Replan; an older sRoute 2T, sRoute and sRoute 2 are sent nothing. true / false are accepted too.\n\nAllowed values: `off` · `on`.\n\n**Details:** Type `string`."},"max_ride_minutes":{"type":"integer","minimum":0,"maximum":1440,"description":"sRoute 2T 1.0.19 or later. Default longest ride, in minutes, of every pickup-and-delivery order without its own max_ride_minutes: from leaving the pickup (after its service) to the start of service at the delivery. 0 (default) sets no default; an order's own value still applies. Sent as sroute2t.max_ride_default (seconds), and each order's own value as sroute2t.max_ride_seconds; orders planned as a pickup or a delivery alone have no ride and are sent nothing.\n\n**Details:** Type `integer` · min `0` · max `1440`."},"latest_departure_minutes":{"type":"integer","minimum":0,"maximum":720,"description":"sRoute 2T 1.0.19 or later. Each driver with working hours leaves the start at most this many minutes after the shift start, on a build (a rebuild or optimize has no shift start). 0 (default) is off. Sent as sroute2t.latest_departure (epoch seconds per vehicle).\n\n**Details:** Type `integer` · min `0` · max `720`."},"order_groups":{"type":"string","enum":["off","on"],"description":"sRoute 2T 1.0.19 or later. on: orders that share a route_group_key ride the same vehicle, all of them or none (a stop left out for it returns with reason group). A key used by a single order of the route does nothing. Sent as sroute2t.groups. true / false are accepted too.\n\nAllowed values: `off` · `on`.\n\n**Details:** Type `string`."},"goods_class_separation":{"type":"string","enum":["off","on"],"description":"sRoute 2T 1.0.19 or later. on: orders whose goods classes are marked incompatible never share a vehicle (reason incompatible_goods). Sent as sroute2t.goods_classes and sroute2t.incompatible_classes, only when the route's orders hold an incompatible pair. true / false are accepted too.\n\nAllowed values: `off` · `on`.\n\n**Details:** Type `string`."},"deliveries_before_pickups":{"type":"string","enum":["off","on"],"description":"sRoute 2T 1.0.19 or later. on: on every route, delivery-only stops come before pickup-only stops; pickup-and-delivery orders may go anywhere (reason deliveries_first). Sent as sroute2t.deliveries_before_pickups. true / false are accepted too.\n\nAllowed values: `off` · `on`.\n\n**Details:** Type `string`."},"waiting_cost":{"type":"string","enum":["off","low","normal","high"],"description":"sRoute 2T 1.0.19 or later. What an hour spent waiting at stops for their time windows costs, in seconds of driving: low 900, normal 1800, high 3600; off (default) keeps waiting free. Sent as sroute2t.waiting_cost_per_hour.\n\nAllowed values: `off` · `low` · `normal` · `high`.\n\n**Details:** Type `string`."},"use_all_vehicles":{"type":"string","enum":["off","low","normal","high"],"description":"sRoute 2T 1.0.19 or later. Soft cost of each vehicle that serves nothing, in seconds of driving: low 1800, normal 3600, high 7200 (which cancels the fewest_vehicles objective); off (default) sends nothing. Never breaks a hard rule. Sent as sroute2t.use_all_vehicles_weight.\n\nAllowed values: `off` · `low` · `normal` · `high`.\n\n**Details:** Type `string`."},"merge_stops":{"type":"object","additionalProperties":false,"description":"All engines (phase P3, done by Superroute). Orders whose stops lie within radius_m of the first one are sent to the engine as one stop (setup once, services added up) and each order keeps its own stop on the route. Only jobs of the same kind with the same skills, priority, route group key and goods class merge; pickup-and-delivery orders, orders with delivery alternatives, stops already served on a re-plan and a kept sequence never do. An unassigned merged stop leaves every order in it unassigned with the same reason. [] or radius_m 0 switches merging off and overrides Route Settings; omit the key to follow Route Settings.\n\n**Details:** Type `object`.","properties":{"radius_m":{"type":"integer","minimum":0,"maximum":1000,"description":"Merge radius in metres; 0 = off.\n\n**Details:** Type `integer` · min `0` · max `1000`.\n\n**Example:** `30`.","examples":[30]},"max_orders":{"type":"integer","minimum":2,"maximum":50,"default":10,"description":"Most orders per merged stop.\n\n**Details:** Type `integer` · Default: `10` · min `2` · max `50`."},"same_window_only":{"type":"string","enum":["off","on"],"default":"off","description":"on: only stops with the same time window merge; off: the windows are intersected. true / false are accepted too.\n\nAllowed values: `off` · `on`.\n\n**Details:** Type `string` · Default: `off`."}}},"reload":{"type":"object","additionalProperties":false,"description":"sRoute and sRoute 2 (phase P3, approximate): when a solve leaves stops out, the vehicles it used return to their nearest depot, load for loading_minutes and plan the stops left on a next trip, up to max_reloads per vehicle; kept only when more orders are served; not applied on precomputed road matrices (road preferences or exclusion zones). sRoute 2T 1.0.20 or later plans the reloads itself: each vehicle may return to a chosen depot up to max_reloads times, planned on the thorough solve time unless solve_time is set; on precomputed road matrices only depots at a start, end or stop of the route are used. An older sRoute 2T is sent nothing and data.rule_notices lists reload. The reloads are returned as reload_stops by GET /v1/driver/routes/{routeId}/points. [] means no reloads and overrides Route Settings.\n\n**Details:** Type `object`.","properties":{"depot_addressbook_ids":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"integer","minimum":1,"description":"Depot addressbook ids. Address component used for geocoding and delivery.\n\n**Details:** Type `integer` · min `1`."},"description":"Address book ids of the business's warehouses or fulfilment centres; others are ignored.\n\n**Details:** Type `array`, items `integer` · minItems `1` · maxItems `10`."},"loading_minutes":{"type":"integer","minimum":0,"maximum":240,"default":15,"description":"Time spent loading at the depot.\n\n**Details:** Type `integer` · Default: `15` · min `0` · max `240`."},"max_reloads":{"type":"integer","minimum":1,"maximum":5,"default":1,"description":"Most reloads per vehicle.\n\n**Details:** Type `integer` · Default: `1` · min `1` · max `5`."},"slot_minutes":{"type":"integer","minimum":5,"maximum":240,"default":30,"description":"Optional, sRoute 2T 1.0.20 or later. The loading bay slot: at a depot whose address book entry has loading_bays, at most that many vehicles start loading in each slot of this length; a stop left out because every bay was taken returns with reason loading_bay. Ignored by sRoute and sRoute 2 (data.rule_notices lists loading_bays).\n\n**Details:** Type `integer` · Default: `30` · min `5` · max `240`."}}},"goods_class_vehicle_overrides":{"type":"object","additionalProperties":{"type":"integer","minimum":1,"description":"Goods class vehicle overrides. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer` · min `1`."},"description":"sRoute and sRoute 2 with goods_class_separation on (phase P3): driver id => the goods class that driver's vehicle carries in the partition Superroute plans with; drivers left out are shared out automatically by each class's load. The partition used is stored in the route's plan explanation (goods_class_partition). sRoute 2T separates classes itself and ignores it.\n\n**Details:** Type `object`.","examples":[{"701":5}]},"respect_schedules":{"type":"string","enum":["off","on"],"description":"Phase P5b, all three engines (Superroute applies it before planning). on (the default, how routes always planned): order stops closed on the route date by the operating hours or holiday calendars of their channel and address type are left out and the others get that day's opening as time window, holiday calendar scopes (country, subdivision, postcode, territory, address) are honoured, date overrides with special hours or extra open days count; a reload depot or break place whose address links operating hours or a holiday calendar is used only while open (sRoute 2T receives the depot's opening as reload.depots[].time_windows; rule notices depot_closed and break_place_closed). off: nothing is filtered or windowed by operating hours or holidays. true / false are accepted too.\n\nAllowed values: `off` · `on`.\n\n**Details:** Type `string`."},"live_solve_progress":{"type":"string","enum":["off","on"],"default":"off","description":"sRoute 2T 1.0.22 or later (phase P6; true / false accepted). on: the route is solved as an engine solve job, and while it is planned the web routes list shows the plan improving (distance, driving time, stops planned, unassigned, vehicles used) with a Use current plan button that stops the search and applies the best plan found so far. The request sent to the engine and the plan written are the same as with off. Web only in this phase: the build-route responses and APIs expose no progress. When the engine is already running its most solve jobs, or loses the job, the route is planned the usual way and data.rule_notices / the plan explanation carry reason solve_jobs_busy or solve_job_lost. sRoute and sRoute 2 ignore it (listed in data.rule_notices).\n\nAllowed values: `off` · `on`.\n\n**Details:** Type `string` · Default: `off`."}},"examples":[{"objective":"shortest","lateness_tolerance_minutes":10,"preferred_driver":"normal","preferred_driver_days":60,"keep_assignments":"soft","solve_time":"thorough","balance_strength":"high","breaks":[{"window_from":"11:00","window_to":"14:00","minutes":30,"skip_policy":"if_route_ends_before_window_end"}],"overtime_minutes":30,"overtime_cost":"normal","familiar_zones":"soft","familiar_zones_strength":"normal","vip_must_serve":"on","deferrable_low_priority":"on","breaks_during_wait":"on","max_ride_minutes":90,"latest_departure_minutes":30,"order_groups":"on","goods_class_separation":"on","deliveries_before_pickups":"on","waiting_cost":"low","use_all_vehicles":"normal","merge_stops":{"radius_m":30,"max_orders":10,"same_window_only":"off"},"reload":{"depot_addressbook_ids":[12],"loading_minutes":20,"max_reloads":2,"slot_minutes":30},"goods_class_vehicle_overrides":{"701":5}}]}}},"BuildRouteV2":{"type":"object","properties":{"drivers":{"type":"array","description":"Drivers. Field in the JSON request body.\n\n**Details:** Type `array`.","examples":[[{"id":2,"start_address":{"address_1":"2395 Madison","address_2":"Apt 4","city":"Montreal","province":"Quebec","country":"Canada","postcode":"H4B2T5","telephone":"555-5555"},"end_address":{"id":2,"address_1":"40d boul des sources","address_2":"","city":"Pointe Claire","province":"Quebec","country":"Canada","postcode":"H9S2H9","telephone":"555-6666"},"start_address_id":1,"end_address_id":2,"start_time":"09:00","end_time":"17:00","region_group_id":2001,"capacity":50,"max_distance":120,"skill_ids":[1,2]}]]},"route_name":{"type":"string","required":true,"description":"Route name. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `test`.","examples":["test"]},"route_date":{"type":"string","required":true,"description":"Route date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `string`.\n\n**Example:** `2021-03-14`.","examples":["2021-03-14"]},"serve_time":{"type":"integer","required":true,"description":"Serve time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","examples":[3]},"ppickup_time":{"type":"integer","required":false,"description":"Ppickup time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","examples":[3]},"balance_mode":{"type":"integer","description":"1: balance on number of orders. 2: balance on working hours. 3: without balance. 4: balanced within tolerance. 5: balanced by zone (compact non-crossing zones). 6: working hours within tolerance. 7: balanced by zone and working hours (compact non-crossing zones cut on time, corrected from measured working hours)\n\n**Details:** Type `integer`.","required":true,"examples":[1]},"balance_tolerance":{"type":"integer","description":"balance_mode 4 only: how far a driver's order count may sit from the average, as a percent (1-100). Ignored by the other balance modes. Defaults to the business route-settings value, then 15.\n\n**Details:** Type `integer`.","required":false,"examples":[15]},"load_check":{"type":"boolean","description":"Consider vehicle load (0/1). When 1, planning also constrains each driver by the assigned vehicle's cargo volume, load weight and maximum item length, in addition to the count-based capacity. Defaults to the business route-settings value.\n\n**Details:** Type `boolean`.","required":false,"examples":[false]},"package_processing_time":{"type":"integer","description":"package processing time in seconds\n\n**Details:** Type `integer`.\n\n**Example:** `30`.","required":true,"examples":[30]},"package_pickup_time":{"type":"integer","description":"package pickup time in seconds\n\n**Details:** Type `integer`.\n\n**Example:** `30`.","required":false,"examples":[30]},"need_approval":{"type":"integer","description":"Need approval after plan\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","required":true,"examples":[1]},"notify_at":{"type":"integer","minimum":0,"maximum":23,"description":"Hour (0-23) in the user time zone when advance email/SMS reminders should be sent. Leave null/omitted to allow any hour.\n\n**Details:** Type `integer` · min `0` · max `23`.\n\n**Example:** `9`.","examples":[9]},"notification_enabled":{"type":"boolean","description":"Master switch: enable all email/SMS notifications for this route. Defaults to true. Set to false to suppress every notification for this route, even when the global switch is on.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"advance_notification_enabled":{"type":"boolean","description":"Enable the pre-delivery advance reminder (day-before email/SMS) for this route. Defaults to true. Set to false to skip the day-before reminder while keeping other notifications.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`.\n\n**Example:** `1 (for multiple territory user)`.","examples":["1 (for multiple territory user)"]},"order_type":{"type":"string","description":"Order type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nEnum values (from deployed code):\n- `D` — Delivery\n- `P` — Pickup\n- `L` — Label Service\n- `P2P` — Peer to Peer\n- `S` — Storage Order\n- `M` — Moving Order\n- `SH` — Shipping Service\n- `SO` — Shipout\n- `LTL` — LTL Service\n- `I` — Instant Delivery\n\n**Details:** Type `string`.\n\n**Example:** `D,P,DP,DD,P2P (D:Delivery P:Pickup,DP:Pickup Step,DD:Delivery Step,P2P:Peer to Peer)`.","enum":["D","P","L","P2P","S","M","SH","SO","LTL","I"],"x-enumDescriptions":["Delivery","Pickup","Label Service","Peer to Peer","Storage Order","Moving Order","Shipping Service","Shipout","LTL Service","Instant Delivery"],"examples":["D,P,DP,DD,P2P (D:Delivery P:Pickup,DP:Pickup Step,DD:Delivery Step,P2P:Peer to Peer)"]},"order_batch":{"type":"string","description":"Order batch. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `W1,W2,W3`.","examples":["W1,W2,W3"]},"sorting_code":{"type":"string","description":"Sorting code. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `607,304,021`.","examples":["607,304,021"]},"label_code":{"type":"string","description":"Label code. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `X2,X3,X4`.","examples":["X2,X3,X4"]},"warehouse_id":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `integer`.\n\n**Example:** `12`.","examples":[12]},"max_distance":{"type":"integer","description":"Max distance. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `120`.","examples":[120]},"vehicle_type":{"type":"string","description":"1 (1: Car, 2: Truck, 3: Motorcycle, 4: Bicycle 5:Pedestrian nullable,default 1)\n\nVehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"],"examples":[1]}}},"BuildRoute":{"type":"object","properties":{"drivers":{"type":"array","description":"Drivers. Field in the JSON request body.\n\n**Details:** Type `array`.","examples":[[1]]},"route_name":{"type":"string","description":"Route name. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `test`.","examples":["test"]},"route_date":{"type":"date","description":"Route date. Calendar date (`YYYY-MM-DD`).\n\n**Details:** Type `date`.\n\n**Example:** `2021-03-14`.","examples":["2021-03-14"]},"serve_time":{"type":"integer","description":"Serve time. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","examples":[3]},"pickup_time":{"type":"integer","description":"pickup time in minutes\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","required":false,"examples":[3]},"package_processing_time":{"type":"integer","description":"package processing time in seconds\n\n**Details:** Type `integer`.\n\n**Example:** `30`.","required":false,"examples":[30]},"package_pickup_time":{"type":"integer","description":"package pickup time in seconds\n\n**Details:** Type `integer`.\n\n**Example:** `30`.","required":false,"examples":[30]},"order_number":{"type":"integer","description":"Order number. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `200`.","examples":[200]},"balance_mode":{"type":"integer","description":"1: balance on number of orders. 2: balance on working hours. 3: without balance. 4: balanced within tolerance. 5: balanced by zone (compact non-crossing zones). 6: working hours within tolerance. 7: balanced by zone and working hours (compact non-crossing zones cut on time, corrected from measured working hours)\n\n**Details:** Type `integer`.","examples":[1]},"balance_tolerance":{"type":"integer","description":"balance_mode 4 only: how far a driver's order count may sit from the average, as a percent (1-100). Ignored by the other balance modes. Defaults to the business route-settings value, then 15.\n\n**Details:** Type `integer`.","examples":[15]},"load_check":{"type":"boolean","description":"Consider vehicle load (0/1). When 1, planning also constrains each driver by the assigned vehicle's cargo volume, load weight and maximum item length, in addition to the count-based capacity. Defaults to the business route-settings value.\n\n**Details:** Type `boolean`.","examples":[false]},"territory_id":{"type":"integer","description":"Territory id.\n\n**Details:** Type `integer`.\n\n**Example:** `1 (for multiple territory user)`.","examples":["1 (for multiple territory user)"]},"order_type":{"type":"string","description":"Order type code stored on `orders.order_type` (except LTL which lives in `ltl_orders`).\n\nEnum values (from deployed code):\n- `D` — Delivery\n- `P` — Pickup\n- `L` — Label Service\n- `P2P` — Peer to Peer\n- `S` — Storage Order\n- `M` — Moving Order\n- `SH` — Shipping Service\n- `SO` — Shipout\n- `LTL` — LTL Service\n- `I` — Instant Delivery\n\n**Details:** Type `string`.\n\n**Example:** `D,P,DP,DD,P2P (D:Delivery P:Pickup,DP:Pickup Step,DD:Delivery Step,P2P:Peer to Peer)`.","enum":["D","P","L","P2P","S","M","SH","SO","LTL","I"],"x-enumDescriptions":["Delivery","Pickup","Label Service","Peer to Peer","Storage Order","Moving Order","Shipping Service","Shipout","LTL Service","Instant Delivery"],"examples":["D,P,DP,DD,P2P (D:Delivery P:Pickup,DP:Pickup Step,DD:Delivery Step,P2P:Peer to Peer)"]},"order_batch":{"type":"string","description":"Order batch. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `W1,W2,W3`.","examples":["W1,W2,W3"]},"sorting_code":{"type":"string","description":"Sorting code. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `123,234,221`.","examples":["123,234,221"]},"label_code":{"type":"string","description":"Label code. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `X2,X3,X4`.","examples":["X2,X3,X4"]},"warehouse_id":{"type":"integer","description":"Warehouse id used as the location / stock context.\n\n**Details:** Type `integer`.\n\n**Example:** `12`.","examples":[12]},"start_address_1":{"type":"integer","description":"Start address 1. Address component used for geocoding and delivery.\n\n**Details:** Type `integer`.\n\n**Example:** `3`.","examples":[3]},"end_address_1":{"type":"integer","description":"End address 1. Address component used for geocoding and delivery.\n\n**Details:** Type `integer`.\n\n**Example:** `2`.","examples":[2]},"region_group_1":{"type":"integer","description":"Region group 1. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `4 (for multiple territory user)`.","examples":["4 (for multiple territory user)"]},"start_time_1":{"type":"string","description":"Start time 1. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `9:00`.","examples":["9:00"]},"end_time_1":{"type":"string","description":"End time 1. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `17:00`.","examples":["17:00"]},"max_distance":{"type":"integer","description":"Max distance. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `120`.","examples":[120]},"vehicle_type":{"type":"string","description":"1 (1: Car, 2: Truck, 3: Motorcycle, 4: Bicycle 5:Pedestrian nullable,default 1)\n\nVehicle type id used for routing profiles. Source: `VehicleTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Car\n- `2` — Truck\n- `3` — Motorcycle\n- `4` — Bicycle\n- `5` — Pedestrian\n\n**Details:** Type `string`.","enum":[1,2,3,4,5],"x-enumDescriptions":["Car","Truck","Motorcycle","Bicycle","Pedestrian"],"examples":[1]},"notify_at":{"type":"integer","minimum":0,"maximum":23,"description":"Hour (0-23) in the user time zone when advance email/SMS reminders should be sent. Leave null/omitted to allow any hour.\n\n**Details:** Type `integer` · min `0` · max `23`.\n\n**Example:** `9`.","examples":[9]},"notification_enabled":{"type":"boolean","description":"Master switch: enable all email/SMS notifications for this route. Defaults to true. Set to false to suppress every notification for this route, even when the global switch is on.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"advance_notification_enabled":{"type":"boolean","description":"Enable the pre-delivery advance reminder (day-before email/SMS) for this route. Defaults to true. Set to false to skip the day-before reminder while keeping other notifications.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]}}},"OrderRate":{"type":"object","properties":{"type":{"type":"string","required":false,"description":"Order Type: D:delivery,P:Pickup,P2P:Peer to Peer\n\n**Details:** Type `string`.","examples":["D"]},"from_postcode":{"type":"string","required":false,"description":"From postcode. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `H9S2H9`.","examples":["H9S2H9"]},"from_country":{"type":"string","required":false,"description":"From country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"to_postcode":{"type":"string","required":true,"description":"**Required.**\n\nTo postcode. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `H4B2T5`.","examples":["H4B2T5"]},"to_country":{"type":"string","required":true,"description":"To country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"packages":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"number","description":"**Required.**\n\nWeight of the package in weight_unit.\n\n**Details:** Type `number`.\n\n**Example:** `1.234`.","examples":[1.234]},"width":{"type":"number","description":"**Required.**\n\nWidth of the package in dimension_unit.\n\n**Details:** Type `number` · pattern `^[0-9]+(\\.[0-9]{1,3})?$`.\n\n**Example:** `10.532`.","pattern":"^[0-9]+(\\.[0-9]{1,3})?$","examples":[10.532]},"height":{"type":"number","description":"**Required.**\n\nHeight of the package in dimension_unit.\n\n**Details:** Type `number` · pattern `^[0-9]+(\\.[0-9]{1,3})?$`.\n\n**Example:** `20.332`.","pattern":"^[0-9]+(\\.[0-9]{1,3})?$","examples":[20.332]},"length":{"type":"number","description":"**Required.**\n\nLength of the package in dimension_unit.\n\n**Details:** Type `number` · pattern `^[0-9]+(\\.[0-9]{1,3})?$`.\n\n**Example:** `15.232`.","pattern":"^[0-9]+(\\.[0-9]{1,3})?$","examples":[15.232]},"dimension_unit":{"type":"integer","enum":[1,2,3,4],"description":"Unit for the dimensions. 1: mm, 2: cm, 3: m, 4: inch\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `1`.","default":1,"examples":[1]},"weight_unit":{"type":"integer","enum":[1,2,3,4],"description":"Unit for the weight. 1: g, 2: kg, 3: oz, 4: lb\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `1`.","default":1,"examples":[1]}},"required":["weight","width","height","length"]},"description":"**Required.**\n\nLegacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"signature_option":{"type":"integer","enum":[0,1],"description":"Indicates if a signature is required. 0: No signature, 1: Signature required.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Default: `0`.","default":0,"x-enumDescriptions":["No / false / off","Yes / true / on"],"examples":[0]},"channel_id":{"type":["integer","null"],"description":"The ID of the channel. Default is null.\n\n**Details:** Type `integer|null`.","default":null,"examples":[null]},"fulfillment_center_id":{"type":["integer","null"],"description":"The ID of the fulfillment center. Default is null.\n\n**Details:** Type `integer|null`.","default":null,"examples":[null]}},"required":["to_postcode","packages"]},"OrderCreate":{"type":"object","properties":{"type":{"type":"string","enum":["D","P","P2P","I"],"description":"Order type. D=Delivery, P=Pickup, P2P=Peer to Peer, I=Instant Delivery. For I the validation is identical to P2P: sender_* fields are required (unless shipping_from id or shipping_from_code is provided) and need_pick_up is forced to 1. Instant orders enter the dispatch pool with status 44 (Waiting for Assignment) and are fulfilled by riders (manual or auto dispatch).\n\nAllowed values: `D` · `P` · `P2P` · `I`.\n\n**Details:** Type `string`.","examples":["D"]},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`.\n\n**Example:** `H9S2H9`.","examples":["H9S2H9"]},"street_number":{"type":"string","description":"Street number. Address component used for geocoding and delivery.\n\n**Details:** Type `string`.\n\n**Example:** `2667`.","examples":[2667]},"street_name":{"type":"string","description":"Street name. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `boul des sources`.","examples":["boul des sources"]},"apt":{"type":"string","description":"Apt. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `123`.","examples":[123]},"buzz_code":{"type":"string","description":"Buzz code. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `9393`.","examples":[9393]},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `altima-4`.","examples":["altima-4"]},"order_code":{"type":"string","description":"Order Code (max 5 characters, letters and numbers only)\n\n**Details:** Type `string` · maxLength `5` · pattern `^[A-Za-z0-9]*$`.\n\n**Example:** `ABC`.","maxLength":5,"pattern":"^[A-Za-z0-9]*$","examples":["ABC"]},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`.\n\n**Example:** `pointe-claire`.","examples":["pointe-claire"]},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`.\n\n**Example:** `QC`.","examples":["QC"]},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`.\n\n**Example:** `Canada`.","examples":["Canada"]},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `John`.","examples":["John"]},"company_name":{"type":["string","null"],"description":"Recipient (or pickup contact) company name.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Super Route`.","examples":["Super Route"]},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`.\n\n**Example:** `join@gmail.com`.","examples":["join@gmail.com"]},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`.\n\n**Example:** `5555555555`.","examples":[5555555555]},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`.\n\n**Example:** `customer note`.","examples":["customer note"]},"notification_language":{"type":"string","description":"Notification language. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `en`.","examples":["en"]},"need_pick_up":{"type":["integer","null"],"enum":[0,1,2,3,null],"description":"Pickup handling mode. `0` = no separate pickup, `1` = need pickup, `2` = inbound scan required, `3` = need batch pickup. Instant (`I`) / P2P force pickup semantics in the service layer.\n\nEnum values:\n- `0` — Pending\n- `1` — Completed\n- `2` — Failed\n- `3` — Cancelled\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `0 (no) or 1 (need pickup) or 2 (Inbound scan required) or 3 (need batch pickup)`.","x-enumDescriptions":["Pending","Completed","Failed","Cancelled"],"examples":["0 (no) or 1 (need pickup) or 2 (Inbound scan required) or 3 (need batch pickup)"]},"pin_verification_required":{"type":["integer","null"],"description":"Override PIN verification requirement for this order. null=Use Default, 0=Disabled, 1=Enabled\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","enum":[0,1,null],"x-enumDescriptions":["No / false / off","Yes / true / on"],"examples":[1]},"fulfillment_center_code":{"type":["string","null"],"description":"Fulfillment center code (unique_identifier from address book). If the code does not exist or is not a fulfillment center, it falls back to auto assignment and a warning is returned.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `WH001`.","examples":["WH001"]},"max_ride_minutes":{"type":["integer","null"],"minimum":1,"maximum":1440,"description":"Optional. Longest time in minutes the goods may be on board between pickup and delivery. Null clears it.\n\n**Details:** Type `integer` · Nullable · min `1` · max `1440`.\n\n**Example:** `90`.","examples":[90]},"dispatch_ready_at":{"type":["string","null"],"description":"Optional. When the goods are ready to leave the depot (Y-m-d H:i:s). Not the same as ready for customer pickup. Null clears it.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-20 07:30:00`.","examples":["2026-09-20 07:30:00"]},"route_group_key":{"type":["string","null"],"maxLength":64,"description":"Optional. Orders with the same key are planned on the same vehicle. Null clears it.\n\n**Details:** Type `string` · Nullable · maxLength `64`.\n\n**Example:** `STORE-42`.","examples":["STORE-42"]},"goods_class_id":{"type":["integer","null"],"description":"Optional. Goods class id of the business (Settings > Goods Classes); orders of incompatible classes never share a vehicle. Wins over goods_class. Null clears it.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `3`.","examples":[3]},"goods_class":{"type":["string","null"],"description":"Optional. Goods class name, alternative to goods_class_id. An unknown class is rejected with HTTP 400.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Food`.","examples":["Food"]},"delivery_alternatives":{"type":["array","null"],"maxItems":10,"items":{"type":"object","properties":{"addressbook_id":{"type":["integer","null"],"description":"Address book entry of the order's business (or of its customer). Either this or latitude/longitude is required.\n\n**Details:** Type `integer` · Nullable."},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `43.6532`.","examples":[43.6532]},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `-79.3832`.","examples":[-79.3832]},"address":{"type":["string","null"],"maxLength":500,"description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string` · Nullable · maxLength `500`.\n\n**Example:** `200 Front St W, Toronto`.","examples":["200 Front St W, Toronto"]},"time_window_start":{"type":["string","null"],"description":"Y-m-d H:i:s; send together with time_window_end\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-20 09:00:00`.","examples":["2026-09-20 09:00:00"]},"time_window_end":{"type":["string","null"],"description":"Y-m-d H:i:s; after time_window_start\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-09-20 12:00:00`.","examples":["2026-09-20 12:00:00"]}}},"description":"Optional. Alternative delivery locations; the order is delivered at its own address or at one of these. Replaces the stored list when sent; an empty list clears it; omitted leaves it unchanged.\n\n**Details:** Type `array`, items `object` · Nullable · maxItems `10`."},"address_1":{"type":["string","null"],"description":"Primary street address line for the delivery/pickup stop (required unless a structured street_number+street_name form is used, or shipping_from resolves the address).\n\n**Details:** Type `string` · Nullable."},"address_2":{"type":["string","null"],"description":"Secondary address line (apartment, unit, suite).\n\n**Details:** Type `string` · Nullable."},"combine_address":{"type":["boolean","null"],"description":"When true, address_1 and address_2 are concatenated before geocoding. Default false.\n\n**Details:** Type `boolean` · Nullable."},"order_channel_code":{"type":["string","null"],"description":"Order channel code. Must be enabled for Local Delivery; when the customer has a channel whitelist, the code must be assigned to that customer. Empty / omit uses the business Default Channel when allowed.\n\n**Details:** Type `string` · Nullable."},"self_pickup":{"type":["integer","null"],"description":"Self-pickup flag. `0` = normal delivery (default), `1` = self-pickup. Only accepted when the account is allowed to place self-pickup orders.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Default: `0` · Nullable.","enum":[0,1,null],"default":0,"x-enumDescriptions":["No / false / off","Yes / true / on"]},"customer_id":{"type":["integer","null"],"description":"Customer id under the authenticated business. Client/employee only. Prefer this over `customer_code` when both would apply.\n\n**Details:** Type `integer` · Nullable."},"customer_code":{"type":["string","null"],"description":"Customer code under the authenticated business. Client/employee only. Ignored when `customer_id` is provided.\n\n**Details:** Type `string` · Nullable."},"packages":{"type":["integer","null"],"description":"Legacy package count. Prefer `packagesDetail` for real dimensions/weights. When `packagesDetail` is present it takes precedence.\n\n**Details:** Type `integer` · Nullable."},"packagesDetail":{"type":["array","null"],"description":"Per-package details for this order. Each element is a `PackageItem` (`ref`, dimensions, weight, units, value, notes, optional `id` on update). On **create**: every entry is inserted as a new package (omit `id`). On **modify**: entries with `id` are updated, entries without `id` are created, and existing packages whose ids are **omitted** from this array are deleted — deletion is refused (HTTP 400) once the order has been dispatched/processed or a package has tracking history; always include the ids of packages you want to keep. Package `ref` values must be unique within the order when provided.\n\nPer-package details (`PackageItem` array). Create inserts every entry; modify updates by `id`, creates without `id`, and deletes packages whose ids are omitted (blocked after dispatch / tracking history).\n\n**Details:** Type `array` · Nullable.","items":{"$ref":"#/components/schemas/PackageItem","description":"Packages detail. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `PackageItem`."}},"shipping_from":{"type":["integer","null"],"description":"Address-book / warehouse id used as the sender location. When set, most `sender_*` fields can be omitted and are filled from that record. Leave null to supply sender_* manually, or use `shipping_from_code` to name the same record by its Unique Identifier.\n\n**Details:** Type `integer` · Nullable."},"shipping_from_code":{"type":["string","null"],"description":"Address-book / warehouse **Unique Identifier** used as the sender location — the same record `shipping_from` names by id, addressed by the code shown in the address book instead. Supply either parameter; when both are set `shipping_from` wins. Resolved within your own business, so the code only has to be unique there.\n\n**Details:** Type `string` · Nullable."},"sender_name":{"type":["string","null"],"description":"Sender contact name. Required for P2P/Instant (and when shipping_from is empty) on create.\n\n**Details:** Type `string` · Nullable."},"sender_address_1":{"type":["string","null"],"description":"Sender street address line 1. Required when shipping_from is empty for order types that need a sender.\n\n**Details:** Type `string` · Nullable."},"sender_address_2":{"type":["string","null"],"description":"Sender street address line 2 (optional).\n\n**Details:** Type `string` · Nullable."},"sender_address_type":{"type":["integer","null"],"description":"Sender address type. `1` = commercial, `2` = residential.\n\nAllowed values: `1` · `2`.\n\n**Details:** Type `integer` · Nullable.","enum":[1,2,null]},"sender_postcode":{"type":["string","null"],"description":"Sender postal / ZIP code. Required when shipping_from is empty for order types that need a sender.\n\n**Details:** Type `string` · Nullable."},"sender_city":{"type":["string","null"],"description":"Sender city. Required when shipping_from is empty for order types that need a sender.\n\n**Details:** Type `string` · Nullable."},"sender_province":{"type":["string","null"],"description":"Sender province / state. Required in regions that require province (see area config); optional in some locales (e.g. UK).\n\n**Details:** Type `string` · Nullable."},"sender_country":{"type":["string","null"],"description":"Sender country (ISO code or name accepted by the address pipeline). Required when shipping_from is empty for order types that need a sender.\n\n**Details:** Type `string` · Nullable."},"sender_company_name":{"type":["string","null"],"description":"Sender company name (optional).\n\n**Details:** Type `string` · Nullable."},"sender_email":{"type":["string","null"],"description":"Sender email (optional).\n\n**Details:** Type `string` · Nullable."},"sender_telephone":{"type":["string","null"],"description":"Sender phone number (optional).\n\n**Details:** Type `string` · Nullable."},"sender_buzz_code":{"type":["string","null"],"description":"Sender buzzer / entry code (optional).\n\n**Details:** Type `string` · Nullable."},"pickup_instruction":{"type":["string","null"],"description":"Instructions shown to the driver for the pickup stop.\n\n**Details:** Type `string` · Nullable."},"delivery_instruction":{"type":["string","null"],"description":"Instructions shown to the driver for the delivery stop.\n\n**Details:** Type `string` · Nullable."},"signature_option":{"type":["integer","null"],"description":"Signature required flag. `0` = not required (default), `1` = required.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Default: `0` · Nullable.","enum":[0,1,null],"default":0,"x-enumDescriptions":["No / false / off","Yes / true / on"]},"insurance_option":{"type":["integer","null"],"description":"Insurance flag. `0` = no insurance (default), `1` = insure. When 0, `insurance_value` is ignored.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Default: `0` · Nullable.","enum":[0,1,null],"default":0,"x-enumDescriptions":["No / false / off","Yes / true / on"]},"insurance_value":{"type":["number","null"],"description":"Order-level insurance value (2 decimal places). Only used when `insurance_option` is 1.\n\n**Details:** Type `number` · Nullable."},"scheduled_date":{"type":["string","null"],"description":"Requested delivery date (`YYYY-MM-DD`). Omit for “as soon as possible”. When set, delivery is not earlier than this date.\n\n**Details:** Type `string` · Nullable."},"time_window_start":{"type":["string","null"],"description":"Delivery time window start (`YYYY-MM-DD HH:MM:SS`). Must be paired with `time_window_end`.\n\n**Details:** Type `string` · Nullable."},"time_window_end":{"type":["string","null"],"description":"Delivery time window end (`YYYY-MM-DD HH:MM:SS`). Must be paired with `time_window_start`.\n\n**Details:** Type `string` · Nullable."},"pickup_date":{"type":["string","null"],"description":"Requested pickup date (`YYYY-MM-DD`). Omit for “as soon as possible”.\n\n**Details:** Type `string` · Nullable."},"pickup_time_window_start":{"type":["string","null"],"description":"Pickup time window start. Must be paired with `pickup_time_window_end`.\n\n**Details:** Type `string` · Nullable."},"pickup_time_window_end":{"type":["string","null"],"description":"Pickup time window end. Must be paired with `pickup_time_window_start`.\n\n**Details:** Type `string` · Nullable."},"service_time":{"type":["number","null"],"description":"On-site service time at the delivery stop in minutes. `0` / omit = use route configuration default.\n\n**Details:** Type `number` · Nullable."},"pickup_service_time":{"type":["number","null"],"description":"On-site service time at the pickup stop in minutes. `0` / omit = use route configuration default.\n\n**Details:** Type `number` · Nullable."},"pickup_time":{"type":["number","null"],"description":"Legacy alias for pickup service time in minutes (same meaning as `pickup_service_time` on some clients).\n\n**Details:** Type `number` · Nullable."},"skills":{"type":["string","null"],"description":"Comma-separated skill ids required to fulfil this order (e.g. `\"1,2,3\"`).\n\n**Details:** Type `string` · Nullable."},"latitude":{"type":["number","null"],"description":"Stop latitude. When both latitude and longitude are provided they pin the geocode; otherwise the address is geocoded.\n\n**Details:** Type `number` · Nullable."},"longitude":{"type":["number","null"],"description":"Stop longitude. Pair with `latitude`.\n\n**Details:** Type `number` · Nullable."},"order_batch":{"type":["string","null"],"description":"Optional batch label grouping orders for planning / reporting (free text).\n\n**Details:** Type `string` · Nullable."},"auto_deduplication":{"type":["integer","null"],"description":"When `1`, create/update deduplicates by package `ref` / external tracking number. `0` = no dedup (default unless the business setting forces it).\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","enum":[0,1,null],"x-enumDescriptions":["No / false / off","Yes / true / on"]},"strict_duplicate_check":{"type":["integer","null"],"description":"When `1`, a detected duplicate returns HTTP 409 instead of the legacy `200` + `result:false` envelope. Default `0`.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","enum":[0,1,null],"x-enumDescriptions":["No / false / off","Yes / true / on"]},"allow_dropoff":{"type":["integer","null"],"description":"Allow safe drop-off without recipient present. `0` = no, `1` = yes.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Nullable.","enum":[0,1,null],"x-enumDescriptions":["No / false / off","Yes / true / on"]},"a_scan_at":{"type":["integer","null"],"description":"Optional Unix timestamp of an A-scan / intake event to stamp on create.\n\n**Details:** Type `integer` · Nullable."},"sorting_code":{"type":["string","null"],"description":"Sorting / hub routing code applied to the order when known.\n\n**Details:** Type `string` · Nullable."},"external_customer":{"type":["object","null"],"description":"Upstream customer identity for multi-system integration. When present, `id`, `name`, `email`, and `system_code` are required.\n\n**Details:** Type `object` · Nullable.","properties":{"id":{"type":"string","description":"Upstream customer id in the external system.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Upstream customer display name.\n\n**Details:** Type `string`."},"email":{"type":"string","description":"Upstream customer email.\n\n**Details:** Type `string`."},"system_code":{"type":"string","description":"Code identifying the external system that owns this customer id.\n\n**Details:** Type `string`."}}},"surcharges":{"type":["array","null"],"description":"Optional surcharge selections. Each item needs `code` (or `surcharge_id`) and the selected option values.\n\n**Details:** Type `array`, items `object` · Nullable.","items":{"type":"object","properties":{"code":{"type":"integer","description":"Surcharge code / id.\n\n**Details:** Type `integer`."},"surcharge_id":{"type":"integer","description":"Surcharge id (alias used by some clients).\n\n**Details:** Type `integer`."},"quantity":{"type":["number","null"],"description":"Quantity for quantity-based surcharges.\n\n**Details:** Type `number` · Nullable."},"selected_values":{"type":"array","description":"Selected option values for this surcharge.\n\n**Details:** Type `array`.","items":{"description":"Selected values. Element of a list or map in the request/response payload."}},"selected_option":{"description":"Single selected option (legacy alias).\n\n**Details:** Nullable."},"selected_options":{"type":"array","description":"Selected options list (legacy alias).\n\n**Details:** Type `array`.","items":{"description":"Selected options. Element of a list or map in the request/response payload."}}}}}}},"OrderPictureUpload":{"type":"object","properties":{"orderId":{"$ref":"#/components/schemas/orderId","description":"Superroute order id (`orders.id`).\n\n**Details:** Schema `$ref` → `orderId`."},"type":{"type":"string","description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`.\n\n**Example:** `photo`.","examples":["photo"]},"image":{"type":"string","description":"Image. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAAAXN`.","examples":["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAAAAXN"]},"imageUrl":{"type":"string","description":"Image url. Absolute or relative URL.\n\n**Details:** Type `string`.\n\n**Example:** `http://abc.com/a.png`.","examples":["http://abc.com/a.png"]},"gps_tracking_id":{"type":"integer","description":"Gps tracking id. Identifier referencing the related record.\n\n**Details:** Type `integer`.","examples":[null]},"operation_event_id":{"type":"integer","description":"Operation event id. Identifier referencing the related record.\n\n**Details:** Type `integer`.","examples":[null]},"tracking_event_id":{"type":"integer","description":"Optional. The tracking event the proof documents (a delivered / picked-up / failed-attempt event of this order). When omitted it is derived from operation_event_id, or from the order's latest outcome event; a proof uploaded before the outcome is reported is tied to that outcome when the driver reports it.\n\n**Details:** Type `integer`.","examples":[null]}}},"OrderPictureDelete":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]}}},"WMSConnect":{"type":"object","properties":{"type":{"type":"string","required":true,"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`.\n\n**Example:** `HYC`.","examples":["HYC"]},"name":{"type":"string","required":true,"description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `HYC Test`.","examples":["HYC Test"]},"unique_identifier":{"type":"string","required":true,"description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `hyc_test`.","examples":["hyc_test"]},"rewrite":{"type":"integer","required":false,"description":"Rewrite. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `0`.","examples":[0]},"config":{"type":"object","properties":{"apikey":{"type":"string","required":true,"description":"Apikey. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `12345678`.","examples":[12345678]}},"description":"Config. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"WMSConnectUpdate":{"type":"object","properties":{"id":{"type":"integer","required":true,"description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `7`.","examples":[7]},"type":{"type":"string","required":false,"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string`.\n\n**Example:** `HYC`.","examples":["HYC"]},"name":{"type":"string","required":false,"description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `HYC Test`.","examples":["HYC Test"]},"unique_identifier":{"type":"string","required":false,"description":"Unique identifier. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `hyc_test`.","examples":["hyc_test"]},"config":{"type":"object","properties":{"apikey":{"type":"string","required":false,"description":"Apikey. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `12345678`.","examples":[12345678]}},"description":"Config. Field in the JSON request body.\n\n**Details:** Type `object`."},"status":{"type":"integer","required":false,"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]}}},"WMSConnectDelete":{"type":"object","properties":{"id":{"type":"integer","required":true,"description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `7`.","examples":[7]}}},"GetShippingLabel":{"type":"object","properties":{"id":{"type":"string","required":true,"description":"depends type ,could be order id,ref or tracking number.\n\n**Details:** Type `string`.\n\n**Example:** `17341`.","examples":[17341]},"type":{"type":"string","required":false,"description":"could be TRACKING_NUMBER,REF or ORDER_ID, if not defined ,will be TRACKING_NUMBER by default.\n\n**Details:** Type `string`.","examples":["TRACKING_NUMBER"]},"packages":{"type":"integer","required":false,"description":"how many packages in this order,if not defined ,will be use order current setting ,as usually ,default package will be 1,if this order has two packages, please give 2, system will be print 2 shipping label for this order.\n\n**Details:** Type `integer`.","examples":[1]},"hide_sender_address":{"type":"integer","required":false,"description":"whether to hide sender address on the label, 0 for no, 1 for yes. If not defined, defaults to 0 (do not hide). Does not follow the user's web UI preference.\n\n**Details:** Type `integer`.","examples":[0]},"hide_receiver_address":{"type":"integer","required":false,"description":"whether to hide receiver address on the label, 0 for no, 1 for yes. If not defined, defaults to 0 (do not hide). Does not follow the user's web UI preference.\n\n**Details:** Type `integer`.","examples":[0]}}},"addressbook":{"type":"object"},"GetStopNumber":{"type":"object","properties":{"route_id":{"type":"string","required":true,"description":"route id.\n\n**Details:** Type `string`.\n\n**Example:** `365`.","examples":[365]},"type":{"type":"string","required":true,"description":"could be TRACKING_NUMBER,REF or ORDER_ID of orders.\n\n**Details:** Type `string`.","examples":["ref"]},"sub_route_count":{"type":"integer","required":true,"description":"count by sub route or not.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]}}},"VerifyScan":{"type":"object","properties":{"route_id":{"type":"string","required":true,"description":"route id.\n\n**Details:** Type `string`.\n\n**Example:** `365`.","examples":[365]},"ref":{"type":"string","required":true,"description":"Order id, ref, tracking number or external tracking number of the scanned package.\n\n**Details:** Type `string`.\n\n**Example:** `20304`.","examples":[20304]},"count_by_sub_route":{"type":"integer","required":false,"description":"1 to count progress within the driver's leg only; 0 (default) for the whole route.\n\n**Details:** Type `integer`.","examples":[0]}}},"PostReplaceDriver":{"type":"object","properties":{"routeId":{"type":"integer","required":true,"description":"route id.\n\n**Details:** Type `integer`.\n\n**Example:** `365`.","examples":[365]},"fromDriverId":{"type":"integer","required":true,"description":"from driver Id\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"toDriverId":{"type":"integer","required":true,"description":"to driver Id\n\n**Details:** Type `integer`.\n\n**Example:** `222`.","examples":[222]}}},"RouteStatusUpdate":{"type":"object","properties":{"routeId":{"type":"integer","description":"Route id (`routes.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"gps_tracking_id":{"type":"integer","description":"Gps tracking id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]}}},"ValidateRefOrderId":{"type":"object","properties":{"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `abc`.","examples":["abc"]}}},"Alliance":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Regional Delivery Alliance`.","examples":["Regional Delivery Alliance"]},"code":{"type":"string","description":"8-character unique alliance code\n\n**Details:** Type `string`.\n\n**Example:** `AB12CD34`.","examples":["AB12CD34"]},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Alliance for regional delivery partners`.","examples":["Alliance for regional delivery partners"]},"owner_client_id":{"type":"integer","description":"Owner client id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"join_policy":{"type":"string","enum":["open","invite_only","approval"],"description":"Allowed values: `open` · `invite_only` · `approval`.\n\n**Details:** Type `string`.","examples":["approval"]},"status":{"type":"string","enum":["active","suspended","dissolved"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `active` · `suspended` · `dissolved`.\n\n**Details:** Type `string`.","examples":["active"]},"settings":{"type":["object","null"],"description":"Settings. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"created_at":{"type":"string","format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"updated_at":{"type":"string","format":"date-time","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"owner":{"$ref":"#/components/schemas/AllianceOwner","description":"Owner. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `AllianceOwner`."},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/AlliancePermission","description":"Permissions. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AlliancePermission`."},"description":"Permissions. Field in the JSON request body.\n\n**Details:** Type `array`."}}},"AllianceCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"**Required.**\n\nAlliance name (max 255 characters)\n\n**Details:** Type `string`.\n\n**Example:** `Regional Delivery Alliance`.","examples":["Regional Delivery Alliance"]},"description":{"type":"string","description":"Optional description (max 1000 characters)\n\n**Details:** Type `string`.\n\n**Example:** `Alliance for regional delivery partners`.","examples":["Alliance for regional delivery partners"]},"join_policy":{"type":"string","enum":["open","invite_only","approval"],"default":"approval","description":"How new members can join\n\nAllowed values: `open` · `invite_only` · `approval`.\n\n**Details:** Type `string` · Default: `approval`."}}},"AllianceUpdate":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `Updated Alliance Name`.","examples":["Updated Alliance Name"]},"description":{"type":["string","null"],"description":"Free-text description.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Updated description`.","examples":["Updated description"]},"join_policy":{"type":"string","enum":["open","invite_only","approval"],"description":"Allowed values: `open` · `invite_only` · `approval`.\n\n**Details:** Type `string`."}}},"AllianceOwner":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `123`.","examples":[123]},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`.\n\n**Example:** `ABC Logistics`.","examples":["ABC Logistics"]},"email":{"type":"string","description":"Account email address.\n\n**Details:** Type `string`.\n\n**Example:** `admin@abc-logistics.com`.","examples":["admin@abc-logistics.com"]}}},"AllianceMember":{"type":"object","properties":{"id":{"type":"integer","description":"Alliance member record ID\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"alliance_id":{"type":"integer","description":"Alliance id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"client_id":{"type":"integer","description":"Client id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `456`.","examples":[456]},"role":{"type":"string","enum":["owner","admin","member"],"description":"Allowed values: `owner` · `admin` · `member`.\n\n**Details:** Type `string`.","examples":["member"]},"status":{"type":"string","enum":["pending","active","left"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pending` · `active` · `left`.\n\n**Details:** Type `string`.","examples":["active"]},"invited_by":{"type":["integer","null"],"description":"Client ID of inviter (null if joined via code)\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `123`.","examples":[123]},"approved_by":{"type":["integer","null"],"description":"Approved by. Field in the JSON request body.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `123`.","examples":[123]},"joined_at":{"type":["string","null"],"format":"date-time","description":"Joined at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"created_at":{"type":"string","format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"client":{"$ref":"#/components/schemas/AllianceOwner","description":"Client. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `AllianceOwner`."},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/AllianceMemberPermission","description":"Permissions. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AllianceMemberPermission`."},"description":"Permissions. Field in the JSON request body.\n\n**Details:** Type `array`."}}},"AllianceMembership":{"type":"object","description":"Alliance membership info returned in my alliances list","properties":{"alliance":{"$ref":"#/components/schemas/Alliance","description":"Alliance. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `Alliance`."},"role":{"type":"string","enum":["owner","admin","member"],"description":"Allowed values: `owner` · `admin` · `member`.\n\n**Details:** Type `string`.","examples":["member"]},"status":{"type":"string","enum":["pending","active"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pending` · `active`.\n\n**Details:** Type `string`.","examples":["active"]},"joined_at":{"type":["string","null"],"format":"date-time","description":"Joined at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/AllianceMemberPermission","description":"Permissions. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `AllianceMemberPermission`."},"description":"Permissions. Field in the JSON request body.\n\n**Details:** Type `array`."},"membership_id":{"type":"integer","description":"Membership id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `5`.","examples":[5]},"is_invitation":{"type":"boolean","description":"True if this is a pending invitation\n\n**Details:** Type `boolean`.","examples":[false]},"inviter":{"description":"Inviter. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `AllianceOwner` · Nullable.","oneOf":[{"$ref":"#/components/schemas/AllianceOwner"},{"type":"null"}]}}},"AlliancePermission":{"type":"object","description":"Alliance-level permission setting","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"alliance_id":{"type":"integer","description":"Alliance id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"permission_type":{"type":"string","description":"Type of permission (tracking_view, order_view, etc.)\n\n**Details:** Type `string`.","examples":["tracking_view"]},"is_enabled":{"type":"boolean","description":"Is enabled. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`.","examples":[true]},"constraints":{"type":["object","null"],"description":"Optional constraints for the permission\n\n**Details:** Type `object` · Nullable."},"created_at":{"type":"string","format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"updated_at":{"type":"string","format":"date-time","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}}},"AllianceMemberPermission":{"type":"object","description":"Member-level permission setting (share/receive)","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"alliance_member_id":{"type":"integer","description":"Alliance member id. Identifier referencing the related record.\n\n**Details:** Type `integer`.\n\n**Example:** `1`.","examples":[1]},"permission_type":{"type":"string","description":"Permission type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`.\n\n**Example:** `tracking_view`.","examples":["tracking_view"]},"grant_type":{"type":"string","enum":["share","receive"],"description":"share = allow others to see my data, receive = allow me to see others' data\n\nAllowed values: `share` · `receive`.\n\n**Details:** Type `string`.","examples":["share"]},"is_enabled":{"type":"boolean","description":"Is enabled. Boolean flag controlling this behaviour (`true`/`false` or `1`/`0` depending on the endpoint).\n\n**Details:** Type `boolean`.","examples":[true]},"created_at":{"type":"string","format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"updated_at":{"type":"string","format":"date-time","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."}}},"RiderOrder":{"type":"object","properties":{"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"ref":{"type":"string","description":"Ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"status_id":{"type":"integer","description":"Internal orders_status_id\n\nNumeric status id. For order endpoints this is `orders_status_id` (`OrdersStatusInput`).\n\n**Details:** Type `integer`."},"stage":{"type":"string","enum":["need_pickup","picking_up","picked_up","delivering","delivered","cancelled","failed"],"description":"Allowed values: `need_pickup` · `picking_up` · `picked_up` · `delivering` · `delivered` · `cancelled` · `failed`.\n\n**Details:** Type `string`."},"tracking_number":{"type":"string","description":"Superroute or carrier tracking number.\n\n**Details:** Type `string`."},"packages":{"type":"integer","description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `integer`."},"pickup":{"type":"object","properties":{"status":{"type":"string","enum":["TODO","DOING","DONE","FAILED","CANCELLED"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `TODO` · `DOING` · `DONE` · `FAILED` · `CANCELLED`.\n\n**Details:** Type `string`."},"contact_name":{"type":"string","description":"Contact name. Human-readable label.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"after":{"type":["string","null"],"description":"ISO-8601 window start (business timezone)\n\n**Details:** Type `string` · Nullable."},"before":{"type":["string","null"],"description":"ISO-8601 window end (business timezone)\n\n**Details:** Type `string` · Nullable."}},"description":"Pickup. Field in the JSON request body.\n\n**Details:** Type `object`."},"dropoff":{"type":"object","properties":{"status":{"type":"string","enum":["TODO","DOING","DONE","FAILED","CANCELLED"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `TODO` · `DOING` · `DONE` · `FAILED` · `CANCELLED`.\n\n**Details:** Type `string`."},"contact_name":{"type":"string","description":"Contact name. Human-readable label.\n\n**Details:** Type `string`."},"telephone":{"type":"string","description":"Phone number in international or local form accepted by the account locale.\n\n**Details:** Type `string`."},"address":{"type":"string","description":"Address. Address component used for geocoding and delivery.\n\n**Details:** Type `string`."},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"after":{"type":["string","null"],"description":"ISO-8601 window start (business timezone)\n\n**Details:** Type `string` · Nullable."},"before":{"type":["string","null"],"description":"ISO-8601 window end (business timezone)\n\n**Details:** Type `string` · Nullable."},"note":{"type":"string","description":"Note. Free-text note.\n\n**Details:** Type `string`."}},"description":"Dropoff. Field in the JSON request body.\n\n**Details:** Type `object`."},"created_at":{"type":["string","null"],"description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string` · Nullable."}}},"PartnerLockerLocation":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}}},"PartnerLockerDeliveryPackageResult":{"type":"object","properties":{"sequence":{"type":"integer","description":"Sequence. Field in the JSON request body.\n\n**Details:** Type `integer`."},"external_package_id":{"type":["string","null"],"description":"External package id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"string","enum":["requested","reserved","allocated","opened","confirmed","failed","cancelled","picked_up"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `requested` · `reserved` · `allocated` · `opened` · `confirmed` · `failed` · `cancelled` · `picked_up`.\n\n**Details:** Type `string`."},"failure_code":{"type":["string","null"],"description":"Failure code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"inventory_id":{"type":["integer","null"],"description":"Inventory id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"associated_package_group_item_id":{"type":["integer","null"],"description":"Associated package group item id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"final_shelf_id":{"type":["integer","null"],"description":"Final shelf id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"final_grid_id":{"type":["integer","null"],"description":"Final grid id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"final_shelf_code":{"type":["string","null"],"description":"Shelf code of the cabinet the package finally landed in (e.g. \"L1\").\n\n**Details:** Type `string` · Nullable."},"final_compartment_number":{"type":["string","null"],"description":"Hardware door number of the compartment the package finally landed in.\n\n**Details:** Type `string` · Nullable."},"final_pickup_locker_number":{"type":["integer","null"],"description":"Pickup Locker Number of that compartment, counted top-to-bottom within a column then left-to-right, starting at 1.\n\n**Details:** Type `integer` · Nullable."},"final_pickup_locker_code":{"type":["string","null"],"description":"Human-readable compartment label \"{final_shelf_code}-{final_pickup_locker_number}\" (e.g. \"L1-3\"), the numbering printed on the cabinet.\n\n**Details:** Type `string` · Nullable."},"smart_locker_log_id":{"type":["integer","null"],"description":"Smart locker log id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."}}},"PartnerLockerWebhookDeliverySummary":{"type":"object","description":"Masked delivery state for the latest outbound webhook event. Signing secrets and response bodies are never returned.","properties":{"configured":{"type":"boolean","description":"Configured. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"event_id":{"type":["string","null"],"description":"Event id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"event_type":{"type":["string","null"],"description":"Event type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"enum":["pending","processing","retrying","delivered","not_configured","dead_letter","failed",null],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pending` · `processing` · `retrying` · `delivered` · `not_configured` · `dead_letter` · `failed`.\n\n**Details:** Type `string` · Nullable."},"attempt_count":{"type":"integer","description":"Attempt count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"Next attempt at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"last_http_status":{"type":["integer","null"],"description":"Last http status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `integer` · Nullable."},"last_error_code":{"type":["string","null"],"description":"Last error code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"delivered_at":{"type":["string","null"],"format":"date-time","description":"Delivered at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."}}},"PartnerLockerNotificationSummary":{"type":"object","description":"Recipient notification state with only a masked destination.","properties":{"channel":{"type":"string","enum":["email","sms"],"description":"Allowed values: `email` · `sms`.\n\n**Details:** Type `string`."},"recipient_mask":{"type":"string","description":"Recipient mask. Field in the JSON request body.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["pending","processing","retrying","sent","skipped","failed"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pending` · `processing` · `retrying` · `sent` · `skipped` · `failed`.\n\n**Details:** Type `string`."},"attempt_count":{"type":"integer","description":"Attempt count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"error_code":{"type":["string","null"],"description":"Error code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"Next attempt at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"sent_at":{"type":["string","null"],"format":"date-time","description":"Sent at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."}}},"PartnerLockerEventSummary":{"type":"object","properties":{"event_id":{"type":"string","description":"Event id. Identifier referencing the related record.\n\n**Details:** Type `string`."},"event_type":{"type":"string","description":"Event type. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"attempt_count":{"type":"integer","description":"Attempt count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"last_http_status":{"type":["integer","null"],"description":"Last http status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `integer` · Nullable."},"last_error_code":{"type":["string","null"],"description":"Last error code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"occurred_at":{"type":["string","null"],"format":"date-time","description":"When the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string`, format `date-time` · Nullable."},"delivered_at":{"type":["string","null"],"format":"date-time","description":"Delivered at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."}}},"PartnerLockerOutboundWebhookEvent":{"type":"object","description":"Outbound partner event. Verify X-Webhook-Signature as base64(HMAC-SHA256(secret, timestamp + '\\n' + delivery_id + '\\n' + raw_request_body)). X-Webhook-Id is stable across retries; X-Webhook-Delivery-Id is unique per attempt. Also verify the timestamp tolerance and X-Webhook-Content-Digest before processing. Sandbox (mock cabinet) events use the same envelope and signature but carry livemode=false, an event_id prefixed PLE-MOCK-, and the X-Webhook-Test: 1 request header; they are posted to the endpoint's sandbox URL when one is configured, otherwise to the production URL. carrier_package.distribution.* events describe a pre-advised carrier package on a distribution order to the location the carrier named; they carry no delivery task, and data holds package_no, carrier_reference_number, member_number, carrier_order_id, batch, distribution {order_id, order_ref, status, loaded_at?, delivered_at?, shelved_at?, reason?}, origin {id, name}, destination {id, name} and, for shelved, location {grid_id, grid_code, shelf_code}. Only carriers with a provider account receive them.","required":["event_id","event_type","livemode","occurred_at","data"],"properties":{"event_id":{"type":"string","description":"**Required.**\n\nStable logical event identifier retained across retries. Sandbox (mock cabinet) events are prefixed PLE-MOCK-; live events are prefixed PLE-.\n\n**Details:** Type `string`."},"event_type":{"type":"string","enum":["partner_locker.delivery.doors_opened","partner_locker.delivery.delivered","partner_locker.pickup.completed","partner_locker.delivery.failed","partner_locker.delivery.expired","partner_locker.delivery.cancelled","partner_locker.delivery.correction_reopened","partner_locker.delivery.code_rotated","carrier_package.distribution.created","carrier_package.distribution.loaded","carrier_package.distribution.delivered","carrier_package.distribution.shelved","carrier_package.distribution.removed"],"description":"**Required.**\n\nAllowed values: `partner_locker.delivery.doors_opened` · `partner_locker.delivery.delivered` · `partner_locker.pickup.completed` · `partner_locker.delivery.failed` · `partner_locker.delivery.expired` · `partner_locker.delivery.cancelled` · `partner_locker.delivery.correction_reopened` · `partner_locker.delivery.code_rotated` · `carrier_package.distribution.created` · `carrier_package.distribution.loaded` · `carrier_package.distribution.delivered` · `carrier_package.distribution.shelved` · `carrier_package.distribution.removed`.\n\n**Details:** Type `string`."},"livemode":{"type":"boolean","description":"**Required.**\n\ntrue for production cabinet events; false for sandbox (mock cabinet) events. Sandbox requests additionally carry the X-Webhook-Test: 1 header.\n\n**Details:** Type `boolean`."},"occurred_at":{"type":"string","format":"date-time","description":"**Required.**\n\nWhen the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string`, format `date-time`."},"data":{"type":"object","properties":{"delivery_no":{"type":"string","description":"Delivery no. Field in the JSON request body.\n\n**Details:** Type `string`."},"external_order_id":{"type":"string","description":"Merchant / upstream order reference stored on the Superroute order.\n\n**Details:** Type `string`."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"pickup_status":{"type":"string","description":"Pickup status. Status value for this resource. When an enum is listed, only those values are accepted.\n\n**Details:** Type `string`."},"requested_package_count":{"type":"integer","description":"Requested package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"actual_package_count":{"type":"integer","description":"Actual package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"failed_package_count":{"type":"integer","description":"Failed package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"picked_up_package_count":{"type":"integer","description":"Picked up package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"partial_delivery":{"type":"boolean","description":"Partial delivery. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"delivery_mode":{"type":"string","enum":["standard","grouped"],"description":"Placement policy of the task (standard when created before the field existed).\n\nAllowed values: `standard` · `grouped`.\n\n**Details:** Type `string`."},"confirmed_by":{"type":["string","null"],"enum":["courier_terminal","partner_api","door_close","timeout_door_closed","console",null],"description":"delivered only. Which path settled the deposit: courier_terminal (courier pressed confirm on the locker screen), partner_api (remote confirm call), door_close (remote open settled by the cabinet reporting every opened door closed), timeout_door_closed (confirmation window lapsed with all doors verified closed), console (operator console).\n\nAllowed values: `courier_terminal` · `partner_api` · `door_close` · `timeout_door_closed` · `console`.\n\n**Details:** Type `string` · Nullable."},"split_from_delivery_no":{"type":["string","null"],"description":"Parent delivery_no when this task is the automatic follow-up of a partially delivered grouped task.\n\n**Details:** Type `string` · Nullable."},"split_delivery_no":{"type":["string","null"],"description":"delivery_no of the automatic follow-up created for the packages this grouped task left undelivered (delivered event).\n\n**Details:** Type `string` · Nullable."},"pickup_code":{"type":["string","null"],"description":"Present for the doors_opened and delivered events. The recipient pickup code is allocated the moment delivery doors open and stays identical through settlement; it only becomes usable for pickup once the courier confirms the deposit (the delivered event).\n\n**Details:** Type `string` · Nullable."},"location":{"$ref":"#/components/schemas/PartnerLockerLocation","description":"Location. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `PartnerLockerLocation`."},"packages":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer","description":"Sequence. Field in the JSON request body.\n\n**Details:** Type `integer`."},"external_package_id":{"type":["string","null"],"description":"External package id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"failure_code":{"type":["string","null"],"description":"Failure code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"shelf_id":{"type":"integer","description":"Present on the delivered event: shelf holding the deposited package.\n\n**Details:** Type `integer`."},"grid_id":{"type":"integer","description":"Present on the delivered event: grid id of the deposited compartment.\n\n**Details:** Type `integer`."},"pickup_locker_number":{"type":["integer","null"],"description":"Present on the delivered event: Pickup Locker Number (column-major display number).\n\n**Details:** Type `integer` · Nullable."},"pickup_locker_code":{"type":["string","null"],"description":"Present on the delivered event: Pickup Locker Code \"{shelf_code}-{pickup_locker_number}\" (e.g. \"L1-3\") — the label the recipient is told to go to. Null when the compartment has no pickup number.\n\n**Details:** Type `string` · Nullable."},"compartment_number":{"type":"string","description":"Present on the delivered event: hardware door/board number.\n\n**Details:** Type `string`."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"rotation":{"type":"object","description":"Present only for the code_rotated event. Names which code was replaced and when — the new code itself is never carried by a webhook; it is revealed only in the direct rotation API response.\n\n**Details:** Type `object`.","properties":{"code_type":{"type":"string","enum":["access","pickup"],"description":"Allowed values: `access` · `pickup`.\n\n**Details:** Type `string`."},"rotated_at":{"type":"string","format":"date-time","description":"Rotated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time`."},"recipient_notified":{"type":"boolean","description":"Whether the rotation re-sent the recipient notification with the new pickup code.\n\n**Details:** Type `boolean`."}}},"correction":{"type":"object","description":"Present only for the correction_reopened event.\n\n**Details:** Type `object`.","properties":{"channel":{"type":"string","enum":["device","api"],"description":"Where the correction reopen was triggered from.\n\nAllowed values: `device` · `api`.\n\n**Details:** Type `string`."},"reopened_count":{"type":"integer","description":"Reopened count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"failed_count":{"type":"integer","description":"Failed count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"compartments":{"type":"array","items":{"type":"object","properties":{"package_sequence":{"type":"integer","description":"Package sequence. Field in the JSON request body.\n\n**Details:** Type `integer`."},"grid_id":{"type":"integer","description":"Superroute grid id of the reopened compartment.\n\n**Details:** Type `integer`."},"pickup_locker_number":{"type":["integer","null"],"description":"Pickup Locker Number (column-major display number).\n\n**Details:** Type `integer` · Nullable."},"pickup_locker_code":{"type":["string","null"],"description":"Pickup Locker Code \"{shelf_code}-{pickup_locker_number}\" (e.g. \"L1-3\") — the label the recipient is told to go to. Null when the compartment has no pickup number.\n\n**Details:** Type `string` · Nullable."},"compartment_number":{"type":"string","description":"Compartment number. Field in the JSON request body.\n\n**Details:** Type `string`."}}},"description":"Compartments. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"opening":{"type":"object","description":"Present only for the doors_opened event. Emitted whenever compartment doors open for a delivery attempt, whether the courier used the locker screen or the API, including reassignment re-openings.\n\n**Details:** Type `object`.","properties":{"attempt_id":{"type":"integer","description":"Attempt id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"attempt_no":{"type":"integer","description":"Attempt no. Field in the JSON request body.\n\n**Details:** Type `integer`."},"opened_count":{"type":"integer","description":"Opened count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"failed_count":{"type":"integer","description":"Failed count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"partial":{"type":"boolean","description":"Partial. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"groups":{"type":"array","items":{"type":"object","properties":{"shelf_name":{"type":"string","description":"Shelf name. Human-readable label.\n\n**Details:** Type `string`."},"locker_identifier":{"type":"string","description":"Locker identifier. Field in the JSON request body.\n\n**Details:** Type `string`."},"compartments":{"type":"array","items":{"type":"object","properties":{"package_sequence":{"type":"integer","description":"Package sequence. Field in the JSON request body.\n\n**Details:** Type `integer`."},"compartment_number":{"type":"string","description":"Hardware door/board number.\n\n**Details:** Type `string`."},"grid_id":{"type":"integer","description":"Superroute grid id of the opened compartment.\n\n**Details:** Type `integer`."},"pickup_locker_number":{"type":["integer","null"],"description":"Pickup Locker Number: sequential display number counted top-to-bottom within a column, then left to right.\n\n**Details:** Type `integer` · Nullable."},"pickup_locker_code":{"type":["string","null"],"description":"Pickup Locker Code \"{shelf_code}-{pickup_locker_number}\" (e.g. \"L1-3\") — the label the recipient is told to go to. Null when the compartment has no pickup number.\n\n**Details:** Type `string` · Nullable."}}},"description":"Compartments. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"description":"Groups. Field in the JSON request body.\n\n**Details:** Type `array`, items `object`."}}},"package_no":{"type":["string","null"],"description":"carrier_package.distribution.* only: {carrier_setting_id}-{sequence}.\n\n**Details:** Type `string` · Nullable."},"distribution":{"type":["object","null"],"description":"carrier_package.distribution.* only.\n\n**Details:** Type `object` · Nullable.","properties":{"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"order_ref":{"type":"string","description":"Order ref. Field in the JSON request body.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["pending_route","routed","in_transit","delivered","shelved","removed"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pending_route` · `routed` · `in_transit` · `delivered` · `shelved` · `removed`.\n\n**Details:** Type `string`."},"loaded_at":{"type":["string","null"],"format":"date-time","description":"Loaded at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"delivered_at":{"type":["string","null"],"format":"date-time","description":"Delivered at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"shelved_at":{"type":["string","null"],"format":"date-time","description":"Shelved at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"reason":{"type":["string","null"],"description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string` · Nullable."}}},"origin":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}},"description":"Origin. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"destination":{"type":["object","null"],"properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."}},"description":"Destination. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."}},"description":"**Required.**\n\nData. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"ThirdPartyDeliveryOutboundWebhookEvent":{"type":"object","description":"Outbound package-delivery webhook pushed to a third-party delivery provider (courier). Covers the delivery assignment lifecycle: delivery.assignment.created (an order was assigned to the provider), delivery.assignment.handed_over (all packages physically handed over) and delivery.assignment.cancelled (the platform withdrew the assignment; data.reason is cancelled, fallback_to_self_delivery or reassigned). Signing scheme is identical to partner locker webhooks: verify X-Webhook-Signature as base64(HMAC-SHA256(secret, timestamp + '\\n' + delivery_id + '\\n' + raw_request_body)) using the X-Webhook-Timestamp and X-Webhook-Delivery-Id headers, check X-Webhook-Content-Digest, and reject stale timestamps. X-Webhook-Id is stable across retries - use it for idempotency. Endpoints are configured per provider (independently from the Smart Locker webhook) in the provider portal Webhook Settings page or by the platform operator under Third-Party Delivery > Providers > Webhooks. Failed deliveries are retried with exponential backoff for up to 7 attempts before dead-lettering. A signed test (mock) event can be sent from the webhook settings pages at any time; test requests carry the X-Webhook-Test: 1 header, an event_id prefixed TEST-, and \"test\": true inside data. The signing secret can be auto-generated or set to a custom value by the provider or the platform operator.","required":["event_id","event_type","occurred_at","data"],"properties":{"event_id":{"type":"string","description":"**Required.**\n\nStable logical event identifier retained across retries.\n\n**Details:** Type `string`."},"event_type":{"type":"string","enum":["delivery.assignment.created","delivery.assignment.handed_over","delivery.assignment.cancelled"],"description":"**Required.**\n\nAllowed values: `delivery.assignment.created` · `delivery.assignment.handed_over` · `delivery.assignment.cancelled`.\n\n**Details:** Type `string`."},"occurred_at":{"type":"string","format":"date-time","description":"**Required.**\n\nWhen the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string`, format `date-time`."},"data":{"type":"object","properties":{"assignment_no":{"type":"string","description":"Assignment no. Field in the JSON request body.\n\n**Details:** Type `string`."},"assignment_status":{"type":"string","enum":["assigned","pulled","accepted","rejected","fallback_to_self_delivery","cancelled"],"description":"Allowed values: `assigned` · `pulled` · `accepted` · `rejected` · `fallback_to_self_delivery` · `cancelled`.\n\n**Details:** Type `string`."},"order_id":{"type":"integer","description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer`."},"order_ref":{"type":["string","null"],"description":"Order ref. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"external_order_number":{"type":["string","null"],"description":"External order number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"reason":{"type":["string","null"],"description":"Only on delivery.assignment.cancelled: cancelled, fallback_to_self_delivery or reassigned.\n\n**Details:** Type `string` · Nullable."},"packages":{"type":"array","items":{"type":"object","properties":{"tracking_number":{"type":["string","null"],"description":"Superroute or carrier tracking number.\n\n**Details:** Type `string` · Nullable."},"external_tracking_number":{"type":["string","null"],"description":"Carrier or upstream tracking number on a package.\n\n**Details:** Type `string` · Nullable."},"third_party_tracking_number":{"type":["string","null"],"description":"Third party tracking number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."}}},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."}},"description":"**Required.**\n\nData. Field in the JSON request body.\n\n**Details:** Type `object`.","examples":[{"assignment_no":"TPD20260730091500ABC123","assignment_status":"assigned","order_id":88231,"order_ref":"SO-100234","packages":[{"tracking_number":"TRK-1001","external_tracking_number":"EXT-1001"}]}]}}},"PartnerLockerDeliveryResult":{"type":"object","properties":{"delivery_no":{"type":"string","description":"Delivery no. Field in the JSON request body.\n\n**Details:** Type `string`."},"external_order_id":{"type":"string","description":"Merchant / upstream order reference stored on the Superroute order.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["draft","active","at_locker","opening","awaiting_confirmation","failed_retryable","failed_attention","delivered","picked_up","expired","cancelled","failed"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nEnum values:\n- `draft` — Draft assignment\n- `active` — Active at locker network\n- `at_locker` — Parcel is at the locker\n- `opening` — Door open in progress\n- `awaiting_confirmation` — Waiting for confirmation\n- `failed_retryable` — Failed but may be retried\n- `failed_attention` — Failed — needs manual attention\n- `delivered` — Delivered into locker\n- `picked_up` — Picked up by recipient\n- `expired` — Expired without pickup\n- `cancelled` — Cancelled\n- `failed` — Terminal failure\n\n**Details:** Type `string`.","x-enumDescriptions":["Draft assignment","Active at locker network","Parcel is at the locker","Door open in progress","Waiting for confirmation","Failed but may be retried","Failed — needs manual attention","Delivered into locker","Picked up by recipient","Expired without pickup","Cancelled","Terminal failure"]},"pickup_status":{"type":"string","enum":["not_ready","ready","partial","completed"],"description":"Allowed values: `not_ready` · `ready` · `partial` · `completed`.\n\n**Details:** Type `string`."},"requested_package_count":{"type":"integer","description":"Requested package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"actual_package_count":{"type":"integer","description":"Actual package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"failed_package_count":{"type":"integer","description":"Failed package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"partial_delivery":{"type":"boolean","description":"Partial delivery. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"associated_package_group_id":{"type":["integer","null"],"description":"Associated package group id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"pickup_code":{"type":["string","null"],"description":"The recipient pickup code, minted when the task is created and returned to an authorized provider for as long as the task can still be picked up (active through delivered / partially picked up). It is the one code the open response and the doors_opened / delivered webhooks carry; it becomes usable at the cabinet once the driver confirms the deposit. Null once the task is cancelled, expired, failed or fully picked up.\n\n**Details:** Type `string` · Nullable."},"ready_package_count":{"type":"integer","description":"Ready package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"remaining_package_count":{"type":"integer","description":"Remaining package count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"picked_up_at":{"type":["string","null"],"format":"date-time","description":"Picked up at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"webhook_delivery_summary":{"$ref":"#/components/schemas/PartnerLockerWebhookDeliverySummary","description":"Webhook delivery summary. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `PartnerLockerWebhookDeliverySummary`."},"notification_summary":{"type":"array","items":{"$ref":"#/components/schemas/PartnerLockerNotificationSummary","description":"Notification summary. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `PartnerLockerNotificationSummary`."},"description":"Notification summary. Field in the JSON request body.\n\n**Details:** Type `array`."},"event_timeline":{"type":"array","items":{"$ref":"#/components/schemas/PartnerLockerEventSummary","description":"Event timeline. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `PartnerLockerEventSummary`."},"description":"Event timeline. Field in the JSON request body.\n\n**Details:** Type `array`."},"access_code":{"type":["string","null"],"description":"Access code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"masked_access_code":{"type":["string","null"],"description":"Masked access code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"used_location_id":{"type":["integer","null"],"description":"Used location id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"delivered_location":{"$ref":"#/components/schemas/PartnerLockerLocation","description":"Delivered location. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `PartnerLockerLocation`."},"packages":{"type":"array","items":{"$ref":"#/components/schemas/PartnerLockerDeliveryPackageResult","description":"Packages. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `PartnerLockerDeliveryPackageResult`."},"description":"Legacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"external_driver_id":{"type":["string","null"],"description":"External driver id. Identifier referencing the related record.\n\n**Details:** Type `string` · Nullable."},"recipient_channel":{"type":"string","enum":["phone","email"],"description":"Allowed values: `phone` · `email`.\n\n**Details:** Type `string`."},"platform_scope_group_id":{"type":"integer","description":"Platform scope group id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"partner_scope_group_id":{"type":["integer","null"],"description":"Partner scope group id. Identifier referencing the related record.\n\n**Details:** Type `integer` · Nullable."},"access_mode":{"type":"string","enum":["scope_any","restricted_locations"],"description":"Partner locker scope access mode.\n\nEnum values (from deployed code):\n- `scope_any` — Any locker in the partner scope may be used\n- `restricted_locations` — Only listed locations in the scope may be used\n\n**Details:** Type `string`.","x-enumDescriptions":["Any locker in the partner scope","Only listed locations"]},"is_mock":{"type":"boolean","description":"True when the delivery was created with mock: true and may only use the provider mock lockers.\n\n**Details:** Type `boolean`."},"restricted_location_ids":{"type":"array","items":{"type":"integer","description":"Restricted location ids. Element of a list or map in the request/response payload.\n\n**Details:** Type `integer`."},"description":"Restricted location ids. List of identifiers for the related records.\n\n**Details:** Type `array`, items `integer`."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"reservation_expires_at":{"type":["string","null"],"format":"date-time","description":"Reservation expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"cancelled_at":{"type":["string","null"],"format":"date-time","description":"Cancelled at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"expired_at":{"type":["string","null"],"format":"date-time","description":"Expired at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"failure_code":{"type":["string","null"],"description":"Failure code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable."},"reservation":{"type":["object","null"],"properties":{"location_id":{"type":"integer","description":"Location id. Identifier referencing the related record.\n\n**Details:** Type `integer`."},"reserved_count":{"type":"integer","description":"Reserved count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"status":{"type":"string","description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string`."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."}},"description":"Reservation. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."},"created_at":{"type":["string","null"],"format":"date-time","description":"Created at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Updated at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"delivery_mode":{"type":"string","enum":["standard","grouped"],"description":"The placement policy chosen at creation. Tasks created before the field existed read standard.\n\nAllowed values: `standard` · `grouped`.\n\n**Details:** Type `string`."},"split_from_delivery_no":{"type":["string","null"],"description":"delivery_no of the grouped delivery this task was split from after a partial delivery; null otherwise.\n\n**Details:** Type `string` · Nullable."},"split_delivery_no":{"type":["string","null"],"description":"delivery_no of the follow-up delivery automatically created for the packages this grouped delivery left undelivered; null when none was created.\n\n**Details:** Type `string` · Nullable."}}},"PartnerLockerDeliveryEnvelope":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"$ref":"#/components/schemas/PartnerLockerDeliveryResult","description":"Data. Field in the JSON request body.\n\n**Details:** Schema `$ref` → `PartnerLockerDeliveryResult`."}}},"PartnerLockerDeliveryListEnvelope":{"type":"object","properties":{"result":{"type":"boolean","description":"Result. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`."},"message":{"type":"string","description":"Message. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/PartnerLockerDeliveryResult","description":"Deliveries. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `PartnerLockerDeliveryResult`."},"description":"Deliveries. Field in the JSON request body.\n\n**Details:** Type `array`."},"pagination":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page. Field in the JSON request body.\n\n**Details:** Type `integer`."},"last_page":{"type":"integer","description":"Last page. Field in the JSON request body.\n\n**Details:** Type `integer`."},"per_page":{"type":"integer","description":"Number of items returned per page.\n\n**Details:** Type `integer`."},"total":{"type":"integer","description":"Total. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}},"description":"Pagination. Field in the JSON request body.\n\n**Details:** Type `object`."}},"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object`."}}},"RiderFailureReason":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"reason":{"type":"string","description":"Human-readable reason for the action (failure, cancellation, reassignment, etc.).\n\n**Details:** Type `string`."}}},"WarehouseMobileEnvelope":{"type":"object","properties":{"result":{"type":"boolean","description":"**Required.**\n\nResult. Field in the JSON request body.\n\n**Details:** Type `boolean`."},"code":{"type":"string","description":"**Required.**\n\nStable machine code for this resource.\n\n**Details:** Type `string`."},"message":{"type":"string","description":"**Required.**\n\nMessage. Free-text note.\n\n**Details:** Type `string`."},"data":{"type":["object","null"],"additionalProperties":true,"description":"Data. Field in the JSON request body.\n\n**Details:** Type `object` · Nullable."}},"required":["result","code","message"]},"WarehouseMobileOperation":{"type":"object","properties":{"warehouse_id":{"type":"integer","description":"**Required.**\n\nWarehouse id used as the location / stock context.\n\n**Details:** Type `integer`.\n\n**Example:** `276`.","examples":[276]},"search":{"type":"string","description":"**Required.**\n\nFree-text search filter applied to the primary label fields of this resource.\n\n**Details:** Type `string`.\n\n**Example:** `SR10000001`.","examples":["SR10000001"]},"operation_id":{"type":"string","format":"uuid","description":"Operation id. Identifier referencing the related record.\n\n**Details:** Type `string`, format `uuid`.\n\n**Example:** `6ba7b810-9dad-11d1-80b4-00c04fd430c8`.","examples":["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]},"carrier_id":{"type":["integer","null"],"description":"Putaway and route outbound only: the carrier a member-numbered pre-advised package belongs to. A member number identifies a parcel only within its carrier, so it is matched only when this is given.\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `12`.","examples":[12]}},"required":["warehouse_id","search"]},"PartnerLockerScopeLocation":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"name":{"type":"string","description":"Human-readable name.\n\n**Details:** Type `string`."},"code":{"type":["string","null"],"description":"Stable unique location code from the platform registry.\n\n**Details:** Type `string` · Nullable."},"address_1":{"type":"string","description":"Primary street line (street number + street name).\n\n**Details:** Type `string`."},"address_2":{"type":["string","null"],"description":"Secondary line (unit / apt).\n\n**Details:** Type `string` · Nullable."},"city":{"type":"string","description":"City / locality.\n\n**Details:** Type `string`."},"province":{"type":"string","description":"Province / state / region.\n\n**Details:** Type `string`."},"country":{"type":"string","description":"ISO country code or country name accepted by the address pipeline.\n\n**Details:** Type `string`."},"postcode":{"type":"string","description":"Postal / ZIP code.\n\n**Details:** Type `string`."},"latitude":{"type":["number","null"],"description":"Latitude. Geographic latitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"longitude":{"type":["number","null"],"description":"Longitude. Geographic longitude in decimal degrees.\n\n**Details:** Type `number` · Nullable."},"locker_count":{"type":"integer","description":"Locker count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."},"online_locker_count":{"type":["integer","null"],"description":"Reachable cabinets at this location. Null when the request did not ask for device state (online_only=false without include_lockers).\n\n**Details:** Type `integer` · Nullable."},"offline_locker_count":{"type":["integer","null"],"description":"Cabinets the provider reports as offline. Null when device state was not requested.\n\n**Details:** Type `integer` · Nullable."},"unknown_locker_count":{"type":["integer","null"],"description":"Cabinets whose provider could not be reached. Null when device state was not requested.\n\n**Details:** Type `integer` · Nullable."},"lockers":{"type":"array","description":"Cabinets at this location. Present only when include_lockers=true.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"shelf_id":{"type":"integer","description":"Cabinet identity used by the delivery API and webhooks.\n\n**Details:** Type `integer`."},"device_id":{"type":"string","description":"Provider-side device id.\n\n**Details:** Type `string`."},"name":{"type":"string","description":"Cabinet code as shown on the terminal.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["online","offline","unknown"],"description":"Live device state. 'unknown' means the provider could not be reached.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `online` · `offline` · `unknown`.\n\n**Details:** Type `string`."},"online":{"type":"boolean","description":"True only when status is online.\n\n**Details:** Type `boolean`."},"mock":{"type":"boolean","description":"Whether this is a sandbox cabinet.\n\n**Details:** Type `boolean`."},"compartment_count":{"type":"integer","description":"Compartment count. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `integer`."}}}},"platform_scope_group_ids":{"type":"array","items":{"type":"integer","description":"Platform scope group ids. Geographic latitude in decimal degrees.\n\n**Details:** Type `integer`."},"description":"Active platform grants that cover this location under the current filter.\n\n**Details:** Type `array`, items `integer`."}}},"LabelServiceOrder":{"type":"object","required":["shipping_method","postcode","address_1","city","country","name","telephone"],"description":"Request body for labelservice rate/submitOrder. province is additionally required outside no-province areas. Send either the flat weight/length/width/height fields (single package) or the packages array (multi-package).","properties":{"shipping_method":{"type":["integer","null"],"description":"**Required.**\n\nShipping method id (required)\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"postcode":{"type":["string","null"],"description":"**Required.**\n\nRecipient postcode\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `H4E3R3`.","examples":["H4E3R3"]},"address_1":{"type":["string","null"],"description":"**Required.**\n\nRecipient address line 1\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `6701 RUE HADLEY`.","examples":["6701 RUE HADLEY"]},"address_2":{"type":["string","null"],"description":"Recipient address line 2\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `123`.","examples":[123]},"apt":{"type":["string","null"],"description":"Apt/unit (fallback for address_2)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `5B`.","examples":["5B"]},"street_number":{"type":["string","null"],"description":"Street number (with street_name, fallback for address_1)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `6701`.","examples":[6701]},"street_name":{"type":["string","null"],"description":"Street name\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `RUE HADLEY`.","examples":["RUE HADLEY"]},"address_type":{"type":["integer","null"],"description":"Address type\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"combine_address":{"type":["boolean","null"],"description":"Combine address_1 and address_2 into address_1\n\n**Details:** Type `boolean` · Nullable.","examples":[true]},"buzz_code":{"type":["string","null"],"description":"Recipient buzz code\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `9393`.","examples":[9393]},"city":{"type":["string","null"],"description":"**Required.**\n\nRecipient city\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Montreal`.","examples":["Montreal"]},"province":{"type":["string","null"],"description":"Recipient province (required outside no-province areas)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `QC`.","examples":["QC"]},"country":{"type":["string","null"],"description":"**Required.**\n\nRecipient country\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `CA`.","examples":["CA"]},"name":{"type":["string","null"],"description":"**Required.**\n\nRecipient name\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `John`.","examples":["John"]},"company_name":{"type":["string","null"],"description":"Recipient company name\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `HELLO WORLD`.","examples":["HELLO WORLD"]},"email":{"type":["string","null"],"description":"Recipient email\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `join@gmail.com`.","examples":["join@gmail.com"]},"telephone":{"type":["string","null"],"description":"**Required.**\n\nRecipient telephone (required)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `5555555555`.","examples":[5555555555]},"note":{"type":["string","null"],"description":"Order note (max 255)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `customer note`.","examples":["customer note"]},"ref":{"type":["string","null"],"description":"Order reference\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `API001`.","examples":["API001"]},"order_code":{"type":["string","null"],"description":"Order Code (max 5 characters, letters and numbers only)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `ABC`.","examples":["ABC"]},"package_ref":{"type":["string","null"],"description":"Package reference (single-package form)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `20311`.","examples":[20311]},"package_note":{"type":["string","null"],"description":"Package note (single-package form, max 255)\n\n**Details:** Type `string` · Nullable.","examples":["Package Note"]},"external_order_id":{"type":["string","null"],"description":"External order id\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `EXT-1001`.","examples":["EXT-1001"]},"auto_deduplication":{"type":["integer","null"],"description":"Auto deduplication (0: No, 1: Yes)\n\n**Details:** Type `integer` · Nullable.","examples":[0]},"notification_language":{"type":["string","null"],"description":"Notification language code\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `en`.","examples":["en"]},"signature_option":{"type":["integer","null"],"description":"Signature option (0: No, 1: Yes)\n\n**Details:** Type `integer` · Nullable.","examples":[1]},"insurance_option":{"type":["integer","null"],"description":"Insurance option\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"package_type":{"type":["string","null"],"description":"Carrier package type code\n\nPackage handling type. Source: `PackageTypeInput`.\n\nEnum values (from deployed code):\n- `parcel` — Parcel\n- `pallet` — Pallet\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `PAK`.","enum":["parcel","pallet",null],"x-enumDescriptions":["Parcel","Pallet"],"examples":["PAK"]},"paid_by":{"type":["integer","null"],"description":"Paid by (1: sender, 2: receiver, 3: third party, 4: collect)\n\n**Details:** Type `integer` · Nullable.","examples":[1]},"account_number":{"type":["string","null"],"description":"Carrier account number (required when paid_by is 3 or 4)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `123456`.","examples":[123456]},"account_country":{"type":["string","null"],"description":"Carrier account country (paid_by 3)\n\n**Details:** Type `string` · Nullable.","examples":["CA"]},"account_postcode":{"type":["string","null"],"description":"Carrier account postcode (paid_by 3)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `H4E3R3`.","examples":["H4E3R3"]},"export_reason":{"type":["integer","null"],"description":"Export reason id\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"carriers":{"type":["array","null"],"description":"Restrict rating to these carriers\n\n**Details:** Type `array`, items `string` · Nullable.","items":{"type":"string","description":"Carriers. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"examples":[["fedex"]]},"services":{"type":["array","null"],"description":"Restrict rating to these services\n\n**Details:** Type `array`, items `string` · Nullable.","items":{"type":"string","description":"Services. Element of a list or map in the request/response payload.\n\n**Details:** Type `string`."},"examples":[["FEDEX_GROUND"]]},"weight":{"type":["number","null"],"description":"Package weight (single-package form)\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `1`.","examples":[1]},"length":{"type":["number","null"],"description":"Package length (single-package form)\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `1`.","examples":[1]},"width":{"type":["number","null"],"description":"Package width (single-package form)\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `1`.","examples":[1]},"height":{"type":["number","null"],"description":"Package height (single-package form)\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `1`.","examples":[1]},"dimension_unit":{"type":["integer","null"],"description":"Dimension unit (single-package form)\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"weight_unit":{"type":["integer","null"],"description":"Weight unit (single-package form)\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"insurance_value":{"type":["number","null"],"description":"Insured value (single-package form)\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `200`.","examples":[200]},"items":{"type":["array","null"],"description":"Customs items (single-package form)\n\n**Details:** Type `array`, items `object` · Nullable.","items":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Item name\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Product 1`.","examples":["Product 1"]},"quantity":{"type":["integer","null"],"description":"Quantity\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"unit_price":{"type":["number","null"],"description":"Unit price\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `1.48`.","examples":[1.48]},"weight":{"type":["number","null"],"description":"Item weight\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `1000`.","examples":[1000]},"currency":{"type":["string","null"],"description":"Currency code\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `CAD`.","examples":["CAD"]},"hscode":{"type":["string","null"],"description":"HS code\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `8009201332`.","examples":[8009201332]},"barcode":{"type":["string","null"],"description":"Barcode\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `1231231243`.","examples":[1231231243]},"sku":{"type":["string","null"],"description":"SKU\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `SKU001`.","examples":["SKU001"]},"description":{"type":["string","null"],"description":"Item description\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Product 1 description`.","examples":["Product 1 description"]},"unit":{"type":["string","null"],"description":"Unit\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `PCS`.","examples":["PCS"]}}}},"packages":{"type":["array","null"],"description":"Multi-package form; replaces the flat weight/dimension fields\n\n**Details:** Type `array`, items `object` · Nullable.","items":{"type":"object","properties":{"ref":{"type":["string","null"],"description":"Package reference\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `20311`.","examples":[20311]},"external_tracking_number":{"type":["string","null"],"description":"External tracking number\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `123456789`.","examples":[123456789]},"weight":{"type":["number","null"],"description":"Weight\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `1000`.","examples":[1000]},"length":{"type":["number","null"],"description":"Length\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `300`.","examples":[300]},"width":{"type":["number","null"],"description":"Width\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `200`.","examples":[200]},"height":{"type":["number","null"],"description":"Height\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `100`.","examples":[100]},"dimension_unit":{"type":["integer","null"],"description":"Dimension unit\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"weight_unit":{"type":["integer","null"],"description":"Weight unit\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"package_value":{"type":["number","null"],"description":"Declared package value\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `200`.","examples":[200]},"insurance_value":{"type":["number","null"],"description":"Insured value\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `200`.","examples":[200]},"items":{"type":["array","null"],"description":"Customs items in this package\n\n**Details:** Type `array`, items `object` · Nullable.","items":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Item name\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Product 1`.","examples":["Product 1"]},"quantity":{"type":["integer","null"],"description":"Quantity\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"unit_price":{"type":["number","null"],"description":"Unit price\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `1.48`.","examples":[1.48]},"weight":{"type":["number","null"],"description":"Item weight\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `1000`.","examples":[1000]},"currency":{"type":["string","null"],"description":"Currency code\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `CAD`.","examples":["CAD"]},"hscode":{"type":["string","null"],"description":"HS code\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `8009201332`.","examples":[8009201332]},"barcode":{"type":["string","null"],"description":"Barcode\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `1231231243`.","examples":[1231231243]},"sku":{"type":["string","null"],"description":"SKU\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `SKU001`.","examples":["SKU001"]},"description":{"type":["string","null"],"description":"Item description\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Product 1 description`.","examples":["Product 1 description"]},"unit":{"type":["string","null"],"description":"Unit\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `PCS`.","examples":["PCS"]}}}}}}},"shipping_from":{"type":["integer","null"],"description":"Shipping-from address book id\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `87`.","examples":[87]},"shipping_from_code":{"type":["string","null"],"description":"Shipping-from address book Unique Identifier (alternative to shipping_from; shipping_from wins when both are given)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `WH-TORONTO`.","examples":["WH-TORONTO"]},"sender_name":{"type":["string","null"],"description":"Sender name (manual sender)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `test`.","examples":["test"]},"sender_company_name":{"type":["string","null"],"description":"Sender company name\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Super Route`.","examples":["Super Route"]},"sender_address_1":{"type":["string","null"],"description":"Sender address line 1\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `6701 RUE HADLEY`.","examples":["6701 RUE HADLEY"]},"sender_address_2":{"type":["string","null"],"description":"Sender address line 2\n\n**Details:** Type `string` · Nullable.","examples":[""]},"sender_address_type":{"type":["integer","null"],"description":"Sender address type\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `1`.","examples":[1]},"sender_postcode":{"type":["string","null"],"description":"Sender postcode\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `H4E3R3`.","examples":["H4E3R3"]},"sender_city":{"type":["string","null"],"description":"Sender city\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `Montreal`.","examples":["Montreal"]},"sender_province":{"type":["string","null"],"description":"Sender province\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `QC`.","examples":["QC"]},"sender_country":{"type":["string","null"],"description":"Sender country\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `CA`.","examples":["CA"]},"sender_email":{"type":["string","null"],"description":"Sender email\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `info@gmail.com`.","examples":["info@gmail.com"]},"sender_telephone":{"type":["string","null"],"description":"Sender telephone\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `5555555555`.","examples":[5555555555]},"sender_buzz_code":{"type":["string","null"],"description":"Sender buzz code\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `9393`.","examples":[9393]},"schedule_date":{"type":["string","null"],"description":"Scheduled date (Y-m-d)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `2026-08-21`.","examples":["2026-08-21"]},"related_order_type":{"type":["integer","null"],"description":"Related order type (1: Batch Pickup Order, 2: Super Proxy Order). Both related_order_type and related_order_id must be provided together or both must be null.\n\nHow this order links to another business document (`orders.related_order_type`). Source: `RelatedOrderTypeInput`.\n\nEnum values (from deployed code):\n- `1` — Batch Pickup\n- `2` — Super Proxy\n- `3` — Storage Order\n- `4` — Return Request\n- `5` — Moving Order\n- `6` — Kiosk Pickup\n- `7` — Smart Locker Pickup\n- `8` — Product Purchase\n- `9` — Shipping Order\n- `10` — Storage Shipout\n- `11` — Return Label\n- `12` — Third-party Delivery Transfer\n- `16` — Sales Order\n- `17` — Third-party Partial Delivery Split\n- `18` — Order Split\n\n**Details:** Type `integer` · Nullable.","enum":[1,2,3,4,5,6,7,8,9,10,11,12,16,17,18,null],"x-enumDescriptions":["Batch Pickup","Super Proxy","Storage Order","Return Request","Moving Order","Kiosk Pickup","Smart Locker Pickup","Product Purchase","Shipping Order","Storage Shipout","Return Label","Third-party Delivery Transfer","Sales Order","Third-party Partial Delivery Split","Order Split"],"examples":[1]},"related_order_id":{"type":["integer","null"],"description":"Related order ID. Both related_order_type and related_order_id must be provided together or both must be null.\n\nId of the related document pointed to by `related_order_type` (storage order, shipping order, sales order, …).\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `12345`.","examples":[12345]}}},"LabelServiceShippingDetailRequest":{"type":"object","required":["id"],"properties":{"id":{"type":["string","null"],"description":"**Required.**\n\nOrder id, tracking number, third-party/external tracking number or ref, per type\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `12708`.","examples":[12708]},"type":{"type":["string","null"],"description":"How to interpret id (default ORDER_ID)\n\nAllowed values: `ORDER_ID` · `TRACKING_NUMBER` · `THIRD_PARTY_TRACKING_NUMBER` · `EXTERNAL_TRACKING_NUMBER` · `REF`.\n\n**Details:** Type `string` · Nullable.","enum":["ORDER_ID","TRACKING_NUMBER","THIRD_PARTY_TRACKING_NUMBER","EXTERNAL_TRACKING_NUMBER","REF",null],"examples":["ORDER_ID"]},"rate_id":{"type":["string","null"],"description":"Rate id to price against\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `rat_xxxx`.","examples":["rat_xxxx"]},"warehouse_code":{"type":["string","null"],"description":"Warehouse code (with carrier+service, syncs the order to the warehouse)\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `test`.","examples":["test"]},"carrier":{"type":["string","null"],"description":"Carrier for warehouse sync\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `fedex`.","examples":["fedex"]},"service":{"type":["string","null"],"description":"Service for warehouse sync\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `FEDEX_GROUND`.","examples":["FEDEX_GROUND"]}}},"LabelServiceCancelLabelRequest":{"type":"object","description":"Provide exactly one of id or tracking_number.","properties":{"id":{"type":["integer","null"],"description":"Order id\n\n**Details:** Type `integer` · Nullable.\n\n**Example:** `17832`.","examples":[17832]},"tracking_number":{"type":["string","null"],"description":"Package tracking number or third-party tracking number\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `794973591300`.","examples":[794973591300]}}},"OrderRateV2":{"type":"object","properties":{"type":{"type":"string","required":false,"description":"Order Type: D:delivery,P:Pickup,P2P:Peer to Peer\n\n**Details:** Type `string`.","examples":["D"]},"from_postcode":{"type":"string","required":false,"description":"From postcode. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `H9S2H9`.","examples":["H9S2H9"]},"from_country":{"type":"string","required":false,"description":"From country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"to_postcode":{"type":"string","required":true,"description":"**Required.**\n\nTo postcode. Stable machine-readable code.\n\n**Details:** Type `string`.\n\n**Example:** `H4B2T5`.","examples":["H4B2T5"]},"to_country":{"type":"string","required":true,"description":"To country. Numeric quantity or monetary amount as defined by this endpoint.\n\n**Details:** Type `string`.\n\n**Example:** `CA`.","examples":["CA"]},"packages":{"type":"array","items":{"type":"object","properties":{"weight":{"type":"number","description":"**Required.**\n\nWeight of the package in weight_unit.\n\n**Details:** Type `number`.\n\n**Example:** `1.234`.","examples":[1.234]},"width":{"type":"number","description":"**Required.**\n\nWidth of the package in dimension_unit.\n\n**Details:** Type `number` · pattern `^[0-9]+(\\.[0-9]{1,3})?$`.\n\n**Example:** `10.532`.","pattern":"^[0-9]+(\\.[0-9]{1,3})?$","examples":[10.532]},"height":{"type":"number","description":"**Required.**\n\nHeight of the package in dimension_unit.\n\n**Details:** Type `number` · pattern `^[0-9]+(\\.[0-9]{1,3})?$`.\n\n**Example:** `20.332`.","pattern":"^[0-9]+(\\.[0-9]{1,3})?$","examples":[20.332]},"length":{"type":"number","description":"**Required.**\n\nLength of the package in dimension_unit.\n\n**Details:** Type `number` · pattern `^[0-9]+(\\.[0-9]{1,3})?$`.\n\n**Example:** `15.232`.","pattern":"^[0-9]+(\\.[0-9]{1,3})?$","examples":[15.232]},"dimension_unit":{"type":"integer","enum":[1,2,3,4],"description":"Unit for the dimensions. 1: mm, 2: cm, 3: m, 4: inch\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `1`.","default":1,"examples":[1]},"weight_unit":{"type":"integer","enum":[1,2,3,4],"description":"Unit for the weight. 1: g, 2: kg, 3: oz, 4: lb\n\nAllowed values: `1` · `2` · `3` · `4`.\n\n**Details:** Type `integer` · Default: `1`.","default":1,"examples":[1]}},"required":["weight","width","height","length"]},"description":"**Required.**\n\nLegacy package count for the order. Prefer `packagesDetail` for dimensions and weights.\n\n**Details:** Type `array`, items `object`."},"signature_option":{"type":"integer","enum":[0,1],"description":"Indicates if a signature is required. 0: No signature, 1: Signature required.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Default: `0`.","default":0,"x-enumDescriptions":["No / false / off","Yes / true / on"],"examples":[0]},"channel_id":{"type":["integer","null"],"description":"The ID of the channel. Default is null.\n\n**Details:** Type `integer|null`.","default":null,"examples":[null]},"fulfillment_center_id":{"type":["integer","null"],"description":"The ID of the fulfillment center. Default is null.\n\n**Details:** Type `integer|null`.","default":null,"examples":[null]},"to_address":{"type":["string","null"],"required":false,"description":"Delivery street line. Optional. When the shipment would be carried by a third-party carrier, some carriers (Intelcom among them) will not price it without a street line; the response then says so in third_party.warning.\n\n**Details:** Type `string|null`.\n\n**Example:** `6841 Rue Saint-Denis`.","examples":["6841 Rue Saint-Denis"]},"to_city":{"type":["string","null"],"required":false,"description":"Delivery city. Optional; used when the postcode alone does not resolve one. Some third-party carriers (Intelcom among them) will not price a consignee without a city — the response then says so in third_party.warning.\n\n**Details:** Type `string|null`.\n\n**Example:** `Montréal`.","examples":["Montréal"]},"to_province":{"type":["string","null"],"required":false,"description":"Delivery province/state. Optional; used when the postcode alone does not resolve one.\n\n**Details:** Type `string|null`.\n\n**Example:** `QC`.","examples":["QC"]}},"required":["to_postcode","packages"]},"LabelFetchState":{"type":"object","description":"The background poll for a label file the carrier had not produced when the order was purchased. One attempt every `interval_seconds` for `timeout_seconds` per window; a failed window restarts when the label is requested again.","properties":{"status":{"type":"string","enum":["pending","ready","failed"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `pending` · `ready` · `failed`.\n\n**Details:** Type `string`."},"attempts":{"type":"integer","description":"Attempts made in the current window.\n\n**Details:** Type `integer`."},"windows":{"type":"integer","description":"How many times the poll was started (1 = never retried).\n\n**Details:** Type `integer`."},"started_at":{"type":["string","null"],"format":"date-time","description":"Started at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Expires at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"Next attempt at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"last_attempt_at":{"type":["string","null"],"format":"date-time","description":"Last attempt at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"completed_at":{"type":["string","null"],"format":"date-time","description":"Completed at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"remaining_seconds":{"type":["integer","null"],"description":"Seconds left in the current window while pending.\n\n**Details:** Type `integer` · Nullable."},"interval_seconds":{"type":"integer","description":"Interval seconds. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `30`.","examples":[30]},"timeout_seconds":{"type":"integer","description":"Timeout seconds. Field in the JSON request body.\n\n**Details:** Type `integer`.\n\n**Example:** `300`.","examples":[300]},"last_error_code":{"type":["string","null"],"description":"Last error code. Stable machine-readable code.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `shipment_label_not_ready`.","examples":["shipment_label_not_ready"]},"last_error":{"type":["string","null"],"description":"Last error. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `ParcelBee: label file is not ready yet, please try again shortly`.","examples":["ParcelBee: label file is not ready yet, please try again shortly"]},"retry_allowed":{"type":"boolean","description":"Retry allowed. Field in the JSON request body.\n\n**Details:** Type `boolean`."}},"examples":[{"status":"pending","attempts":3,"windows":1,"started_at":"2026-09-16T10:00:00+00:00","expires_at":"2026-09-16T10:05:00+00:00","next_attempt_at":"2026-09-16T10:02:00+00:00","last_attempt_at":"2026-09-16T10:01:30+00:00","completed_at":null,"remaining_seconds":210,"interval_seconds":30,"timeout_seconds":300,"last_error_code":"shipment_label_not_ready","last_error":"ParcelBee: label file is not ready yet, please try again shortly","retry_allowed":true}]},"InsufficientBalance":{"type":"object","description":"Detail of a balance refusal: the charge that did not fit, what the account had available (balance + credit), and how the payer may top up. Present whenever `code` is `INSUFFICIENT_BALANCE`.","properties":{"msg":{"type":"string","description":"Always the literal `Insufficient balance available`. Kept unchanged for existing integrations that match on it.\n\n**Details:** Type `string`.","examples":["Insufficient balance available"]},"balance":{"type":["number","null"],"description":"The shortfall, under the key it has always used. Same value as `shortfall`. Null when the account was refused before the charge was calculated.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `7`.","examples":[7]},"code":{"type":"string","description":"Stable machine code for this resource.\n\n**Details:** Type `string`.\n\n**Example:** `INSUFFICIENT_BALANCE`.","examples":["INSUFFICIENT_BALANCE"]},"message":{"type":"string","description":"The refusal in the caller's language, with the amounts filled in.\n\n**Details:** Type `string`."},"required":{"type":["number","null"],"description":"The charge that would have been posted. Null when the account was already exhausted and the order was refused without pricing it.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `12`.","examples":[12]},"available":{"type":"number","description":"balance + credit at the moment of the refusal.\n\n**Details:** Type `number`.\n\n**Example:** `5`.","examples":[5]},"shortfall":{"type":["number","null"],"description":"required - available, never below 0.\n\n**Details:** Type `number` · Nullable.\n\n**Example:** `7`.","examples":[7]},"currency":{"type":"string","description":"Currency. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `CAD`.","examples":["CAD"]},"currency_symbol":{"type":"string","description":"Currency symbol. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `$`.","examples":["$"]},"can_pay_online":{"type":"boolean","description":"The payer may settle the shortfall online right now: online payment is enabled, at least one channel is configured, and the shortfall is within their online payment limit.\n\n**Details:** Type `boolean`."},"max_online_amount":{"type":["number","null"],"description":"The payer's per-payment online limit, when one is set.\n\n**Details:** Type `number` · Nullable."},"exceeds_max_online_amount":{"type":"boolean","description":"The shortfall is larger than `max_online_amount`, so it cannot be settled online.\n\n**Details:** Type `boolean`."},"channels":{"type":"array","description":"Top-up channels this business has configured and left enabled in Payment Method Settings. Empty when there are none.\n\n**Details:** Type `array`, items `object`.","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource identifier.\n\n**Details:** Type `string`.\n\n**Example:** `stripe:card`.","examples":["stripe:card"]},"gateway":{"type":"string","description":"Gateway. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `stripe`.","examples":["stripe"]},"method":{"type":"string","description":"Method. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `string`.\n\n**Example:** `card`.","examples":["card"]},"value":{"type":"string","description":"The value the payment form submits for this channel.\n\n**Details:** Type `string`.\n\n**Example:** `card`.","examples":["card"]},"display_name":{"type":"string","description":"Display name. Human-readable label.\n\n**Details:** Type `string`.\n\n**Example:** `Credit / Debit Card`.","examples":["Credit / Debit Card"]},"icon":{"type":"string","description":"Icon. Field in the JSON request body.\n\n**Details:** Type `string`.\n\n**Example:** `fas fa-credit-card`.","examples":["fas fa-credit-card"]},"requires_saved_card":{"type":"boolean","description":"Requires saved card. Field in the JSON request body.\n\n**Details:** Type `boolean`."}}}},"add_funds_url":{"type":["string","null"],"description":"Link to the Add Funds page, pre-filled with the shortfall. Null when online payment is disabled for this payer.\n\n**Details:** Type `string` · Nullable."}}},"RuleNotice":{"type":"object","description":"A planning rule the routing engine dropped, approximated or applied with an adjustment (RuleCapabilities).","required":["rule","engine","status","reason"],"properties":{"rule":{"type":"string","description":"**Required.**\n\nThe solver_rules key.\n\n**Details:** Type `string`.\n\n**Example:** `overtime_minutes`.","examples":["overtime_minutes"]},"engine":{"type":"string","enum":["sroute","sroute2","sroute2t"],"description":"**Required.**\n\nThe routing engine the route is planned with.\n\nAllowed values: `sroute` · `sroute2` · `sroute2t`.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["dropped","approximated","adjusted"],"description":"**Required.**\n\ndropped: the engine is sent nothing for the rule. approximated: the rule is planned as closely as the engine allows. adjusted (sRoute 2T 1.0.20): the rule was sent with something changed or left out, see reason.\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `dropped` · `approximated` · `adjusted`.\n\n**Details:** Type `string`."},"reason":{"type":"string","enum":["engine_unsupported","engine_version","balance_preset","solve_time_raised","precomputed_matrix","depot_unreachable","depot_limit","shipment","place_unreachable","depot_closed","break_place_closed","solve_jobs_busy","solve_job_lost"],"description":"**Required.**\n\nengine_unsupported: the engine has no native support for the rule. engine_version: the engine is older than min_version, or its version could not be read. balance_preset (phase P3): the rule maps to a balance preset and the route uses its own (use_all_vehicles on sRoute 2). sRoute 2T 1.0.20: solve_time_raised (rule solve_time) reloads were planned on the thorough tier because no solve time was chosen; precomputed_matrix (rule reload) depots that are no point of the route's precomputed road matrices were left out; depot_unreachable (rule reload) the engine cut depots off from every vehicle; depot_limit (rule reload) a driver was given only its nearest depots, at most 20 reload options; shipment (rule release_time) ready times of pickup-and-delivery orders were not sent. sRoute 2T 1.0.21: place_unreachable (rule break_places) break places no driver can reach were left out. Phase P5b (respect_schedules on, the address links operating hours or a holiday calendar): depot_closed (rule reload) depots closed on the route date were not used, status dropped when none was left; break_place_closed (rule break_places) places not open for the break on the route date were left out, a break left without places is taken along the route.\n\nAllowed values: `engine_unsupported` · `engine_version` · `balance_preset` · `solve_time_raised` · `precomputed_matrix` · `depot_unreachable` · `depot_limit` · `shipment` · `place_unreachable` · `depot_closed` · `break_place_closed` · `solve_jobs_busy` · `solve_job_lost`.\n\n**Details:** Type `string`."},"min_version":{"type":["string","null"],"description":"Only with reason engine_version: the lowest engine version that reads the rule.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `1.0.10`.","examples":["1.0.10"]},"engine_version":{"type":["string","null"],"description":"Only with reason engine_version: the version the engine reports, or null when it could not be read.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `1.0.9`.","examples":["1.0.9"]}}},"DeviceOrderWebhookEvent":{"type":"object","description":"Body of a device_order.* webhook, delivered to device_order_webhook_url.","required":["event_id","event_type","livemode","occurred_at","data"],"properties":{"event_id":{"type":"string","description":"**Required.**\n\nDOE-<device order event id>; stable across retries, deduplicate on it\n\n**Details:** Type `string`.\n\n**Example:** `DOE-90017`.","examples":["DOE-90017"]},"event_type":{"type":"string","enum":["device_order.stored","device_order.collected","device_order.removed","device_order.overdue","device_order.exception_opened","device_order.exception_resolved"],"description":"**Required.**\n\nAllowed values: `device_order.stored` · `device_order.collected` · `device_order.removed` · `device_order.overdue` · `device_order.exception_opened` · `device_order.exception_resolved`.\n\n**Details:** Type `string`."},"livemode":{"type":"boolean","description":"**Required.**\n\nLivemode. Discriminator / type code selecting the variant of this resource.\n\n**Details:** Type `boolean`.\n\n**Example:** `true`.","examples":[true]},"occurred_at":{"type":["string","null"],"format":"date-time","description":"**Required.**\n\nWhen the event happened (`YYYY-MM-DD HH:MM:SS` or ISO-8601). Defaults to server time when omitted.\n\n**Details:** Type `string`, format `date-time` · Nullable."},"data":{"type":"object","required":["device_order"],"properties":{"device_order":{"type":"object","properties":{"id":{"type":"integer","description":"Resource identifier.\n\n**Details:** Type `integer`."},"kind":{"type":"string","enum":["dropoff","shipout_pickup","partner_delivery","kiosk_pickup","self_pickup","locker_storage","return_dropoff","storage_dropoff","carrier_stockin","smart_drop_return"],"description":"Allowed values: `dropoff` · `shipout_pickup` · `partner_delivery` · `kiosk_pickup` · `self_pickup` · `locker_storage` · `return_dropoff` · `storage_dropoff` · `carrier_stockin` · `smart_drop_return`.\n\n**Details:** Type `string`."},"status":{"type":"string","enum":["created","reserved","depositing","stored","retrieving","collected","removed","failed","cancelled"],"description":"Status value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\nAllowed values: `created` · `reserved` · `depositing` · `stored` · `retrieving` · `collected` · `removed` · `failed` · `cancelled`.\n\n**Details:** Type `string`."},"next_actor":{"type":"string","enum":["recipient","customer","courier","operator","partner","nobody"],"description":"Allowed values: `recipient` · `customer` · `courier` · `operator` · `partner` · `nobody`.\n\n**Details:** Type `string`."},"device_type":{"type":"string","enum":["smart_locker","kiosk","smart_drop"],"description":"Allowed values: `smart_locker` · `kiosk` · `smart_drop`.\n\n**Details:** Type `string`."},"device_id":{"type":"integer","description":"Stable device identifier from the mobile / kiosk client.\n\n**Details:** Type `integer`."},"device_name":{"type":["string","null"],"description":"Device name. Human-readable label.\n\n**Details:** Type `string` · Nullable."},"grid_code":{"type":["string","null"],"description":"Locker cell; null for kiosks and smart drops\n\n**Details:** Type `string` · Nullable."},"reference_number":{"type":["string","null"],"description":"Reference number. Field in the JSON request body.\n\n**Details:** Type `string` · Nullable."},"order_id":{"type":["integer","null"],"description":"Superroute order id (`orders.id`).\n\n**Details:** Type `integer` · Nullable."},"external_order_id":{"type":["string","null"],"description":"Merchant / upstream order reference stored on the Superroute order.\n\n**Details:** Type `string` · Nullable."},"due_at":{"type":["string","null"],"format":"date-time","description":"Due at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"overdue_at":{"type":["string","null"],"format":"date-time","description":"Overdue at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"stored_at":{"type":["string","null"],"format":"date-time","description":"Stored at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"ended_at":{"type":["string","null"],"format":"date-time","description":"Ended at. Date-time value (prefer ISO-8601 or `YYYY-MM-DD HH:MM:SS` in the business timezone).\n\n**Details:** Type `string`, format `date-time` · Nullable."},"removal_reason":{"type":["string","null"],"description":"overdue_return | handover | relay | anomaly | recovery\n\n**Details:** Type `string` · Nullable."}},"description":"**Required.**\n\nDevice order. Field in the JSON request body.\n\n**Details:** Type `object`."},"exception":{"type":"object","description":"Only on device_order.exception_opened / device_order.exception_resolved\n\n**Details:** Type `object`.","properties":{"id":{"type":["integer","null"],"description":"Resource identifier.\n\n**Details:** Type `integer` · Nullable."},"type":{"type":["string","null"],"description":"Type discriminator for this resource. See the endpoint description for the allowed set.\n\n**Details:** Type `string` · Nullable.\n\n**Example:** `door_left_open`.","examples":["door_left_open"]},"severity":{"type":["string","null"],"description":"info | attention | urgent\n\n**Details:** Type `string` · Nullable."},"status":{"type":["string","null"],"description":"open | acknowledged | resolved | dismissed\n\nStatus value for this resource. Exact allowed set depends on the endpoint — when the schema lists an enum, those are the only accepted values. Common domains: order (`orders_status_id`), route (`RouteStatusInput`), loading plan, packing plan, locker delivery, wallet transaction.\n\n**Details:** Type `string` · Nullable."},"resolution_action":{"type":["string","null"],"description":"reopened | took_out | reassigned | emptied | marked_ok | escalated\n\n**Details:** Type `string` · Nullable."}}}},"description":"**Required.**\n\nData. Field in the JSON request body.\n\n**Details:** Type `object`."}},"examples":[{"event_id":"DOE-90017","event_type":"device_order.stored","livemode":true,"occurred_at":"2026-09-15T10:06:00-04:00","data":{"device_order":{"id":5012,"kind":"shipout_pickup","status":"stored","next_actor":"recipient","device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A","grid_code":"A-12","reference_number":"SR100234","order_id":88231,"external_order_id":null,"due_at":"2026-09-18T10:06:00-04:00","overdue_at":null,"stored_at":"2026-09-15T10:06:00-04:00","ended_at":null,"removal_reason":null}}}]},"BatchOrderCreate":{"type":"object","required":["orders"],"properties":{"orders":{"type":"array","description":"**Required.**\n\nList of orders to create in this batch. Each element uses the same fields as single-order create (`OrderCreate`), including `packagesDetail`.\n\n**Details:** Type `array` · minItems `1`.","items":{"$ref":"#/components/schemas/OrderCreate","description":"Orders. Element of a list or map in the request/response payload.\n\n**Details:** Schema `$ref` → `OrderCreate`."},"minItems":1},"per_order_transaction":{"type":["integer","null"],"description":"When `1`, each order is committed in its own transaction so one failure cannot roll back the others (a terminal error row with `batch_aborted=true` is appended if processing stops early). Default `0` keeps the legacy single-transaction batch.\n\nEnum values:\n- `0` — No / false / off\n- `1` — Yes / true / on\n\n**Details:** Type `integer` · Default: `0` · Nullable.","enum":[0,1,null],"default":0,"x-enumDescriptions":["No / false / off","Yes / true / on"]}}}}},"jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","webhooks":{"order.created":{"post":{"operationId":"webhook.tenant.order.created","summary":"An order was created.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"`true` for a created order."},"id":{"type":"integer","description":"Order id."},"ref":{"type":["string","null"],"description":"Your order reference."},"type":{"type":"string","description":"Order type code (D delivery, P pickup, …)."},"customer_id":{"type":["integer","null"]},"tracking_number":{"type":"array","description":"Tracking number of every package.","items":{"type":"string"}},"shipping_price":{"type":["string","null"],"description":"Two-decimal price; hidden when the recipient may not see prices."},"price_details":{"type":["object","null"],"description":"Price breakdown.","additionalProperties":true},"currency":{"type":["string","null"]},"rates":{"type":"array","description":"Rate options, when the order was created with rating.","items":{"type":"object","additionalProperties":true}},"best_rate":{"type":["object","null"],"additionalProperties":true},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"external_tracking_number":{"type":["string","null"]}},"required":["id"],"additionalProperties":true}},"warning":{"type":"string","description":"Present only when the create produced a warning."}},"required":["result","id","type","tracking_number","packages"],"additionalProperties":true},"examples":{"sample":{"value":{"result":true,"id":1001,"ref":"REF-001","type":"D","customer_id":42,"tracking_number":["SR000000001"],"shipping_price":"13.30","price_details":{"shipping_fee":"10.00","signature_fee":"1.50","sub_total":"11.50","tax_details":[{"tax_number_id":3,"tax_name":"HST","tax_rate":13,"tax":"1.50"}],"tax_zone_id":7},"currency":"CAD","packages":[{"id":2001,"ref":"PKG-001","tracking_number":"SR000000001","external_tracking_number":"1Z999AA10123456784"}]}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Sent once per created order. Orders of types other than local delivery are sent only when `order_created_webhook_all_types` is 1. Orders from a batch are not sent here when `order_create_async_postback_url` is set; the batch result goes there instead."}},"order.status_change":{"post":{"operationId":"webhook.tenant.order.status_change","summary":"An operation changed an order's status.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Operation event id."},"action":{"type":"string","enum":["created","updated","deleted"]},"user_id":{"type":["integer","null"]},"business_id":{"type":["integer","null"]},"location_id":{"type":["integer","null"]},"location_information":{"type":"object","description":"Name and address of `location_id`; present only when it is set.","additionalProperties":true},"grid_id":{"type":["integer","null"]},"ip_address":{"type":["string","null"]},"operation_category":{"type":["integer","null"]},"operation_type":{"type":["integer","null"]},"operation_category_text":{"type":["string","null"]},"operation_type_text":{"type":["string","null"]},"operation_description":{"type":["string","null"]},"is_ascan":{"type":["integer","boolean","null"]},"route_id":{"type":["integer","null"]},"order_id":{"type":["integer","null"]},"before_status":{"type":["integer","null"]},"after_status":{"type":["integer","null"]},"tracking_event_id":{"type":["integer","null"]},"gps_tracking_id":{"type":["integer","null"]},"latitude":{"type":["number","string","null"]},"longitude":{"type":["number","string","null"]},"order_address_history_id":{"type":["integer","null"]},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]},"order_ref":{"type":["string","null"]},"package_id":{"type":["integer","null"]},"tracking_number":{"type":["string","null"]},"external_tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"return_reason":{"type":["string","null"]},"shipping_to":{"type":["object","array"],"properties":{"name":{"type":["string","null"]},"company_name":{"type":["string","null"]},"telephone":{"type":["string","null"]},"email":{"type":["string","null"]},"address_1":{"type":["string","null"]},"address_2":{"type":["string","null"]},"city":{"type":["string","null"]},"province":{"type":["string","null"]},"country":{"type":["string","null"]},"code":{"type":["string","null"]},"postcode":{"type":["string","null"]}},"additionalProperties":true,"description":"An address object, or an empty array `[]` when there is none."},"shipping_from":{"type":["object","array"],"properties":{"name":{"type":["string","null"]},"company_name":{"type":["string","null"]},"telephone":{"type":["string","null"]},"email":{"type":["string","null"]},"address_1":{"type":["string","null"]},"address_2":{"type":["string","null"]},"city":{"type":["string","null"]},"province":{"type":["string","null"]},"country":{"type":["string","null"]},"code":{"type":["string","null"]},"postcode":{"type":["string","null"]}},"additionalProperties":true,"description":"An address object, or an empty array `[]` when there is none."},"is_correction":{"type":"boolean","description":"Present, `true`, only with the event envelope on, when the change corrects an earlier status."}},"required":["id","action"],"additionalProperties":true},"examples":{"sample":{"value":{"id":50001,"user_id":3011,"business_id":42,"location_id":12,"location_information":{"name":"Toronto Depot","address_1":"10 King St","address_2":"","city":"Toronto","province":"ON","country":"Canada","postcode":"M5V1A1","territory_id":7,"territory_name":"Downtown"},"grid_id":null,"ip_address":"203.0.113.24","operation_category":1,"operation_type":1001,"is_ascan":0,"operation_description":null,"route_id":8801,"order_id":1001,"before_status":20,"after_status":8,"tracking_event_id":90001,"gps_tracking_id":77012,"latitude":"43.6532","longitude":"-79.3832","order_address_history_id":null,"created_at":"2026-09-26 06:58:36","updated_at":"2026-09-26 06:58:36","action":"created","operation_type_text":"driver change status","operation_category_text":"driver","order_ref":"REF-001","package_id":2001,"tracking_number":"SR000000001","external_tracking_number":"1Z999AA10123456784","type":"D","return_reason":"","shipping_to":{"name":"Jane Doe","company_name":"","telephone":"+14165550123","email":"jane@example.com","address_1":"55 Queen St W","address_2":"Unit 8","city":"Toronto","province":"ON","country":"Canada","code":"","postcode":"M5H2M9"},"shipping_from":{"name":"Toronto Depot","company_name":"Acme Logistics","telephone":"+14165550100","address_1":"10 King St","address_2":"","city":"Toronto","province":"ON","country":"Canada","code":"","postcode":"M5V1A1"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Sent once per package of the order."}},"tracking.event":{"post":{"operationId":"webhook.tenant.tracking.event","summary":"A tracking event was recorded.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"location_id":{"type":["integer","string","null"],"description":"Location id, or an empty string."},"location_name":{"type":["string","null"]},"tracking_event_type":{"type":["string","null"]},"tracking_event_status_id":{"type":"integer"},"tracking_event_key":{"type":["string","null"]},"otep_status":{"type":["string","null"],"description":"OTEP status code."},"description":{"type":"object","description":"The event text keyed by language code.","additionalProperties":true},"proof_files":{"type":"array","description":"Delivered and picked-up statuses only.","items":{"type":"string"}},"proof_files_detail":{"type":"array","description":"Delivered and picked-up statuses only.","items":{"type":"object","properties":{"file_id":{"type":"integer"},"type":{"type":"integer","description":"1 signature, 2 photo, …"},"note":{"type":["string","null"]},"url":{"type":"string","description":"Storage path."},"full_url":{"type":"string"},"signed_url":{"type":"string","description":"Time-limited download URL; absent when the file was removed."},"signed_url_expires_at":{"type":"integer","description":"Unix seconds."},"tracking_event_id":{"type":["integer","null"]},"tracking_event_status_id":{"type":["integer","null"]},"tracking_event_key":{"type":["string","null"]},"service_type":{"type":["integer","null"]},"service_status":{"type":["integer","null"]}},"required":["file_id","type","url"],"additionalProperties":true}},"reason_id":{"type":["integer","null"]},"reason":{"type":["string","null"]},"visible_to_public":{"type":["boolean","integer","null"]},"tracking_number":{"type":"array","items":{"type":"string"}},"external_tracking_number":{"type":"array","items":{"type":"string"}},"occurred_at":{"type":"string","description":"With the event envelope on only."},"occurred_timestamp":{"type":"integer","description":"With the event envelope on only."}},"required":["id","order_id","tracking_event_status_id"],"additionalProperties":true},"examples":{"sample":{"value":{"id":90001,"order_id":1001,"order_ref":"REF-001","location_id":12,"location_name":"Toronto Depot","tracking_event_type":"D","tracking_event_status_id":500,"tracking_event_key":"deliver_success","otep_status":"delivered","proof_files":["storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg","storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg"],"proof_files_detail":[{"file_id":234567,"type":1,"url":"storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg","full_url":"https://api.superroute.ca/storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg","signed_url":"https://api.superroute.ca/files/pod/234567?expires=1784748600&signature=8f2c1d...","signed_url_expires_at":1784748600,"tracking_event_id":90001,"tracking_event_status_id":500,"tracking_event_key":"deliver_success","service_type":1,"service_status":1},{"file_id":234568,"type":2,"url":"storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg","full_url":"https://api.superroute.ca/storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg","signed_url":"https://api.superroute.ca/files/pod/234568?expires=1784748600&signature=41ba90...","signed_url_expires_at":1784748600,"tracking_event_id":90001,"tracking_event_status_id":500,"tracking_event_key":"deliver_success","service_type":1,"service_status":1}],"description":{"en":"Your parcel has been delivered successfully. Thank you!","fr":"Votre colis a été livré avec succès. Merci !","chs":"您的包裹已成功送达，感谢您的使用！","cht":"您的包裹已成功送達，感謝您的使用！","es":"Tu paquete ha sido entregado con éxito. ¡Gracias!","de":"Ihr Paket wurde erfolgreich zugestellt. Vielen Dank!","nl":"Uw pakket is succesvol afgeleverd, bedankt voor uw gebruik!","pt":"Seu pacote foi entregue com sucesso. Obrigado!","it":"Il tuo pacco è stato consegnato con successo. Grazie!","sr":"Vaš paket je uspešno dostavljen, hvala vam što koristite naše usluge!","hu":"Csomagja sikeresen kiszállításra került, köszönjük hogy használta szolgáltatásunkat!","pl":"Twoja paczka została dostarczona pomyślnie. Dziękujemy!","sk":"Váš balík bol úspešne doručený. Ďakujeme!","cs":"Váš balík byl úspěšně doručen. Děkujeme!"},"tracking_number":["SR000000001"],"external_tracking_number":["1Z999AA10123456784"]}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Proof files, failure reasons and tracking numbers are present only when they apply."}},"order.create_async":{"post":{"operationId":"webhook.tenant.order.create_async","summary":"Result of an asynchronous batch create.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":["array","object"],"description":"Normally a JSON array with one row per submitted order. If the whole batch fails, a single object `{result: false, message}`.","items":{"type":"object","properties":{"result":{"type":"boolean","description":"`false` for a row that was not created."},"message":{"type":"string","description":"Why the row was not created."},"ref":{"type":["string","null"]},"skipped_ref":{"type":["string","null"]},"error_key":{"type":["string","null"]}},"required":["result"],"additionalProperties":true,"description":"A created order (same shape as `order.created`) or a failed row."},"properties":{"result":{"type":"boolean"},"message":{"type":"string"}}},"examples":{"sample":{"value":[{"result":true,"id":1001,"ref":"REF-001","type":"D","customer_id":42,"tracking_number":["SR000000001"],"shipping_price":"13.30","currency":"CAD","packages":[{"id":2001,"ref":"PKG-001","tracking_number":"SR000000001","external_tracking_number":"1Z999AA10123456784"}]},{"result":false,"message":"Please provider a valid postcode","ref":"REF-002"}]}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"The body is a JSON array, never enveloped. Operations may resend a batch result manually; the resend carries the same body."}},"pod.files_updated":{"post":{"operationId":"webhook.tenant.pod.files_updated","summary":"A proof-of-delivery file was added or removed.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","description":"`added`, `removed`, …"},"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":"array","items":{"type":"string"}},"external_tracking_number":{"type":"array","items":{"type":"string"}},"file":{"type":"object","properties":{"file_id":{"type":"integer"},"type":{"type":"integer","description":"1 signature, 2 photo, …"},"note":{"type":["string","null"]},"url":{"type":"string","description":"Storage path."},"full_url":{"type":"string"},"signed_url":{"type":"string","description":"Time-limited download URL; absent when the file was removed."},"signed_url_expires_at":{"type":"integer","description":"Unix seconds."},"tracking_event_id":{"type":["integer","null"]},"tracking_event_status_id":{"type":["integer","null"]},"tracking_event_key":{"type":["string","null"]},"service_type":{"type":["integer","null"]},"service_status":{"type":["integer","null"]}},"required":["file_id","type","url"],"additionalProperties":true},"event_id":{"type":"string","description":"Identity of this event; kept on retries and on manual redelivery."},"event_time":{"type":"string","description":"ISO 8601 time of the event."},"event_timestamp":{"type":"integer","description":"Unix seconds of the event."}},"required":["action","order_id","file","event_id","event_time","event_timestamp"],"additionalProperties":true},"examples":{"sample":{"value":{"action":"added","order_id":1001,"order_ref":"REF-001","tracking_number":["SR000000001"],"external_tracking_number":["1Z999AA10123456784"],"file":{"file_id":234567,"type":1,"note":null,"url":"storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg","full_url":"https://api.superroute.ca/storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg","signed_url":"https://api.superroute.ca/files/pod/234567?expires=1784748600&signature=8f2c1d...","signed_url_expires_at":1784748600,"tracking_event_id":90001,"tracking_event_status_id":500,"tracking_event_key":"deliver_success","service_type":1,"service_status":1},"event_id":"9b2e4c7a-1f30-4d8e-8a55-6c0f1e2d3a4b","event_time":"2026-09-26T06:58:36-04:00","event_timestamp":1790420316}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Always carries `event_id`, `event_time` and `event_timestamp`, whatever the envelope setting."}},"order.deleted":{"post":{"operationId":"webhook.tenant.order.deleted","summary":"An order was deleted.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["deleted"]},"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"type":{"type":["string","null"]},"orders_status_id":{"type":["integer","null"]},"tracking_number":{"type":"array","items":{"type":"string"}},"external_tracking_number":{"type":"array","items":{"type":"string"}},"event_id":{"type":"string","description":"Identity of this event; kept on retries and on manual redelivery."},"event_time":{"type":"string","description":"ISO 8601 time of the event."},"event_timestamp":{"type":"integer","description":"Unix seconds of the event."}},"required":["action","order_id","event_id","event_time","event_timestamp"],"additionalProperties":true},"examples":{"sample":{"value":{"action":"deleted","order_id":1001,"order_ref":"REF-001","type":"D","orders_status_id":2,"tracking_number":["SR000000001"],"external_tracking_number":["1Z999AA10123456784"],"event_id":"4c1a7f92-0b6d-4e11-9c3a-2f7b5d8e6a10","event_time":"2026-09-26T06:58:36-04:00","event_timestamp":1790420316}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Always carries `event_id`, `event_time` and `event_timestamp`, whatever the envelope setting."}},"order.cancel_failed":{"post":{"operationId":"webhook.tenant.order.cancel_failed","summary":"A cancel request through the API could not be carried out.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"boolean","description":"Always `false`."},"code":{"type":["string","null"]},"message":{"type":["string","null"]},"http_status":{"type":"integer"},"submitted":{"type":"object","description":"What the cancel request named.","properties":{"order_id":{"type":["integer","string","null"]},"tracking_number":{"type":["string","null"]},"external_tracking_number":{"type":["string","null"]}},"additionalProperties":true},"matched_order_ids":{"type":"array","description":"Present only when the request matched several orders.","items":{"type":"integer"}}},"required":["result","http_status","submitted"],"additionalProperties":true},"examples":{"sample":{"value":{"result":false,"code":"ORDER_ALREADY_IN_DELIVERY","message":"Order can no longer be cancelled at its current status","http_status":409,"submitted":{"order_id":1001,"tracking_number":"SR000000001","external_tracking_number":null}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Sent to the caller of the cancel request."}},"route_board.seat_changed":{"post":{"operationId":"webhook.tenant.route_board.seat_changed","summary":"A seat on a route board changed.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["route_board.seat_changed"]},"action":{"type":"string","enum":["claimed","standby","pooled","promoted","withdrawn","vetoed","replaced","assigned","awarded","lost","displaced","settled","board_opened","board_closed","board_cancelled"]},"board":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":["string","null"]},"date":{"type":["string","null"]},"mode":{"type":["string","null"]},"status":{"type":["string","null"]},"business_id":{"type":"integer"},"broker_id":{"type":["integer","null"]}},"required":["id"],"additionalProperties":true},"seat":{"type":["object","null"],"properties":{"id":{"type":"integer"},"route_id":{"type":["integer","null"]},"slot_id":{"type":["integer","null"]},"route_name":{"type":["string","null"]},"work_from":{"type":["string","null"]},"work_end":{"type":["string","null"]},"status":{"type":["string","null"]}},"additionalProperties":true},"claim":{"type":["object","null"],"properties":{"id":{"type":"integer"},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"driver_alias":{"type":["string","null"]},"rank":{"type":["integer","null"]},"status":{"type":["string","null"]},"bid_price":{"type":["number","null"]},"awarded_price":{"type":["number","null"]},"reason":{"type":["string","null"]}},"additionalProperties":true},"occurred_at":{"type":"string"},"extra":{"type":"object","description":"Action-specific details.","additionalProperties":true}},"required":["event","action","board","seat","claim","occurred_at","extra"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"route_board.seat_changed","action":"claimed","board":{"id":12,"title":"Thursday AM routes","date":"2026-09-10","mode":"route","status":"open","business_id":7,"broker_id":null},"seat":{"id":301,"route_id":940,"slot_id":950,"route_name":"North Loop","work_from":"08:00","work_end":"12:00","status":"filled"},"claim":{"id":5001,"driver_id":920,"driver_name":"Alex Driver","driver_alias":"AD","rank":1,"status":"primary","bid_price":null,"awarded_price":null,"reason":null},"occurred_at":"2026-09-26T06:58:36-04:00","extra":{}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Business recipients only."}},"order.assigned":{"post":{"operationId":"webhook.tenant.order.assigned","summary":"The order was assigned to a driver.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.assigned","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":16,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"source":"auto_assign","previous_driver_id":null}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.unassigned":{"post":{"operationId":"webhook.tenant.order.unassigned","summary":"The order lost its driver.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.unassigned","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":16,"route_id":5120,"driver_id":null,"driver_name":"Alex","customer_id":77,"previous_driver_id":42,"source":"driver_duty_release"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.accepted":{"post":{"operationId":"webhook.tenant.order.accepted","summary":"The driver accepted the order.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.accepted","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":16,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"reason":null}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.rejected":{"post":{"operationId":"webhook.tenant.order.rejected","summary":"The driver rejected the order.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.rejected","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":16,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"reason":"Too far away"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.pickup_started":{"post":{"operationId":"webhook.tenant.order.pickup_started","summary":"The driver started the pickup.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.pickup_started","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":45,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"previous_status_id":16}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.picked_up":{"post":{"operationId":"webhook.tenant.order.picked_up","summary":"The order was picked up.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.picked_up","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":7,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"previous_status_id":45}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.on_the_way":{"post":{"operationId":"webhook.tenant.order.on_the_way","summary":"The driver is on the way to the recipient.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.on_the_way","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":46,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"previous_status_id":7}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.completed":{"post":{"operationId":"webhook.tenant.order.completed","summary":"The order was completed.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.completed","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":8,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"previous_status_id":46}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.failed":{"post":{"operationId":"webhook.tenant.order.failed","summary":"The delivery failed.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.failed","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":9,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"previous_status_id":46}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.cancelled":{"post":{"operationId":"webhook.tenant.order.cancelled","summary":"The order was cancelled.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.cancelled","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":12,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"previous_status_id":16}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"order.ready":{"post":{"operationId":"webhook.tenant.order.ready","summary":"The order was marked ready for pickup.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Order lifecycle event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"order_id":{"type":"integer"},"order_ref":{"type":["string","null"]},"tracking_number":{"type":["string","null"]},"type":{"type":["string","null"]},"status_id":{"type":["integer","null"]},"previous_status_id":{"type":["integer","null"]},"route_id":{"type":["integer","null"]},"driver_id":{"type":["integer","null"]},"driver_name":{"type":["string","null"]},"previous_driver_id":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"source":{"type":["string","null"]},"reason":{"type":["string","null"]},"ready_by_user_id":{"type":["integer","null"]}},"required":["order_id"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDE","event_type":"order.ready","livemode":true,"occurred_at":"2026-08-17T10:00:05-04:00","data":{"order_id":88231,"order_ref":"SO-100234","tracking_number":"TRK-1001","type":"D","status_id":16,"route_id":5120,"driver_id":42,"driver_name":"Alex","customer_id":77,"ready_by_user_id":3}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all). The same event for the same order and driver is sent at most once per minute."}},"driver.on_duty_changed":{"post":{"operationId":"webhook.tenant.driver.on_duty_changed","summary":"A driver went on or off duty.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Driver duty event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"driver_id":{"type":"integer"},"driver_name":{"type":["string","null"]},"on_duty":{"type":"boolean"},"changed_at":{"type":"string"}},"required":["driver_id","on_duty"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDF","event_type":"driver.on_duty_changed","livemode":true,"occurred_at":"2026-08-17T08:00:00-04:00","data":{"driver_id":42,"driver_name":"Alex","on_duty":true,"changed_at":"2026-08-17T08:00:00-04:00"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Narrowed by `order_lifecycle_events` (empty: all)."}},"driver.location_update":{"post":{"operationId":"webhook.tenant.driver.location_update","summary":"A driver's position.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Driver position event.","properties":{"event_id":{"type":"string","description":"`OLE-` + ULID; the identity of this event."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":"string","description":"ISO 8601."},"data":{"type":"object","properties":{"driver_id":{"type":"integer"},"driver_name":{"type":["string","null"]},"latitude":{"type":"number"},"longitude":{"type":"number"},"recorded_at":{"type":"string"},"route_id":{"type":"integer"},"order_id":{"type":"integer"},"heading":{"type":"number"},"speed":{"type":"number"},"accuracy":{"type":"number"}},"required":["driver_id","latitude","longitude","recorded_at"],"additionalProperties":true}},"required":["event_id","event_type","livemode","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"OLE-01JABCDG","event_type":"driver.location_update","livemode":true,"occurred_at":"2026-08-17T10:00:30-04:00","data":{"driver_id":42,"driver_name":"Alex","latitude":45.5017,"longitude":-73.5673,"recorded_at":"2026-08-17T10:00:30-04:00","route_id":5120,"heading":90,"speed":12.5}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"At most one per driver every `driver_location_min_interval_sec` seconds (default 60). `route_id`, `order_id`, `heading`, `speed` and `accuracy` are present only when known."}},"device_order.stored":{"post":{"operationId":"webhook.tenant.device_order.stored","summary":"An item was stored in a device.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`DOE-` + ledger id; the same for the same event every time it is sent."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","properties":{"device_order":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string"},"status":{"type":"string"},"next_actor":{"type":["string","null"]},"device_type":{"type":["string","null"]},"device_id":{"type":["integer","null"]},"device_name":{"type":["string","null"]},"grid_code":{"type":["string","null"]},"reference_number":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_id":{"type":["string","null"]},"due_at":{"type":["string","null"]},"overdue_at":{"type":["string","null"]},"stored_at":{"type":["string","null"]},"ended_at":{"type":["string","null"]},"removal_reason":{"type":["string","null"]}},"required":["id","kind","status"],"additionalProperties":true},"exception":{"type":"object","description":"Exception events only.","properties":{"id":{"type":["integer","null"]},"type":{"type":["string","null"]},"severity":{"type":["string","null"]},"status":{"type":["string","null"]},"resolution_action":{"type":["string","null"]}},"additionalProperties":true}},"required":["device_order"],"additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"DOE-90017","event_type":"device_order.stored","livemode":true,"occurred_at":"2026-09-15T10:06:00-04:00","data":{"device_order":{"id":5012,"kind":"shipout_pickup","status":"stored","next_actor":"recipient","device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A","grid_code":"A-12","reference_number":"SR100234","order_id":88231,"external_order_id":null,"due_at":"2026-09-18T10:06:00-04:00","overdue_at":null,"stored_at":"2026-09-15T10:06:00-04:00","ended_at":null,"removal_reason":null}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Business recipients only. Narrowed by `device_order_events` (empty: all)."}},"device_order.collected":{"post":{"operationId":"webhook.tenant.device_order.collected","summary":"The item was collected.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`DOE-` + ledger id; the same for the same event every time it is sent."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","properties":{"device_order":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string"},"status":{"type":"string"},"next_actor":{"type":["string","null"]},"device_type":{"type":["string","null"]},"device_id":{"type":["integer","null"]},"device_name":{"type":["string","null"]},"grid_code":{"type":["string","null"]},"reference_number":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_id":{"type":["string","null"]},"due_at":{"type":["string","null"]},"overdue_at":{"type":["string","null"]},"stored_at":{"type":["string","null"]},"ended_at":{"type":["string","null"]},"removal_reason":{"type":["string","null"]}},"required":["id","kind","status"],"additionalProperties":true},"exception":{"type":"object","description":"Exception events only.","properties":{"id":{"type":["integer","null"]},"type":{"type":["string","null"]},"severity":{"type":["string","null"]},"status":{"type":["string","null"]},"resolution_action":{"type":["string","null"]}},"additionalProperties":true}},"required":["device_order"],"additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"DOE-90017","event_type":"device_order.collected","livemode":true,"occurred_at":"2026-09-15T10:06:00-04:00","data":{"device_order":{"id":5012,"kind":"shipout_pickup","status":"collected","next_actor":"nobody","device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A","grid_code":"A-12","reference_number":"SR100234","order_id":88231,"external_order_id":null,"due_at":"2026-09-18T10:06:00-04:00","overdue_at":null,"stored_at":"2026-09-15T10:06:00-04:00","ended_at":"2026-09-16T18:40:00-04:00","removal_reason":null}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Business recipients only. Narrowed by `device_order_events` (empty: all)."}},"device_order.removed":{"post":{"operationId":"webhook.tenant.device_order.removed","summary":"The item was removed by staff.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`DOE-` + ledger id; the same for the same event every time it is sent."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","properties":{"device_order":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string"},"status":{"type":"string"},"next_actor":{"type":["string","null"]},"device_type":{"type":["string","null"]},"device_id":{"type":["integer","null"]},"device_name":{"type":["string","null"]},"grid_code":{"type":["string","null"]},"reference_number":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_id":{"type":["string","null"]},"due_at":{"type":["string","null"]},"overdue_at":{"type":["string","null"]},"stored_at":{"type":["string","null"]},"ended_at":{"type":["string","null"]},"removal_reason":{"type":["string","null"]}},"required":["id","kind","status"],"additionalProperties":true},"exception":{"type":"object","description":"Exception events only.","properties":{"id":{"type":["integer","null"]},"type":{"type":["string","null"]},"severity":{"type":["string","null"]},"status":{"type":["string","null"]},"resolution_action":{"type":["string","null"]}},"additionalProperties":true}},"required":["device_order"],"additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"DOE-90017","event_type":"device_order.removed","livemode":true,"occurred_at":"2026-09-15T10:06:00-04:00","data":{"device_order":{"id":5012,"kind":"shipout_pickup","status":"removed","next_actor":"nobody","device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A","grid_code":"A-12","reference_number":"SR100234","order_id":88231,"external_order_id":null,"due_at":"2026-09-18T10:06:00-04:00","overdue_at":"2026-09-18T10:15:00-04:00","stored_at":"2026-09-15T10:06:00-04:00","ended_at":"2026-09-19T09:00:00-04:00","removal_reason":"overdue_return"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Business recipients only. Narrowed by `device_order_events` (empty: all)."}},"device_order.overdue":{"post":{"operationId":"webhook.tenant.device_order.overdue","summary":"The item was not collected in time.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`DOE-` + ledger id; the same for the same event every time it is sent."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","properties":{"device_order":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string"},"status":{"type":"string"},"next_actor":{"type":["string","null"]},"device_type":{"type":["string","null"]},"device_id":{"type":["integer","null"]},"device_name":{"type":["string","null"]},"grid_code":{"type":["string","null"]},"reference_number":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_id":{"type":["string","null"]},"due_at":{"type":["string","null"]},"overdue_at":{"type":["string","null"]},"stored_at":{"type":["string","null"]},"ended_at":{"type":["string","null"]},"removal_reason":{"type":["string","null"]}},"required":["id","kind","status"],"additionalProperties":true},"exception":{"type":"object","description":"Exception events only.","properties":{"id":{"type":["integer","null"]},"type":{"type":["string","null"]},"severity":{"type":["string","null"]},"status":{"type":["string","null"]},"resolution_action":{"type":["string","null"]}},"additionalProperties":true}},"required":["device_order"],"additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"DOE-90017","event_type":"device_order.overdue","livemode":true,"occurred_at":"2026-09-15T10:06:00-04:00","data":{"device_order":{"id":5012,"kind":"shipout_pickup","status":"stored","next_actor":"operator","device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A","grid_code":"A-12","reference_number":"SR100234","order_id":88231,"external_order_id":null,"due_at":"2026-09-18T10:06:00-04:00","overdue_at":"2026-09-18T10:15:00-04:00","stored_at":"2026-09-15T10:06:00-04:00","ended_at":null,"removal_reason":null}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Business recipients only. Narrowed by `device_order_events` (empty: all)."}},"device_order.exception_opened":{"post":{"operationId":"webhook.tenant.device_order.exception_opened","summary":"An exception was opened on the device order.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`DOE-` + ledger id; the same for the same event every time it is sent."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","properties":{"device_order":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string"},"status":{"type":"string"},"next_actor":{"type":["string","null"]},"device_type":{"type":["string","null"]},"device_id":{"type":["integer","null"]},"device_name":{"type":["string","null"]},"grid_code":{"type":["string","null"]},"reference_number":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_id":{"type":["string","null"]},"due_at":{"type":["string","null"]},"overdue_at":{"type":["string","null"]},"stored_at":{"type":["string","null"]},"ended_at":{"type":["string","null"]},"removal_reason":{"type":["string","null"]}},"required":["id","kind","status"],"additionalProperties":true},"exception":{"type":"object","description":"Exception events only.","properties":{"id":{"type":["integer","null"]},"type":{"type":["string","null"]},"severity":{"type":["string","null"]},"status":{"type":["string","null"]},"resolution_action":{"type":["string","null"]}},"additionalProperties":true}},"required":["device_order"],"additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"DOE-90017","event_type":"device_order.exception_opened","livemode":true,"occurred_at":"2026-09-15T10:06:00-04:00","data":{"device_order":{"id":5012,"kind":"shipout_pickup","status":"stored","next_actor":"recipient","device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A","grid_code":"A-12","reference_number":"SR100234","order_id":88231,"external_order_id":null,"due_at":"2026-09-18T10:06:00-04:00","overdue_at":null,"stored_at":"2026-09-15T10:06:00-04:00","ended_at":null,"removal_reason":null},"exception":{"id":311,"type":"door_left_open","severity":"attention","status":"open","resolution_action":null}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Business recipients only. Narrowed by `device_order_events` (empty: all)."}},"device_order.exception_resolved":{"post":{"operationId":"webhook.tenant.device_order.exception_resolved","summary":"The exception was resolved.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`DOE-` + ledger id; the same for the same event every time it is sent."},"event_type":{"type":"string"},"livemode":{"type":"boolean"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","properties":{"device_order":{"type":"object","properties":{"id":{"type":"integer"},"kind":{"type":"string"},"status":{"type":"string"},"next_actor":{"type":["string","null"]},"device_type":{"type":["string","null"]},"device_id":{"type":["integer","null"]},"device_name":{"type":["string","null"]},"grid_code":{"type":["string","null"]},"reference_number":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_id":{"type":["string","null"]},"due_at":{"type":["string","null"]},"overdue_at":{"type":["string","null"]},"stored_at":{"type":["string","null"]},"ended_at":{"type":["string","null"]},"removal_reason":{"type":["string","null"]}},"required":["id","kind","status"],"additionalProperties":true},"exception":{"type":"object","description":"Exception events only.","properties":{"id":{"type":["integer","null"]},"type":{"type":["string","null"]},"severity":{"type":["string","null"]},"status":{"type":["string","null"]},"resolution_action":{"type":["string","null"]}},"additionalProperties":true}},"required":["device_order"],"additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"DOE-90017","event_type":"device_order.exception_resolved","livemode":true,"occurred_at":"2026-09-15T10:06:00-04:00","data":{"device_order":{"id":5012,"kind":"shipout_pickup","status":"stored","next_actor":"recipient","device_type":"smart_locker","device_id":11,"device_name":"LOCKER-A","grid_code":"A-12","reference_number":"SR100234","order_id":88231,"external_order_id":null,"due_at":"2026-09-18T10:06:00-04:00","overdue_at":null,"stored_at":"2026-09-15T10:06:00-04:00","ended_at":null,"removal_reason":null},"exception":{"id":311,"type":"door_left_open","severity":"attention","status":"resolved","resolution_action":"marked_ok"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Business recipients only. Narrowed by `device_order_events` (empty: all)."}},"partner_locker.delivery.doors_opened":{"post":{"operationId":"webhook.partner-locker.partner_locker.delivery.doors_opened","summary":"Compartment doors were opened for a delivery.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEE","event_type":"partner_locker.delivery.doors_opened","livemode":true,"occurred_at":"2026-07-21T14:29:40-04:00","data":{"delivery_no":"PLD-100234","external_order_id":"EXT-9001","status":"awaiting_confirmation","delivery_mode":"standard","pickup_code":"483920","opening":{"attempt_id":501,"attempt_no":1,"opened_count":2,"failed_count":0,"partial":false,"groups":[{"shelf_name":"LK-A1","locker_identifier":"SL-88231","compartments":[{"package_sequence":1,"compartment_number":"12","grid_id":5011,"pickup_locker_number":3,"pickup_locker_code":"LK-A1-3"},{"package_sequence":2,"compartment_number":"15","grid_id":5014,"pickup_locker_number":6,"pickup_locker_code":"LK-A1-6"}]}]}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.delivery_doors_opened` in the endpoint's event types (none selected: all)."}},"partner_locker.delivery.delivered":{"post":{"operationId":"webhook.partner-locker.partner_locker.delivery.delivered","summary":"A delivery was confirmed into the lockers.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEF","event_type":"partner_locker.delivery.delivered","livemode":true,"occurred_at":"2026-07-21T14:30:00-04:00","data":{"delivery_no":"PLD-100234","external_order_id":"EXT-9001","status":"delivered","pickup_status":"ready","requested_package_count":2,"actual_package_count":2,"failed_package_count":0,"picked_up_package_count":0,"partial_delivery":false,"delivery_mode":"standard","confirmed_by":"door_close","split_from_delivery_no":null,"split_delivery_no":null,"pickup_code":"483920","location":{"id":12,"name":"Main St Locker"},"packages":[{"sequence":1,"external_package_id":"PKG-1","status":"confirmed","shelf_id":21,"grid_id":5011,"compartment_number":"12","pickup_locker_number":3,"pickup_locker_code":"LK-A1-3"},{"sequence":2,"external_package_id":"PKG-2","status":"confirmed","shelf_id":21,"grid_id":5014,"compartment_number":"15","pickup_locker_number":6,"pickup_locker_code":"LK-A1-6"}]}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.delivery_delivered` in the endpoint's event types (none selected: all)."}},"partner_locker.pickup.completed":{"post":{"operationId":"webhook.partner-locker.partner_locker.pickup.completed","summary":"The recipient collected the delivery.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEG","event_type":"partner_locker.pickup.completed","livemode":true,"occurred_at":"2026-07-22T09:12:00-04:00","data":{"delivery_no":"PLD-100234","status":"picked_up","pickup_status":"completed","picked_up_package_count":2}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.delivery_picked_up` in the endpoint's event types (none selected: all)."}},"partner_locker.delivery.failed":{"post":{"operationId":"webhook.partner-locker.partner_locker.delivery.failed","summary":"A delivery failed.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEH","event_type":"partner_locker.delivery.failed","livemode":true,"occurred_at":"2026-07-21T14:35:00-04:00","data":{"delivery_no":"PLD-100235","status":"failed","failed_package_count":1,"packages":[{"sequence":1,"status":"failed","failure_code":"NO_CAPACITY"}]}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.delivery_failed` in the endpoint's event types (none selected: all)."}},"partner_locker.delivery.expired":{"post":{"operationId":"webhook.partner-locker.partner_locker.delivery.expired","summary":"A delivery expired.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEI","event_type":"partner_locker.delivery.expired","livemode":true,"occurred_at":"2026-07-24T00:05:00-04:00","data":{"delivery_no":"PLD-100236","status":"expired"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.delivery_expired` in the endpoint's event types (none selected: all)."}},"partner_locker.delivery.cancelled":{"post":{"operationId":"webhook.partner-locker.partner_locker.delivery.cancelled","summary":"A delivery was cancelled.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEJ","event_type":"partner_locker.delivery.cancelled","livemode":true,"occurred_at":"2026-07-21T15:00:00-04:00","data":{"delivery_no":"PLD-100237","status":"cancelled"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.delivery_cancelled` in the endpoint's event types (none selected: all)."}},"partner_locker.delivery.correction_reopened":{"post":{"operationId":"webhook.partner-locker.partner_locker.delivery.correction_reopened","summary":"Compartments were reopened to correct a delivery.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEK","event_type":"partner_locker.delivery.correction_reopened","livemode":true,"occurred_at":"2026-07-21T14:31:05-04:00","data":{"delivery_no":"PLD-100234","status":"delivered","correction":{"channel":"device","reopened_count":2,"failed_count":0,"compartments":[{"compartment_number":"A03","package_sequence":1,"grid_id":5011,"pickup_locker_number":3,"pickup_locker_code":"LK-A1-3"},{"compartment_number":"A04","package_sequence":2,"grid_id":5014,"pickup_locker_number":6,"pickup_locker_code":"LK-A1-6"}]}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.delivery_correction_reopened` in the endpoint's event types (none selected: all)."}},"partner_locker.delivery.code_rotated":{"post":{"operationId":"webhook.partner-locker.partner_locker.delivery.code_rotated","summary":"An access or pickup code was replaced.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEM","event_type":"partner_locker.delivery.code_rotated","livemode":true,"occurred_at":"2026-08-11T09:15:00-04:00","data":{"delivery_no":"PLD-100234","external_order_id":"EXT-9001","status":"active","rotation":{"code_type":"access","rotated_at":"2026-08-11T09:15:00-04:00","recipient_notified":false}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Received only by endpoints subscribed to all events: this type cannot be selected by name today."}},"carrier_package.distribution.created":{"post":{"operationId":"webhook.partner-locker.carrier_package.distribution.created","summary":"A carrier package was put on a distribution order.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEN","event_type":"carrier_package.distribution.created","livemode":true,"occurred_at":"2026-09-20T10:12:00-04:00","data":{"package_no":"12-77","carrier_reference_number":"1Z999AA10123456784","member_number":null,"carrier_order_id":null,"batch":"B-1","distribution":{"order_id":9002,"order_ref":"DIST-276-703-20260920-1","status":"pending_route"},"origin":{"id":276,"name":"Central"},"destination":{"id":703,"name":"Point A"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.carrier_package_distributed` in the endpoint's event types (none selected: all)."}},"carrier_package.distribution.loaded":{"post":{"operationId":"webhook.partner-locker.carrier_package.distribution.loaded","summary":"A carrier package was loaded for distribution.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEN","event_type":"carrier_package.distribution.loaded","livemode":true,"occurred_at":"2026-09-20T10:12:00-04:00","data":{"package_no":"12-77","carrier_reference_number":"1Z999AA10123456784","member_number":null,"carrier_order_id":null,"batch":"B-1","distribution":{"order_id":9002,"order_ref":"DIST-276-703-20260920-1","status":"in_transit","loaded_at":"2026-09-20T10:12:00-04:00"},"origin":{"id":276,"name":"Central"},"destination":{"id":703,"name":"Point A"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.carrier_package_loaded` in the endpoint's event types (none selected: all)."}},"carrier_package.distribution.delivered":{"post":{"operationId":"webhook.partner-locker.carrier_package.distribution.delivered","summary":"A carrier package reached its destination.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEN","event_type":"carrier_package.distribution.delivered","livemode":true,"occurred_at":"2026-09-20T10:12:00-04:00","data":{"package_no":"12-77","carrier_reference_number":"1Z999AA10123456784","member_number":null,"carrier_order_id":null,"batch":"B-1","distribution":{"order_id":9002,"order_ref":"DIST-276-703-20260920-1","status":"delivered","delivered_at":"2026-09-20T13:40:00-04:00"},"origin":{"id":276,"name":"Central"},"destination":{"id":703,"name":"Point A"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.carrier_package_delivered` in the endpoint's event types (none selected: all)."}},"carrier_package.distribution.shelved":{"post":{"operationId":"webhook.partner-locker.carrier_package.distribution.shelved","summary":"A carrier package was shelved at its destination.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEN","event_type":"carrier_package.distribution.shelved","livemode":true,"occurred_at":"2026-09-20T10:12:00-04:00","data":{"package_no":"12-77","carrier_reference_number":"1Z999AA10123456784","member_number":null,"carrier_order_id":null,"batch":"B-1","distribution":{"order_id":9002,"order_ref":"DIST-276-703-20260920-1","status":"shelved","shelved_at":"2026-09-20T13:55:00-04:00"},"destination":{"id":703,"name":"Point A"},"location":{"grid_id":5011,"grid_code":"L-A-01","shelf_code":"L-A"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.carrier_package_shelved` in the endpoint's event types (none selected: all)."}},"carrier_package.distribution.removed":{"post":{"operationId":"webhook.partner-locker.carrier_package.distribution.removed","summary":"A carrier package was taken off its distribution order.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`PLE-` + ULID (`PLE-MOCK-` on sandbox events)."},"event_type":{"type":"string"},"livemode":{"type":"boolean","description":"`false` on sandbox events."},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Delivery or carrier-package details. Keys whose value is null are left out.","additionalProperties":true}},"required":["event_id","event_type","livemode","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"PLE-01JABCDEN","event_type":"carrier_package.distribution.removed","livemode":true,"occurred_at":"2026-09-20T10:12:00-04:00","data":{"package_no":"12-77","carrier_reference_number":"1Z999AA10123456784","member_number":null,"carrier_order_id":null,"batch":"B-1","distribution":{"order_id":9002,"order_ref":"DIST-276-703-20260920-1","status":"removed","reason":"removed"},"origin":{"id":276,"name":"Central"},"destination":{"id":703,"name":"Point A"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with `partner_locker.carrier_package_distribution_removed` in the endpoint's event types (none selected: all)."}},"delivery.assignment.created":{"post":{"operationId":"webhook.tpd.delivery.assignment.created","summary":"An order was assigned to the provider.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`TPDE-` + ULID."},"event_type":{"type":"string"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"assignment_no":{"type":"string"},"assignment_status":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_number":{"type":["string","null"]},"order_ref":{"type":["string","null"]},"packages":{"type":"array","items":{"type":"object","additionalProperties":true}},"legs":{"type":"array","description":"Present only when the assignment has legs.","items":{"type":"object","additionalProperties":true}},"reason":{"type":["string","null"]}},"required":["assignment_no"],"additionalProperties":true}},"required":["event_id","event_type","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"TPDE-01JABCDEA","event_type":"delivery.assignment.created","occurred_at":"2026-07-30T09:15:00-04:00","data":{"assignment_no":"TPD20260730091500ABC123","assignment_status":"assigned","order_id":88231,"order_ref":"SO-100234","packages":[{"tracking_number":"TRK-1001","external_tracking_number":"EXT-1001"}]}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with this type in the endpoint's event types."}},"delivery.assignment.handed_over":{"post":{"operationId":"webhook.tpd.delivery.assignment.handed_over","summary":"The provider accepted the hand-over.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`TPDE-` + ULID."},"event_type":{"type":"string"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"assignment_no":{"type":"string"},"assignment_status":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_number":{"type":["string","null"]},"order_ref":{"type":["string","null"]},"packages":{"type":"array","items":{"type":"object","additionalProperties":true}},"legs":{"type":"array","description":"Present only when the assignment has legs.","items":{"type":"object","additionalProperties":true}},"reason":{"type":["string","null"]}},"required":["assignment_no"],"additionalProperties":true}},"required":["event_id","event_type","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"TPDE-01JABCDEB","event_type":"delivery.assignment.handed_over","occurred_at":"2026-07-30T14:02:00-04:00","data":{"assignment_no":"TPD20260730091500ABC123","assignment_status":"accepted","order_id":88231,"order_ref":"SO-100234","external_order_number":"CARRIER-556","packages":[{"tracking_number":"TRK-1001","external_tracking_number":"EXT-1001"}]}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with this type in the endpoint's event types."}},"delivery.assignment.cancelled":{"post":{"operationId":"webhook.tpd.delivery.assignment.cancelled","summary":"The assignment was cancelled.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`TPDE-` + ULID."},"event_type":{"type":"string"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"assignment_no":{"type":"string"},"assignment_status":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_number":{"type":["string","null"]},"order_ref":{"type":["string","null"]},"packages":{"type":"array","items":{"type":"object","additionalProperties":true}},"legs":{"type":"array","description":"Present only when the assignment has legs.","items":{"type":"object","additionalProperties":true}},"reason":{"type":["string","null"]}},"required":["assignment_no"],"additionalProperties":true}},"required":["event_id","event_type","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"TPDE-01JABCDEC","event_type":"delivery.assignment.cancelled","occurred_at":"2026-07-30T16:40:00-04:00","data":{"assignment_no":"TPD20260730091500ABC123","assignment_status":"cancelled","order_id":88231,"order_ref":"SO-100234","reason":"cancelled"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with this type in the endpoint's event types."}},"delivery.assignment.partial_delivered":{"post":{"operationId":"webhook.tpd.delivery.assignment.partial_delivered","summary":"Some packages of the assignment were delivered.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"`TPDE-` + ULID."},"event_type":{"type":"string"},"occurred_at":{"type":["string","null"]},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"assignment_no":{"type":"string"},"assignment_status":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"external_order_number":{"type":["string","null"]},"order_ref":{"type":["string","null"]},"packages":{"type":"array","items":{"type":"object","additionalProperties":true}},"legs":{"type":"array","description":"Present only when the assignment has legs.","items":{"type":"object","additionalProperties":true}},"reason":{"type":["string","null"]}},"required":["assignment_no"],"additionalProperties":true}},"required":["event_id","event_type","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"TPDE-01JABCDED","event_type":"delivery.assignment.partial_delivered","occurred_at":"2026-07-31T11:20:00-04:00","data":{"assignment_no":"TPD20260730091500ABC123","assignment_status":"accepted","order_id":88231,"order_ref":"SO-100234","packages":[{"tracking_number":"TRK-1001","outcome":"delivered"},{"tracking_number":"TRK-1002"}],"legs":[{"leg_no":1,"package_id":4451,"external_order_number":"CARRIER-556","push_status":"pushed","status":"accepted","outcome":"delivered"},{"leg_no":2,"package_id":4452,"external_order_number":"CARRIER-557","push_status":"pushed","status":"accepted"}]}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Subscribe with this type in the endpoint's event types."}},"loading_plan.solve_started":{"post":{"operationId":"webhook.loading-plan.loading_plan.solve_started","summary":"The solver started.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"UUID."},"event_type":{"type":"string"},"occurred_at":{"type":"string","description":"ISO 8601; fixed when the event is queued."},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"request_id":{"type":["string","null"]},"loading_plan_id":{"type":"integer"},"solve_run_id":{"type":"integer"},"status":{"type":"string"},"error_code":{"type":["string","null"]},"candidate_id":{"type":"integer","description":"`loading_plan.finalized` only."},"status_path":{"type":"string","description":"API path to read the run."}},"required":["loading_plan_id","solve_run_id","status","status_path"],"additionalProperties":true}},"required":["event_id","event_type","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"4f6c2a1e-8b3d-4c5a-9e7f-1a2b3c4d5e6f","event_type":"loading_plan.solve_started","occurred_at":"2026-09-15T10:06:00-04:00","data":{"request_id":"req-7781","loading_plan_id":310,"solve_run_id":1204,"status":"solving","status_path":"/api/v1/loading-plans/310/solve-runs/1204"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"loading_plan.candidates_ready":{"post":{"operationId":"webhook.loading-plan.loading_plan.candidates_ready","summary":"Candidate plans are ready.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"UUID."},"event_type":{"type":"string"},"occurred_at":{"type":"string","description":"ISO 8601; fixed when the event is queued."},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"request_id":{"type":["string","null"]},"loading_plan_id":{"type":"integer"},"solve_run_id":{"type":"integer"},"status":{"type":"string"},"error_code":{"type":["string","null"]},"candidate_id":{"type":"integer","description":"`loading_plan.finalized` only."},"status_path":{"type":"string","description":"API path to read the run."}},"required":["loading_plan_id","solve_run_id","status","status_path"],"additionalProperties":true}},"required":["event_id","event_type","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"4f6c2a1e-8b3d-4c5a-9e7f-1a2b3c4d5e6f","event_type":"loading_plan.candidates_ready","occurred_at":"2026-09-15T10:06:00-04:00","data":{"request_id":"req-7781","loading_plan_id":310,"solve_run_id":1204,"status":"candidates_ready","status_path":"/api/v1/loading-plans/310/solve-runs/1204"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"loading_plan.finalized":{"post":{"operationId":"webhook.loading-plan.loading_plan.finalized","summary":"A candidate was finalized.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"UUID."},"event_type":{"type":"string"},"occurred_at":{"type":"string","description":"ISO 8601; fixed when the event is queued."},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"request_id":{"type":["string","null"]},"loading_plan_id":{"type":"integer"},"solve_run_id":{"type":"integer"},"status":{"type":"string"},"error_code":{"type":["string","null"]},"candidate_id":{"type":"integer","description":"`loading_plan.finalized` only."},"status_path":{"type":"string","description":"API path to read the run."}},"required":["loading_plan_id","solve_run_id","status","status_path"],"additionalProperties":true}},"required":["event_id","event_type","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"4f6c2a1e-8b3d-4c5a-9e7f-1a2b3c4d5e6f","event_type":"loading_plan.finalized","occurred_at":"2026-09-15T10:06:00-04:00","data":{"request_id":"req-7781","loading_plan_id":310,"solve_run_id":1204,"status":"finalized","status_path":"/api/v1/loading-plans/310/solve-runs/1204","candidate_id":5521}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"loading_plan.validation_failed":{"post":{"operationId":"webhook.loading-plan.loading_plan.validation_failed","summary":"The input failed validation.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"UUID."},"event_type":{"type":"string"},"occurred_at":{"type":"string","description":"ISO 8601; fixed when the event is queued."},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"request_id":{"type":["string","null"]},"loading_plan_id":{"type":"integer"},"solve_run_id":{"type":"integer"},"status":{"type":"string"},"error_code":{"type":["string","null"]},"candidate_id":{"type":"integer","description":"`loading_plan.finalized` only."},"status_path":{"type":"string","description":"API path to read the run."}},"required":["loading_plan_id","solve_run_id","status","status_path"],"additionalProperties":true}},"required":["event_id","event_type","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"4f6c2a1e-8b3d-4c5a-9e7f-1a2b3c4d5e6f","event_type":"loading_plan.validation_failed","occurred_at":"2026-09-15T10:06:00-04:00","data":{"request_id":"req-7781","loading_plan_id":310,"solve_run_id":1204,"status":"validation_failed","status_path":"/api/v1/loading-plans/310/solve-runs/1204","error_code":"VEHICLE_CAPACITY_EXCEEDED"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"loading_plan.solve_failed":{"post":{"operationId":"webhook.loading-plan.loading_plan.solve_failed","summary":"The solver failed.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"UUID."},"event_type":{"type":"string"},"occurred_at":{"type":"string","description":"ISO 8601; fixed when the event is queued."},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"request_id":{"type":["string","null"]},"loading_plan_id":{"type":"integer"},"solve_run_id":{"type":"integer"},"status":{"type":"string"},"error_code":{"type":["string","null"]},"candidate_id":{"type":"integer","description":"`loading_plan.finalized` only."},"status_path":{"type":"string","description":"API path to read the run."}},"required":["loading_plan_id","solve_run_id","status","status_path"],"additionalProperties":true}},"required":["event_id","event_type","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"4f6c2a1e-8b3d-4c5a-9e7f-1a2b3c4d5e6f","event_type":"loading_plan.solve_failed","occurred_at":"2026-09-15T10:06:00-04:00","data":{"request_id":"req-7781","loading_plan_id":310,"solve_run_id":1204,"status":"solve_failed","status_path":"/api/v1/loading-plans/310/solve-runs/1204","error_code":"SOLVER_TIMEOUT"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"loading_plan.cancelled":{"post":{"operationId":"webhook.loading-plan.loading_plan.cancelled","summary":"The solve was cancelled.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"UUID."},"event_type":{"type":"string"},"occurred_at":{"type":"string","description":"ISO 8601; fixed when the event is queued."},"data":{"type":"object","description":"Keys whose value is null are left out.","properties":{"request_id":{"type":["string","null"]},"loading_plan_id":{"type":"integer"},"solve_run_id":{"type":"integer"},"status":{"type":"string"},"error_code":{"type":["string","null"]},"candidate_id":{"type":"integer","description":"`loading_plan.finalized` only."},"status_path":{"type":"string","description":"API path to read the run."}},"required":["loading_plan_id","solve_run_id","status","status_path"],"additionalProperties":true}},"required":["event_id","event_type","occurred_at","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event_id":"4f6c2a1e-8b3d-4c5a-9e7f-1a2b3c4d5e6f","event_type":"loading_plan.cancelled","occurred_at":"2026-09-15T10:06:00-04:00","data":{"request_id":"req-7781","loading_plan_id":310,"solve_run_id":1204,"status":"cancelled","status_path":"/api/v1/loading-plans/310/solve-runs/1204"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"endpoint.verify":{"post":{"operationId":"webhook.open-platform.endpoint.verify","summary":"Challenge sent before the first callback to a new endpoint.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["endpoint.verify"]},"challenge":{"type":"string","description":"Echo this value back in the response body."},"occurred_at":{"type":"string"}},"required":["event","challenge","occurred_at"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"endpoint.verify","challenge":"c_8f2c1d4b9a7e6f50","occurred_at":"2026-09-15T14:05:00Z"}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"job.queued":{"post":{"operationId":"webhook.open-platform.job.queued","summary":"The job was queued.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"delivery_id":{"type":"string","description":"`dlv_` + ULID."},"job_id":{"type":"string","description":"`job_` + ULID."},"request_id":{"type":["string","null"]},"capability":{"type":"string"},"occurred_at":{"type":"string","description":"Time of this attempt."},"attempt":{"type":"integer"},"status":{"type":["string","null"]}},"required":["event","delivery_id","job_id","capability","occurred_at","attempt"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"job.queued","delivery_id":"dlv_01jabcde0000000000000000","job_id":"job_01jabcde0000000000000000","request_id":"req-7781","capability":"routing.optimize","occurred_at":"2026-09-15T14:06:00Z","attempt":1,"status":"queued"}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"job.succeeded":{"post":{"operationId":"webhook.open-platform.job.succeeded","summary":"The job succeeded.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"delivery_id":{"type":"string","description":"`dlv_` + ULID."},"job_id":{"type":"string","description":"`job_` + ULID."},"request_id":{"type":["string","null"]},"capability":{"type":"string"},"occurred_at":{"type":"string","description":"Time of this attempt."},"attempt":{"type":"integer"},"status":{"type":["string","null"]},"result_url":{"type":"string"},"result_expires_at":{"type":["string","null"]},"data":{"description":"The result, inline only when it is small enough; otherwise fetch `result_url`."}},"required":["event","delivery_id","job_id","capability","occurred_at","attempt","result_url"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"job.succeeded","delivery_id":"dlv_01jabcde0000000000000000","job_id":"job_01jabcde0000000000000000","request_id":"req-7781","capability":"routing.optimize","occurred_at":"2026-09-15T14:06:00Z","attempt":1,"status":"succeeded","result_url":"https://open.superroute.ca/v1/jobs/job_01jabcde0000000000000000/result","result_expires_at":"2026-09-22T14:06:00Z"}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"job.failed":{"post":{"operationId":"webhook.open-platform.job.failed","summary":"The job failed.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"delivery_id":{"type":"string","description":"`dlv_` + ULID."},"job_id":{"type":"string","description":"`job_` + ULID."},"request_id":{"type":["string","null"]},"capability":{"type":"string"},"occurred_at":{"type":"string","description":"Time of this attempt."},"attempt":{"type":"integer"},"status":{"type":["string","null"]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}},"required":["event","delivery_id","job_id","capability","occurred_at","attempt","error"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"job.failed","delivery_id":"dlv_01jabcde0000000000000000","job_id":"job_01jabcde0000000000000000","request_id":"req-7781","capability":"routing.optimize","occurred_at":"2026-09-15T14:06:00Z","attempt":1,"status":"failed","error":{"code":"SOLVER_TIMEOUT","message":"The solver did not finish within the time limit."}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"job.cancelled":{"post":{"operationId":"webhook.open-platform.job.cancelled","summary":"The job was cancelled.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"delivery_id":{"type":"string","description":"`dlv_` + ULID."},"job_id":{"type":"string","description":"`job_` + ULID."},"request_id":{"type":["string","null"]},"capability":{"type":"string"},"occurred_at":{"type":"string","description":"Time of this attempt."},"attempt":{"type":"integer"},"status":{"type":["string","null"]}},"required":["event","delivery_id","job_id","capability","occurred_at","attempt"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"job.cancelled","delivery_id":"dlv_01jabcde0000000000000000","job_id":"job_01jabcde0000000000000000","request_id":"req-7781","capability":"routing.optimize","occurred_at":"2026-09-15T14:06:00Z","attempt":1,"status":"cancelled"}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"subscription.verify":{"post":{"operationId":"webhook.ohp.subscription.verify","summary":"The subscribe-time challenge; echo `data.challenge` back.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"`0.1`."},"profile":{"type":"string","description":"`parcel`."},"message_id":{"type":"string","description":"The delivery id; the same on every retry — dedupe on it."},"sent_at":{"type":"string","description":"ISO 8601 time of this attempt."},"body":{"type":"object","properties":{"event":{"type":"string","description":"The event type."},"data":{"type":"object","description":"","properties":{"challenge":{"type":"string","description":"Echo this value back, bare or as `{\"challenge\": …}`."}},"required":["challenge"],"additionalProperties":true}},"required":["event","data"],"additionalProperties":true}},"required":["ohp_version","message_id","body"],"additionalProperties":true},"examples":{"sample":{"value":{"ohp_version":"0.2","profile":"parcel","message_id":"opd_01jaq2f8m0n3v6x9r2k5w8y1zk","sent_at":"2026-09-24T17:00:00-04:00","body":{"event":"subscription.verify","data":{"challenge":"q7VgW2xL9rT4mB6cD8fH1jK5nP0sU3yZa2e4g6i8"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"Sent once, while POST /subscriptions is being answered. The subscription exists only if the echo matches."}},"handoff.accepted":{"post":{"operationId":"webhook.ohp.handoff.accepted","summary":"An offered handoff was accepted; the order exists now.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"`0.1`."},"profile":{"type":"string","description":"`parcel`."},"message_id":{"type":"string","description":"The delivery id; the same on every retry — dedupe on it."},"sent_at":{"type":"string","description":"ISO 8601 time of this attempt."},"body":{"type":"object","properties":{"event":{"type":"string","description":"The event type."},"data":{"type":"object","description":"","properties":{"handoff_ref":{"type":"string","description":"The handoff's reference."},"status":{"type":"string","description":"The commercial state (docs/standards/ohp.md §4)."},"tracking_numbers":{"type":"array","items":{"type":"string"}}},"required":["handoff_ref","status"],"additionalProperties":true}},"required":["event","data"],"additionalProperties":true}},"required":["ohp_version","message_id","body"],"additionalProperties":true},"examples":{"sample":{"value":{"ohp_version":"0.2","profile":"parcel","message_id":"opd_01jaq2f8m0n3v6x9r2k5w8y1zd","sent_at":"2026-09-24T18:00:00-04:00","body":{"event":"handoff.accepted","data":{"handoff_ref":"rsb_9f2c1ab4de67f8a1b2c3d4e5","status":"accepted","tracking_numbers":["SR100200300"]}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"handoff.rejected":{"post":{"operationId":"webhook.ohp.handoff.rejected","summary":"An offered handoff was rejected.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"`0.1`."},"profile":{"type":"string","description":"`parcel`."},"message_id":{"type":"string","description":"The delivery id; the same on every retry — dedupe on it."},"sent_at":{"type":"string","description":"ISO 8601 time of this attempt."},"body":{"type":"object","properties":{"event":{"type":"string","description":"The event type."},"data":{"type":"object","description":"","properties":{"handoff_ref":{"type":"string","description":"The handoff's reference."},"status":{"type":"string","description":"The commercial state (docs/standards/ohp.md §4)."},"reason":{"type":["string","null"],"description":"The grantor's reason."}},"required":["handoff_ref","status"],"additionalProperties":true}},"required":["event","data"],"additionalProperties":true}},"required":["ohp_version","message_id","body"],"additionalProperties":true},"examples":{"sample":{"value":{"ohp_version":"0.2","profile":"parcel","message_id":"opd_01jaq2f8m0n3v6x9r2k5w8y1zg","sent_at":"2026-09-24T18:10:00-04:00","body":{"event":"handoff.rejected","data":{"handoff_ref":"rsb_9f2c1ab4de67f8a1b2c3d4e5","status":"rejected","reason":"No van that day"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"handoff.expired":{"post":{"operationId":"webhook.ohp.handoff.expired","summary":"An offered handoff passed its expiry unanswered.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"`0.1`."},"profile":{"type":"string","description":"`parcel`."},"message_id":{"type":"string","description":"The delivery id; the same on every retry — dedupe on it."},"sent_at":{"type":"string","description":"ISO 8601 time of this attempt."},"body":{"type":"object","properties":{"event":{"type":"string","description":"The event type."},"data":{"type":"object","description":"","properties":{"handoff_ref":{"type":"string","description":"The handoff's reference."},"status":{"type":"string","description":"The commercial state (docs/standards/ohp.md §4)."}},"required":["handoff_ref","status"],"additionalProperties":true}},"required":["event","data"],"additionalProperties":true}},"required":["ohp_version","message_id","body"],"additionalProperties":true},"examples":{"sample":{"value":{"ohp_version":"0.2","profile":"parcel","message_id":"opd_01jaq2f8m0n3v6x9r2k5w8y1zf","sent_at":"2026-09-25T18:00:00-04:00","body":{"event":"handoff.expired","data":{"handoff_ref":"rsb_9f2c1ab4de67f8a1b2c3d4e5","status":"expired"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"handoff.cancelled":{"post":{"operationId":"webhook.ohp.handoff.cancelled","summary":"A handoff was cancelled.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"`0.1`."},"profile":{"type":"string","description":"`parcel`."},"message_id":{"type":"string","description":"The delivery id; the same on every retry — dedupe on it."},"sent_at":{"type":"string","description":"ISO 8601 time of this attempt."},"body":{"type":"object","properties":{"event":{"type":"string","description":"The event type."},"data":{"type":"object","description":"","properties":{"handoff_ref":{"type":"string","description":"The handoff's reference."},"status":{"type":"string","description":"The commercial state (docs/standards/ohp.md §4)."}},"required":["handoff_ref","status"],"additionalProperties":true}},"required":["event","data"],"additionalProperties":true}},"required":["ohp_version","message_id","body"],"additionalProperties":true},"examples":{"sample":{"value":{"ohp_version":"0.2","profile":"parcel","message_id":"opd_01jaq2f8m0n3v6x9r2k5w8y1ze","sent_at":"2026-09-24T18:20:00-04:00","body":{"event":"handoff.cancelled","data":{"handoff_ref":"rsb_9f2c1ab4de67f8a1b2c3d4e5","status":"cancelled"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"amendment.accepted":{"post":{"operationId":"webhook.ohp.amendment.accepted","summary":"An amendment proposal was accepted; any price delta became a settlement line.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"`0.1`."},"profile":{"type":"string","description":"`parcel`."},"message_id":{"type":"string","description":"The delivery id; the same on every retry — dedupe on it."},"sent_at":{"type":"string","description":"ISO 8601 time of this attempt."},"body":{"type":"object","properties":{"event":{"type":"string","description":"The event type."},"data":{"type":"object","description":"","properties":{"handoff_ref":{"type":"string","description":"The handoff's reference."},"status":{"type":"string","description":"The commercial state (docs/standards/ohp.md §4)."},"amendment_id":{"type":"integer"},"price_delta":{"type":["number","null"],"description":"Signed price change, when one was charged."},"currency":{"type":["string","null"]},"answer_note":{"type":["string","null"]}},"required":["handoff_ref","amendment_id","status"],"additionalProperties":true}},"required":["event","data"],"additionalProperties":true}},"required":["ohp_version","message_id","body"],"additionalProperties":true},"examples":{"sample":{"value":{"ohp_version":"0.2","profile":"parcel","message_id":"opd_01jaq2f8m0n3v6x9r2k5w8y1zb","sent_at":"2026-09-24T19:05:00-04:00","body":{"event":"amendment.accepted","data":{"handoff_ref":"rsb_9f2c1ab4de67f8a1b2c3d4e5","amendment_id":7,"status":"accepted","price_delta":4.5,"currency":"CAD","answer_note":"Rebooked for the morning run"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"amendment.rejected":{"post":{"operationId":"webhook.ohp.amendment.rejected","summary":"An amendment proposal was rejected.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"`0.1`."},"profile":{"type":"string","description":"`parcel`."},"message_id":{"type":"string","description":"The delivery id; the same on every retry — dedupe on it."},"sent_at":{"type":"string","description":"ISO 8601 time of this attempt."},"body":{"type":"object","properties":{"event":{"type":"string","description":"The event type."},"data":{"type":"object","description":"","properties":{"handoff_ref":{"type":"string","description":"The handoff's reference."},"status":{"type":"string","description":"The commercial state (docs/standards/ohp.md §4)."},"amendment_id":{"type":"integer"},"answer_note":{"type":["string","null"]}},"required":["handoff_ref","amendment_id","status"],"additionalProperties":true}},"required":["event","data"],"additionalProperties":true}},"required":["ohp_version","message_id","body"],"additionalProperties":true},"examples":{"sample":{"value":{"ohp_version":"0.2","profile":"parcel","message_id":"opd_01jaq2f8m0n3v6x9r2k5w8y1zc","sent_at":"2026-09-24T19:06:00-04:00","body":{"event":"amendment.rejected","data":{"handoff_ref":"rsb_9f2c1ab4de67f8a1b2c3d4e5","amendment_id":8,"status":"rejected","answer_note":"Already loaded"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"handoff.tracking":{"post":{"operationId":"webhook.ohp.handoff.tracking","summary":"One OTEP tracking event on a handed-over order.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"`0.1`."},"profile":{"type":"string","description":"`parcel`."},"message_id":{"type":"string","description":"The delivery id; the same on every retry — dedupe on it."},"sent_at":{"type":"string","description":"ISO 8601 time of this attempt."},"body":{"type":"object","properties":{"event":{"type":"string","description":"The event type."},"data":{"type":"object","description":"","properties":{"handoff_ref":{"type":"string"},"event":{"type":"object","properties":{"status_code":{"type":"string","description":"An OTEP status code (docs/standards/otep.md)."},"occurred_at":{"type":["string","null"]}},"required":["status_code"],"additionalProperties":true}},"required":["handoff_ref","event"],"additionalProperties":true}},"required":["event","data"],"additionalProperties":true}},"required":["ohp_version","message_id","body"],"additionalProperties":true},"examples":{"sample":{"value":{"ohp_version":"0.2","profile":"parcel","message_id":"opd_01jaq2f8m0n3v6x9r2k5w8y1zh","sent_at":"2026-09-24T21:15:00-04:00","body":{"event":"handoff.tracking","data":{"handoff_ref":"rsb_9f2c1ab4de67f8a1b2c3d4e5","event":{"status_code":"delivered","occurred_at":"2026-09-24T21:12:00-04:00"}}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"The timeline pulled from GET /handoffs/{ref}/timeline stays the record."}},"settlement_line.created":{"post":{"operationId":"webhook.ohp.settlement_line.created","summary":"A new settlement line exists for a handoff.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ohp_version":{"type":"string","description":"`0.1`."},"profile":{"type":"string","description":"`parcel`."},"message_id":{"type":"string","description":"The delivery id; the same on every retry — dedupe on it."},"sent_at":{"type":"string","description":"ISO 8601 time of this attempt."},"body":{"type":"object","properties":{"event":{"type":"string","description":"The event type."},"data":{"type":"object","description":"","properties":{"line_id":{"type":"string"},"handoff_ref":{"type":"string"},"kind":{"type":"string","enum":["adjustment","cancellation_fee","credit"]},"amount":{"type":"number","description":"Signed: positive = the sender owes more, negative = a credit."},"currency":{"type":"string"},"reason":{"type":["string","null"]},"status":{"type":["string","null"]}},"required":["line_id","handoff_ref","kind","amount","currency"],"additionalProperties":true}},"required":["event","data"],"additionalProperties":true}},"required":["ohp_version","message_id","body"],"additionalProperties":true},"examples":{"sample":{"value":{"ohp_version":"0.2","profile":"parcel","message_id":"opd_01jaq2f8m0n3v6x9r2k5w8y1zj","sent_at":"2026-09-25T09:00:00-04:00","body":{"event":"settlement_line.created","data":{"line_id":"12","handoff_ref":"rsb_9f2c1ab4de67f8a1b2c3d4e5","kind":"adjustment","amount":4.5,"currency":"CAD","reason":"Reweigh: billed 3.1 kg vs quoted 2.4 kg","status":"accepted"}}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}},"description":"The lines pulled from GET /settlement-lines stay the record."}},"test":{"post":{"operationId":"webhook.dataset.test","summary":"Test delivery from the dataset webhook's test button.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string"},"dataset_id":{"type":["integer","null"]},"data":{"type":"object","properties":{"test":{"type":"boolean"},"message":{"type":"string"},"webhook_id":{"type":"integer"},"webhook_name":{"type":["string","null"]}},"additionalProperties":true}},"required":["event","timestamp","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"test","timestamp":"2026-09-15T10:06:00-04:00","dataset_id":41,"data":{"test":true,"message":"This is a test webhook from Superroute","webhook_id":7,"webhook_name":"Warehouse sync"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"record_created":{"post":{"operationId":"webhook.dataset.record_created","summary":"A record was created by a user (web, API, bulk API). Imports, copies and merges send import_completed instead.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","description":"When this attempt was sent."},"dataset_id":{"type":["integer","null"]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"integer"},"group_id":{"type":"integer"},"dataset_id":{"type":["integer","null"]},"row_number":{"type":["integer","null"]},"data":{"type":"object","description":"The record's values keyed by column code; may hold personal data.","additionalProperties":true},"address_combined":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"geocode_status":{"type":["string","null"]},"validation_status":{"type":["string","null"]},"validation_errors":{"description":"Validation errors by column, or null."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","group_id","data"],"additionalProperties":true},"occurred_at":{"type":"string","description":"When the event happened."}},"required":["record","occurred_at"],"additionalProperties":true}},"required":["event","timestamp","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"record_created","timestamp":"2026-09-15T10:06:00-04:00","dataset_id":41,"data":{"record":{"id":88213,"group_id":12,"dataset_id":41,"row_number":57,"data":{"store_code":"MTL-017","name":"Plateau","address":"4200 Rue Saint-Denis","city":"Montreal","postcode":"H2J 2K8"},"address_combined":"4200 Rue Saint-Denis Montreal H2J 2K8","latitude":45.5226,"longitude":-73.5821,"geocode_status":"success","validation_status":"valid","validation_errors":null,"created_at":"2026-09-15T10:02:11-04:00","updated_at":"2026-09-15T10:05:40-04:00"},"occurred_at":"2026-09-15T10:05:59-04:00"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"record_updated":{"post":{"operationId":"webhook.dataset.record_updated","summary":"A record was edited by a user (web or API). System changes (geocoding, computed columns, validation status) are not sent.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","description":"When this attempt was sent."},"dataset_id":{"type":["integer","null"]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"integer"},"group_id":{"type":"integer"},"dataset_id":{"type":["integer","null"]},"row_number":{"type":["integer","null"]},"data":{"type":"object","description":"The record's values keyed by column code; may hold personal data.","additionalProperties":true},"address_combined":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"geocode_status":{"type":["string","null"]},"validation_status":{"type":["string","null"]},"validation_errors":{"description":"Validation errors by column, or null."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","group_id","data"],"additionalProperties":true},"changed":{"type":"array","description":"Codes of the columns whose value changed.","items":{"type":"string"}},"previous":{"type":"object","description":"The changed columns' values before the edit.","additionalProperties":true},"occurred_at":{"type":"string","description":"When the event happened."}},"required":["record","changed","previous","occurred_at"],"additionalProperties":true}},"required":["event","timestamp","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"record_updated","timestamp":"2026-09-15T10:06:00-04:00","dataset_id":41,"data":{"record":{"id":88213,"group_id":12,"dataset_id":41,"row_number":57,"data":{"store_code":"MTL-017","name":"Plateau","address":"4200 Rue Saint-Denis","city":"Montreal","postcode":"H2J 2K8"},"address_combined":"4200 Rue Saint-Denis Montreal H2J 2K8","latitude":45.5226,"longitude":-73.5821,"geocode_status":"success","validation_status":"valid","validation_errors":null,"created_at":"2026-09-15T10:02:11-04:00","updated_at":"2026-09-15T10:05:40-04:00"},"changed":["name"],"previous":{"name":"Plateau Mont-Royal"},"occurred_at":"2026-09-15T10:05:59-04:00"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"record_deleted":{"post":{"operationId":"webhook.dataset.record_deleted","summary":"A record was deleted by a user (web, API, bulk, duplicate resolution); `record` is its last state. Deleting a whole group or dataset sends nothing per record.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","description":"When this attempt was sent."},"dataset_id":{"type":["integer","null"]},"data":{"type":"object","properties":{"record":{"type":"object","properties":{"id":{"type":"integer"},"group_id":{"type":"integer"},"dataset_id":{"type":["integer","null"]},"row_number":{"type":["integer","null"]},"data":{"type":"object","description":"The record's values keyed by column code; may hold personal data.","additionalProperties":true},"address_combined":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"geocode_status":{"type":["string","null"]},"validation_status":{"type":["string","null"]},"validation_errors":{"description":"Validation errors by column, or null."},"created_at":{"type":["string","null"]},"updated_at":{"type":["string","null"]}},"required":["id","group_id","data"],"additionalProperties":true},"occurred_at":{"type":"string","description":"When the event happened."}},"required":["record","occurred_at"],"additionalProperties":true}},"required":["event","timestamp","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"record_deleted","timestamp":"2026-09-15T10:06:00-04:00","dataset_id":41,"data":{"record":{"id":88213,"group_id":12,"dataset_id":41,"row_number":57,"data":{"store_code":"MTL-017","name":"Plateau","address":"4200 Rue Saint-Denis","city":"Montreal","postcode":"H2J 2K8"},"address_combined":"4200 Rue Saint-Denis Montreal H2J 2K8","latitude":45.5226,"longitude":-73.5821,"geocode_status":"success","validation_status":"valid","validation_errors":null,"created_at":"2026-09-15T10:02:11-04:00","updated_at":"2026-09-15T10:05:40-04:00"},"occurred_at":"2026-09-15T10:05:59-04:00"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"import_completed":{"post":{"operationId":"webhook.dataset.import_completed","summary":"A batch of records reached a group: a file import, a scheduled import, a copy or a merge. Sent on failure too.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","description":"When this attempt was sent."},"dataset_id":{"type":["integer","null"]},"data":{"type":"object","properties":{"group_id":{"type":"integer"},"dataset_id":{"type":"integer"},"source":{"type":"string","enum":["file","scheduled","copy","merge"]},"status":{"type":"string","description":"`geocoding`: imported, geocoding started; geocode_completed follows.","enum":["completed","failed","geocoding"]},"created":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"},"errors":{"type":"integer"},"invalid":{"type":"integer"},"error":{"type":["string","null"]},"scheduled_import_id":{"type":"integer","description":"Scheduled imports only."},"source_group_ids":{"type":"array","description":"Copies and merges only.","items":{"type":"integer"}},"source_groups_deleted":{"type":"boolean","description":"Merges only."},"occurred_at":{"type":"string","description":"When the event happened."}},"required":["group_id","dataset_id","source","status","created","updated","skipped","errors","invalid","error","occurred_at"],"additionalProperties":true}},"required":["event","timestamp","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"import_completed","timestamp":"2026-09-15T10:06:00-04:00","dataset_id":41,"data":{"group_id":12,"dataset_id":41,"source":"file","status":"geocoding","created":1250,"updated":0,"skipped":0,"errors":3,"invalid":14,"error":null,"occurred_at":"2026-09-15T10:05:59-04:00"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"geocode_completed":{"post":{"operationId":"webhook.dataset.geocode_completed","summary":"Geocoding of a whole group finished (after an import, a group regeocode or records added through the API). Single-record geocoding sends nothing.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","description":"When this attempt was sent."},"dataset_id":{"type":["integer","null"]},"data":{"type":"object","properties":{"group_id":{"type":"integer"},"dataset_id":{"type":"integer"},"success":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"},"pending":{"type":"integer"},"occurred_at":{"type":"string","description":"When the event happened."}},"required":["group_id","dataset_id","success","failed","skipped","pending","occurred_at"],"additionalProperties":true}},"required":["event","timestamp","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"geocode_completed","timestamp":"2026-09-15T10:06:00-04:00","dataset_id":41,"data":{"group_id":12,"dataset_id":41,"success":1231,"failed":16,"skipped":3,"pending":0,"occurred_at":"2026-09-15T10:05:59-04:00"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"validation_failed":{"post":{"operationId":"webhook.dataset.validation_failed","summary":"A group validation run ended with invalid or skipped records.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","description":"When this attempt was sent."},"dataset_id":{"type":["integer","null"]},"data":{"type":"object","properties":{"group_id":{"type":"integer"},"dataset_id":{"type":"integer"},"valid":{"type":"integer"},"invalid":{"type":"integer"},"skipped":{"type":"integer"},"failures":{"type":"array","description":"At most 100.","items":{"type":"object","properties":{"record_id":{"type":"integer"},"errors":{"description":"Errors by column."}},"required":["record_id","errors"],"additionalProperties":true}},"truncated":{"type":"boolean","description":"More failures than listed."},"occurred_at":{"type":"string","description":"When the event happened."}},"required":["group_id","dataset_id","valid","invalid","skipped","failures","truncated","occurred_at"],"additionalProperties":true}},"required":["event","timestamp","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"validation_failed","timestamp":"2026-09-15T10:06:00-04:00","dataset_id":41,"data":{"group_id":12,"dataset_id":41,"valid":1236,"invalid":14,"skipped":0,"failures":[{"record_id":88213,"errors":{"postcode":[{"rule":"regex","message":"Postcode format is invalid","on_fail":"flag"}]}}],"truncated":false,"occurred_at":"2026-09-15T10:05:59-04:00"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}},"duplicate_found":{"post":{"operationId":"webhook.dataset.duplicate_found","summary":"Duplicates were found in a group: by the duplicate check (`detect`, with pairs) or while merging (`merge`, count only).","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"timestamp":{"type":"string","description":"When this attempt was sent."},"dataset_id":{"type":["integer","null"]},"data":{"type":"object","properties":{"group_id":{"type":"integer"},"dataset_id":{"type":"integer"},"source":{"type":"string","enum":["detect","merge"]},"count":{"type":"integer"},"pairs":{"type":"array","description":"At most 100.","items":{"type":"object","properties":{"original_id":{"type":"integer"},"duplicate_id":{"type":"integer"}},"required":["original_id","duplicate_id"],"additionalProperties":true}},"truncated":{"type":"boolean","description":"More duplicates than listed."},"occurred_at":{"type":"string","description":"When the event happened."}},"required":["group_id","dataset_id","source","count","pairs","truncated","occurred_at"],"additionalProperties":true}},"required":["event","timestamp","data"],"additionalProperties":true},"examples":{"sample":{"value":{"event":"duplicate_found","timestamp":"2026-09-15T10:06:00-04:00","dataset_id":41,"data":{"group_id":12,"dataset_id":41,"source":"detect","count":2,"pairs":[{"original_id":88001,"duplicate_id":88213},{"original_id":88040,"duplicate_id":88230}],"truncated":false,"occurred_at":"2026-09-15T10:05:59-04:00"}}}}}}},"responses":{"200":{"description":"Return any 2xx status to acknowledge receipt."}}}}}}