LSP DMS Gateway — API Integration

Overview

            subscriberid + x-access-key / x-secret-key
  Your DMS ───────────────────────────────────────────▶  Aarambh LSP DMS Gateway
     ▲                                                        (agent sync, order status & events)
     │  ar-access-key / ar-secret-key   ({{WEBHOOK_URI}})
     │◀──────────────────────────────  order/create · order/cancel · order/update
     │◀──────────────────────────────  rider/allocate · rider/payment
     │◀──────────────────────────────  order/status/get · agent/position   (reads)
     │
     │  Authorization: bearer          ({{BASE_URI}})
     │◀──────────────────────────────  order/getNearest · order/request_callback

• Inbound (you → gateway): agent create / update / live-location, agent session tokens for the SDK (agent/acquireSession), order status update, order status cancel, order events (PCC/DCC confirmation, RTO verification, callback request), a read of an order in the order/create shape, a notification relay (notification/create), and payment reads — order earning, rider earning and rider incentive (payment/*).
• Outbound (gateway → you): the gateway pushes order/create, order/cancel, order/update, rider/allocate and rider/payment to your {{WEBHOOK_URI}}, and reads order/status/get and agent/position from it. It also calls order/getNearest and order/request_callback on your {{BASE_URI}}.

Every gateway route is under the /lsp-dms-gateway prefix — e.g. the create-agent route is POST /lsp-dms-gateway/v1/agent/create. Paths below omit the prefix.

Authentication

• Missing subscriberid → 400 { "error": "subscriberid header is required" }
• Missing / wrong x-access-key / x-secret-key → 401

Conventions

• Success: 200 { "message": "<text>", "data": <payload> }.
• Error: { "error": "<message>" } with the HTTP status. When an upstream call to your endpoints fails, the response adds partnerStatus and partnerResponse.
• Coordinates (agent endpoints): ["<lat>", "<long>"] — strings, each with exactly 6 digits after the decimal point (-?\d+\.\d{6}).
• userCode: the agent code returned by agent/create (e.g. sck0005). Use it on every later agent / order call — not a code of your own.
• subscriberid: your subscriber identifier; every record is scoped by it.

Agent APIs

You call these to register and sync your riders.

POST/v1/agent/create

Registers a rider. Returns a server-generated userCode.

{
  "currentLocation": ["12.912345", "77.612345"],
  "mobile": "9845405219",
  "name": "Shashank Rao",
  "isActive": true,
  "timestamp": "2026-08-31T06:19:09.467Z",
  "vehicle": { "type": "bike", "brand": "Hero", "number": "KA01AB1234", "model": "Splendor" },
  "notification": { "provider": "samsung", "token": "<fcm-token>", "enabled": true },
  "device": {
    "id": "string", "osVersion": "14", "appVersion": "1.2.3",
    "isCharging": true, "batteryLevel": 100, "isVirtual": false,
    "languageCode": "en", "languageTag": "en-IN",
    "manufacturer": "samsung", "model": "SM-S911B", "permissions": {}
  },
  // optional profile fields
  "firstName": "shashank",
  "lastName": "rao",
  "profilePic": "",
  "gender": "male",
  "addressDetails": {
    "location": { "type": "Point", "coordinates": [77.5946, 12.9716] },
    "pincode": "560001",
    "city": "Bangalore"
  },
  "verified": true,
  "enabled": 1
}

Validation (400 on first failure)

Notes

• A second create for the same mobile is rejected (400).
• userCode is generated by Aarambh — do not send your own.
• notification is stored against the rider's user record; device is stored as a device record linked to the rider.

{ "message": "Agent created successfully",
  "data": { "userId": "...", "agentId": "...", "userCode": "sck0005", "vendorCode": "<subscriberid>" } }

POST/v1/agent/update

{
  "UserCode": "sck0005",
  "timestamp": "2026-08-31T06:20:00Z",
  "isActive": true,
  "vehicle": { "brand": "Hero", "number": "KA01AB1234" },
  "notification": { "provider": "samsung", "token": "<fcm>", "enabled": true },
  "device": { "manufacturer": "samsung", "model": "SM-S911B" }
}

POST/v1/agent/live-location

A GPS ping for a rider. Location only — it does not change online / available state. Rate-limited per subscriber → 429 with a Retry-After header.

{ "UserCode": "sck0005", "currentLocation": ["12.912345", "77.612345"] }

UserCode required non-empty; currentLocation required, same 2-element / 6-decimal rule.

POST/v1/agent/acquireSession

Issues a session token for a rider created with agent/create. This is the token your app passes to the Aarambh SDK's login() — see the SDK integration guide. Call it whenever the app needs a fresh token (e.g. on each login), not just once at registration.

{
  "UserCode": "sck0005",
  "notifyToken": "<FCM device token for push notifications>"
}

{ "message": "session acquired successfully",
  "data": {
    "token": "<session token>",
    "agentDetails": { "_id": "...", "agentId": "...", "isAvailable": true, "role": "Agent" },
    "currentUser": {
      "_id": "...", "name": "Shashank Rao", "email": "", "role": "Agent",
      "userCode": "sck0005", "deviceId": "...", "enabled": 1, "isAccountLocked": false
    },
    "issued_at": "2026-09-23T06:19:09.467Z"
  } }

Unknown UserCode for your subscriber → 404.

GET/v1/agent/{userCode}/location

Reads the rider's current position from your {{WEBHOOK_URI}}/agent/position?userCode=<userCode> and returns your response unchanged.

Order APIs

You call these to report order lifecycle events.

POST/v1/order/status/update

{
  "order_id": "ORD-1788156784513-12|bdtest",
  "transaction_id": "TXN-1788156784513-12|bdtest",
  "status": "Order-picked-up",
  "assignee": "sck0005",
  "timestamp": "2026-08-31T07:00:00Z",
  "call_back_support": "no",
  "proof": { "type": "OTP", "code": "8309", "image": "https://.../pod.jpg", "gps": "12.912345,77.612345" }
}

What the gateway checks (each stop → the noted status, nothing is applied)

1. The assignee resolves to one of your riders — else 404 INVALID_USERCODE.
2. The order exists for your subscriber — else 404.
3. The order isn't already finished (Order-delivered / RTO-Delivered / RTO-Disposed / Cancelled) — if it is, you get 200 { "skipped": true } and nothing changes.
4. Strictly one step forward along Agent-assigned → At-pickup → Order-picked-up → Out-for-delivery → At-delivery → Order-delivered — see the rules section. Backwards → 409 STATUS_REGRESSION; skipping a step → 409 NON_INCREMENTAL_STATUS; the same status again → 200 no-op.
5. Confirmation gate: when the order requires a pickup / delivery code, that code must have been confirmed first (via order/event) — else 409 PCC_NOT_VERIFIED / 409 DCC_NOT_VERIFIED (FIFO pickup: 409 PCC_SCAN_REQUIRED). RTO-Delivered similarly needs an rto-verification event when the order carries an RTO code → 409 RTO_NOT_VERIFIED.
6. Idempotent: repeating the same (order_id, status) within a short window returns 200 { "idempotent": true } and is not re-processed. A failed attempt clears the window so you can retry.

Behavior by status

On success the response is 200. Terminal / same-rank calls return { "skipped": true, ... }; repeats return { "idempotent": true, ... }.

POST/v1/order/status/cancel

{
  "order_id": "ORD-...",
  "transaction_id": "TXN-...",
  "bap_id": "protocol.lbnp.preprod.aarambh.cloud",
  "cancellation_reason_id": "013",
  "cancellation_reason": "Customer unreachable",
  "is_rto": false
}

• order_id, transaction_id — required, non-empty.
• is_rto — optional; strict boolean. true routes the cancellation as a return.
• cancellation_reason_id — optional; an ONDC reason code, used as-is (falls back to "013").

The order is cancelled and the buyer platform is notified. If the order was already past pickup, the cancellation is treated as a return (initiated or disposed, per the order's RTO configuration). Terminal orders return 200 with no change; repeats are idempotent.

POST/v1/order/event

{ "order_id": "ORD-...", "transaction_id": "TXN-...",
  "events": { "type": "otp", "value": "8309" } }

POST/v1/order/nearest

Passes through to your {{BASE_URI}}/order/getNearest. Body { "coordinates": ["<lat>","<lng>"], "limit": 5, "radius": 5 }; coordinates required.

GET/v1/order/getOrder/{id}

Returns the order (by order_id, or task_id) in the same shape as the order/create webhook payload. 404 if the order isn't found for your subscriber.

{
  "order_id": "ORD-...",
  "pickupProof": { "type": "OTP", "enabled": true, "image": true, "gps_enabled": true, "verification_type": "AARAMBH" },
  "dropProof": { /* same shape */ },
  "rtoProof": { /* drop shape, enabled when the order is RTO-configured */ },
  "start": { "location": { "gps": "13.026000,77.593500", "address": { ... } }, "contact": { "phone": "...", "email": "..." } },
  "end": { "location": { "gps": "12.908300,77.605000", "address": { ... }, "contact": { ... } } },
  "quote": { "price": "267.03", "breakup": [ { "type": "delivery", "price": "226.30" }, { "type": "tax", "price": "40.73" } ] },
  "payment": { "type": "ON-ORDER", "amount": "" },
  "merchant_order_id": "bdtest|1788156784513",
  "retail_item_details": [ { "name": "...", "quantity": "2", "price": "3" } ],
  "parcel_type": "P3",
  "support": { "type": "", "contact": "" },
  "groupable": false,
  "sla": { "pickup": "PT15M", "delivery": "PT60M", "cancellation": "" },
  "rto_enabled": true,
  "status": "Agent-assigned"
}

Notification APIs

You call this to have the gateway relay a push notification to your own {{WEBHOOK_URI}}.

POST/v1/notification/create

Forwards the request body as-is to {{WEBHOOK_URI}}/notification/push (ar-access-key / ar-secret-key) and returns your webhook's response back to you, wrapped in the standard success envelope.

{
  "order_id": "ORD-1788156784513-12|bdtest",
  "transaction_id": "TXN-1788156784513-12|bdtest",
  // ...any other fields your {{WEBHOOK_URI}}/notification/push endpoint expects
}

• order_id — optional, but when present the call is also recorded as a notificationCreate event against that order's sync history (created if it doesn't already exist for your subscriber).
• transaction_id — optional; stored alongside the sync record when order_id is present.

{ "message": "Notification created successfully",
  "data": /* whatever your {{WEBHOOK_URI}}/notification/push endpoint returned */ }

If the call to your {{WEBHOOK_URI}}/notification/push fails, you get 502 with partnerStatus / partnerResponse — same as any other upstream call the gateway makes on your behalf.

Payment APIs

Read-only. You call these to fetch what a rider earned — per order, per rider over a date range, and the incentives a rider unlocked over a date range. Figures are the ones Aarambh settled for the order; nothing is recalculated on read.

• Dates: from and to are YYYY-MM-DD, both required and both inclusive. A range can span at most 31 days.
• Day boundary: a day is the operational day, 06:00 IST → 06:00 IST — an order settled at 02:00 on the 2nd belongs to the 1st.
• Rider: identified by the userCode returned from agent/create.

GET/v1/payment/order_earning/{orderId}

The earning for one order: the rider who completed it, the amount, and its breakup. 404 if no earning has been settled for that order_id under your subscriber.

{ "message": "Order earning fetched successfully",
  "data": {
    "order_id": "ORD-1788156784513-12|bdtest",
    "user_code": "sck0005",
    "amount": 120,
    "breakup": { "base_price": 40, "last_mile_charges": 30, "first_mile_charges": 10, "surge": 20, "rto_earning": 0, "rain_charge": 20, "adjustment": 0 },
    "first_mile_distance": 1.2,
    "last_mile_distance": 4.5,
    "rto_distance": 0,
    "type": "system_calculated",
    "earned_at": "2026-09-01T05:00:00.000Z"
  } }

GET/v1/payment/rider_earning/{userCode}?from=&to=

A rider's earnings over a date range: the total, and one entry per order in the same shape as order_earning (each with its own breakup). A rider with no earnings in the range returns amount: 0 and an empty orders list.

GET /v1/payment/rider_earning/sck0005?from=2026-09-01&to=2026-09-07

{ "message": "Rider earning fetched successfully",
  "data": {
    "user_code": "sck0005",
    "from": "2026-09-01",
    "to": "2026-09-07",
    "amount": 180,                 // sum of orders[].amount
    "total_orders": 2,
    "orders": [
      {
        "order_id": "ORD-1788156784513-12|bdtest",
        "amount": 120,
        "breakup": { "base_price": 40, "last_mile_charges": 30, "first_mile_charges": 10, "surge": 20, "rto_earning": 0, "rain_charge": 20, "adjustment": 0 },
        "first_mile_distance": 1.2,
        "last_mile_distance": 4.5,
        "rto_distance": 0,
        "type": "system_calculated",
        "earned_at": "2026-09-01T05:00:00.000Z"
      },
      { "order_id": "ORD-1788156799001-04|bdtest", "amount": 60, "breakup": { /* same shape */ }, ... }
    ]
  } }

GET/v1/payment/rider_incentive/{userCode}?from=&to=

The incentives a rider unlocked over a date range: the total, its split by incentive type, and per incentive cycle the slabs that were unlocked. A rider with nothing unlocked in the range returns total_incentive: 0 and an empty incentives list.

GET /v1/payment/rider_incentive/sck0005?from=2026-09-01&to=2026-09-07

{ "message": "Rider incentive fetched successfully",
  "data": {
    "user_code": "sck0005",
    "from": "2026-09-01",
    "to": "2026-09-07",
    "total_incentive": 350,
    "breakup": { "daily": 50, "weekly": 300, "festival": 0 },
    "incentives": [
      {
        "incentive_id": "7c1f...",
        "name": "Weekly booster",
        "type": "WEEKLY",
        "incentive_on": "ordercount",
        "period": "2026-W36",
        "total_orders": 42,
        "total_earnings": 3000,
        "amount": 300,
        "slabs": [
          { "slab_count": 20, "slab_amount": 100, "amount": 100, "unlocked_at": "2026-09-01T06:30:00.000Z" },
          { "slab_count": 40, "slab_amount": 300, "amount": 200, "unlocked_at": "2026-09-04T06:30:00.000Z" }
        ]
      },
      { "name": "Daily 10", "type": "DAILY", "period": "2026-09-04", "amount": 50, ... }
    ]
  } }

Maps APIs

Road routing, snapping and reachability over Aarambh's own map server (GraphHopper 12.0, OpenStreetMap data for India). This is a separate service from the gateway: its own base URI, its own key, and GraphHopper's request / response shapes — not the gateway's { message, data } envelope.

• Coordinate order differs by format. The point query param is lat,lon (point=12.9716,77.5946). Every JSON / GeoJSON body and response — POST points, coordinates, bbox — is [lon, lat].
• Units: distance in metres, time in milliseconds.
• Polylines: points_encoded defaults to true (Google polyline, multiplier 1e5). Pass points_encoded=false for a GeoJSON LineString.

GET/route

Driving route through two or more points, in order: distance, ETA, geometry and optional turn-by-turn.

GET https://api-maps.aarambh.cloud/route?point=12.9716,77.5946&point=12.9352,77.6245&profile=car&points_encoded=false&key={{MAPS_API_KEY}}

{ "info": { "copyrights": ["GraphHopper", "OpenStreetMap contributors"], "took": 11, "road_data_timestamp": "2026-04-24T20:20:51Z" },
  "paths": [ {
    "distance": 6579.883,          // metres
    "time": 263196,              // milliseconds
    "bbox": [77.594568, 12.934965, 77.624481, 12.971707],
    "points_encoded": false,
    "points": { "type": "LineString", "coordinates": [[77.594568, 12.971606], [77.594588, 12.971707], /* … */] },
    "snapped_waypoints": { "type": "LineString", "coordinates": [[77.594568, 12.971606], [77.624481, 12.935222]] },
    "instructions": [
      { "text": "Continue",  "sign": 0,  "distance": 58.02,  "time": 2321, "interval": [0, 3], "street_name": "" },
      { "text": "Turn left", "sign": -2, "distance": 13.486, "time": 539,  "interval": [3, 5], "street_name": "" }
      /* … */
    ],
    "details": { "road_class": [[0, 2, "footway"], [2, 5, "service"] /* … */] }
  } ] }

POST/route

Same as GET, with the request as a JSON body. Use it for many points, and for custom_model, which only exists in POST. Note points is [lon, lat].

POST https://api-maps.aarambh.cloud/route
X-API-Key: {{MAPS_API_KEY}}
Content-Type: application/json

{
  "points": [[77.5946, 12.9716], [77.6245, 12.9352]],
  "profile": "car",
  "points_encoded": false,
  "instructions": false,
  "details": ["road_class"],
  "ch.disable": true,
  "custom_model": {
    "speed":    [{ "if": "road_class == MOTORWAY", "limit_to": "60" }],
    "priority": [{ "if": "road_class == TRACK",   "multiply_by": "0" }]
  }
}

• Every GET param maps to a body field of the same name; repeatable params become arrays (details, headings, curbsides, snap_preventions).
• custom_model rules: speed (limit_to km/h or multiply_by), priority (multiply_by; 0 forbids the road), and areas (GeoJSON polygons to reference as in_<area_id>). Conditions can use the encoded values listed by /info, e.g. road_class, road_environment, max_speed, roundabout, country.
• A custom_model needs "ch.disable": true.

POST/match?profile=car

Map matching: snaps a recorded GPS trace onto roads. Use it to compute the distance a rider actually drove from their location pings. The response has the same shape as /route, plus a map_matching summary.

POST https://api-maps.aarambh.cloud/match?profile=car&points_encoded=false&gps_accuracy=40&key={{MAPS_API_KEY}}
Content-Type: application/gpx+xml

<gpx version="1.1" creator="dms"><trk><trkseg>
  <trkpt lat="12.9716" lon="77.5946"><time>2026-10-05T10:00:00Z</time></trkpt>
  <trkpt lat="12.9690" lon="77.5990"><time>2026-10-05T10:01:00Z</time></trkpt>
  <trkpt lat="12.9650" lon="77.6040"><time>2026-10-05T10:02:00Z</time></trkpt>
</trkseg></trk></gpx>

{ "map_matching": { "original_distance": 1258.56, "distance": 1689.691, "time": 67585 },
  "paths": [ { "distance": 1689.691, "time": 67585, "points": { /* matched LineString */ }, /* … as /route */ } ] }

• gps_accuracy (m, default 40): how far a ping may sit from the road. Raise it for noisy traces.
• original_distance is the straight-line sum between pings; distance is the matched on-road distance.
• Accepts the same output params as /route (points_encoded, instructions, details, type=gpx).

GET/isochrone

The area reachable from a point within a time or distance limit, as GeoJSON polygons — e.g. "everywhere a rider can reach in 10 minutes", for serviceability zones.

GET https://api-maps.aarambh.cloud/isochrone?point=12.9716,77.5946&profile=car&time_limit=600&buckets=2&key={{MAPS_API_KEY}}

{ "polygons": [
    { "type": "Feature", "properties": { "bucket": 0 },
      "geometry": { "type": "Polygon", "coordinates": [[[77.470879, 12.988645], [77.471762, 12.988897], /* … */]] } }
  ],
  "info": { "took": 556, /* … */ } }

Isochrones are the slowest call — a 10-minute limit in a dense city can take several seconds. Cache results rather than computing one per request.

GET/spt

Shortest-path tree: every road node reachable within the limit, with its travel time and distance from the point. Returned as CSV. Same point, time_limit, distance_limit and reverse_flow params as /isochrone.

GET https://api-maps.aarambh.cloud/spt?point=12.9716,77.5946&profile=car&distance_limit=500&columns=longitude,latitude,time,distance,prev_longitude,prev_latitude,edge_id&key={{MAPS_API_KEY}}

longitude,latitude,time,distance,prev_longitude,prev_latitude,edge_id
77.594568,12.971606,0,0,null,null,-1
77.594714,12.971656,1045,26,77.594568,12.971606,24160304
…

• columns defaults to longitude,latitude,time,distance. Also available: prev_longitude, prev_latitude, prev_time, prev_distance, edge_id, base_node, adj_node, and any encoded value from /info (e.g. road_class).
• time is milliseconds, distance metres.

GET/nearest

Snaps one coordinate to the closest point on the road network. Use it to check a pickup / drop pin is on a reachable road, or to clean up a rider's raw GPS position.

GET https://api-maps.aarambh.cloud/nearest?point=12.9716,77.5946&profile=car&key={{MAPS_API_KEY}}

{ "type": "Point", "coordinates": [77.594567, 12.971606], "distance": 3.57 }   // snapped [lon, lat]; metres moved

GET/info

Server metadata: coverage bbox, profiles, engine version, data dates, and the encoded values usable in details, custom_model and /spt columns.

{ "bbox": [68.262955, 6.756888, 97.329353, 35.568624],
  "profiles": [{ "name": "car" }],
  "version": "12.0",
  "elevation": false,
  "import_date": "2026-09-20T11:59:21Z",
  "data_date": "2026-04-24T20:20:51Z",
  "encoded_values": { "road_class": ["OTHER", "MOTORWAY", /* … */], "max_speed": [">number", "<number"], /* … */ } }

Errors

Errors are { "message": "…", "hints": [{ "message", "details", … }] }. Not served on this server: /matrix, /route-pt (public transit), /navigate, /mvt vector tiles and geocoding. For many-to-many distances, call /route with calc_points=false per pair.

Webhook (Aarambh → you)

The gateway calls your {{WEBHOOK_URI}} with the ar-access-key / ar-secret-key pair. For the order/* POSTs below, Aarambh sends the full payload (shown in getOrder); rider/allocate and rider/payment are described below. You respond 200 with your own body, which is passed straight back to the original caller.

POST{{WEBHOOK_URI}}/rider/allocate

Aarambh pushes this when a rider is assigned to an order — the order moves from Searching-for-Agent to Agent-assigned. It tells you which of your riders (userCode) now holds the order, with the pickup and drop points.

• If your endpoint returns a 5xx, the push is retried up to 3 more times with backoff (0.5s, 1s, 2s), then dropped. A 4xx is not retried. A failed push never affects the assignment.
• You can receive the same payload more than once: key on order_id and treat a repeat as the same allocation.
• Respond 200; your body is not interpreted.

{
  "order_id": "ORD-1788156784513-12|bdtest",
  "transaction_id": "3f1d9a3c-5b8e-4f62-9d0a-6b7f2c1e8a44",
  "task_id": "T-1788156784513",
  "userCode": "sck0005",
  "pickup": {
    "location": { "gps": "12.9352,77.6245",
      "address": { "name": "Store 12", "building": "", "locality": "Koramangala", "city": "Bengaluru", "state": "Karnataka", "country": "IND", "area_code": "560034" } },
    "contact": { "phone": "9876543210", "email": "" },
    "person": { "name": "Store 12" },
    "time": { "range": { "start": "2026-10-06T10:00:00.000Z", "end": "2026-10-06T10:30:00.000Z" } },
    "instructions": { "code": "2", "short_desc": "" }
  },
  "drop": { /* same shape as pickup */ }
}

POST{{WEBHOOK_URI}}/rider/payment

Aarambh pushes the rider's payout for an order as soon as it is settled. Today this fires when an order ends RTO-Disposed — the rider could not hand over the parcel and the order is not returned to the pickup point — so the rider (userCode) is paid for the attempt. The earning pushed here is the same one later returned by payment/order_earning.

• If your endpoint returns a 5xx, the push is retried up to 3 more times with backoff (0.5s, 1s, 2s), then dropped. A 4xx is not retried. A failed push never affects the order — use payment/order_earning to reconcile anything you missed.
• Because of retries you can receive the same payload more than once: key on order_id and treat a repeat as the same payout, not a second one.
• Respond 200; your body is not interpreted.

{
  "order_id": "ORD-1788156784513-12|bdtest",
  "status": "RTO-Disposed",
  "amount": "64",
  "orderId": "ORD-1788156784513-12|bdtest",
  "fm_distance": 1.42,
  "last_mile_distance": 5.8,
  "breakup": {
    "baseCharge": 54,
    "rainCharge": 10,
    "surgeLevel": 1,
    "surgeLocation": "Koramangala",
    "basePrice": 30,
    "lmCharges": 18,
    "fmCharges": 6,
    "surgePrice": 0,
    "rtoEarning": 0,
    "pricingMode": "rate_card",
    "pricePatternId": "6f1c2a9e-...",
    "pricingSource": { "level": "agent_card", "patternId": "6f1c2a9e-...", "patternVersion": 3 }
  },
  "created_by": "<your subscriberid>",
  "pricingMode": "rate_card",
  "pickup": {
    "location": { "gps": "12.9352,77.6245",
      "address": { "name": "Store 12", "building": "", "locality": "Koramangala", "city": "Bengaluru", "state": "Karnataka", "country": "IND", "area_code": "560034" } },
    "contact": { "phone": "9876543210", "email": "" },
    "person": { "name": "Store 12" },
    "time": { "range": { "start": "2026-10-06T10:00:00.000Z", "end": "2026-10-06T10:30:00.000Z" } },
    "instructions": { "code": "2", "short_desc": "" }
  },
  "drop": { /* same shape as pickup */ },
  "userCode": "sck0005"
}

Status & verification rules

Strictly-incremental status progression

The forward track advances one step at a time:

• Sending an earlier status → 409 STATUS_REGRESSION.
• Sending the same status → 200 no-op.
• Sending a status more than one step ahead → 409 NON_INCREMENTAL_STATUS (the response tells you the one status you may send next).
• The first status must be Agent-assigned.
• RTO-Initiated, RTO-Delivered, Cancelled are not part of the forward track.

Pickup / delivery confirmation (PCC / DCC)

If the order has no code for a leg, that gate simply doesn't apply. Order-picked-up and Order-delivered also require proof (proof.image or proof.code) in the status call.

Return verification (RTO)

When an order carries an RTO code, RTO-Delivered is only accepted after an order/event with type: "rto-verification" whose value matches that code.

Idempotency & failures

• Repeating status/update for the same (order_id, status), or status/cancel for the same order_id, within a short window returns 200 { "idempotent": true } and is not re-processed. A failed attempt clears the window so a genuine retry goes through.
• If a call the gateway makes to your endpoints fails, you get 502 with partnerStatus / partnerResponse — it is never reported as 200.

End-to-end flows

Error reference