> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.lute.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Standardised JSON Schema

> Specifications of the unified Shipdesk JSON envelope, status lifecycle, error handling, and courier abstraction guarantees.

# Standardised Shipdesk JSON Schema

Shipdesk operates as an abstraction layer between your storefront and multiple courier networks (Delhivery, Shadowfax, Xpressbees, Ekart). A foundational design goal is **strict schema consistency**:

> [!NOTE]
>
> **Zero Courier Leaks**: All API responses follow a predictable Shipdesk schema. We never expose raw courier payloads, courier-specific error codes, internal database IDs, or carrier tokens.

***

## 1. Top-Level Response Envelopes

Every JSON response returned by `https://api.apps.lute.co.in/v1` conforms to one of two shapes.

### Successful Response Envelope

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2026-11-22T16:25:00.000Z",
    "request_id": "req_01h8q7k2v9z4",
    "version": "v1"
  }
}
```

* `success` (boolean): Always `true` for `2xx` HTTP status codes.
* `data` (object | array): The requested resource or collection.
* `meta` (object, optional): Includes ISO 8601 server timestamp, unique `request_id` for auditing, and API version.

***

### Error Response Envelope

When a request cannot be processed (`4xx` or `5xx`), Shipdesk returns a structured error envelope:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_pincode",
    "message": "The delivery PIN code 999999 is invalid or not served by any connected carrier.",
    "details": [
      {
        "field": "pin",
        "issue": "Must be an active 6-digit Indian postal code"
      }
    ]
  }
}
```

* `success` (boolean): Always `false`.
* `error.code` (string): Machine-readable snake\_case error code.
* `error.message` (string): Human-friendly description of what went wrong and how to correct it.
* `error.details` (array, optional): Specific field validation errors.

***

## 2. Standardized Status Lifecycle

Individual courier APIs use dozens of disparate status strings (e.g. `DL`, `UD`, `OFD`, `RTO-INIT`, `RAD`, `INTRANSIT`). Shipdesk maps all carrier updates into a single lifecycle:

```mermaid theme={null}
flowchart LR
  U["Awaiting AWB"] --> R["Ready to ship"]
  R --> PS["Pickup scheduled"]
  PS --> PU["Picked up"]
  PU --> IT["In transit"]
  IT --> OFD["Out for delivery"]
  OFD --> DEL["Delivered"]
  OFD --> NDR["NDR Action required"]
  NDR --> IT
  NDR --> RTO["RTO"]
  U -.-> CAN["Cancelled"]
  R -.-> CAN
```

| Shipdesk Standard Status | Description |
| - | - |
| `Awaiting AWB` | Order created in Shipdesk; no courier or AWB assigned yet. |
| `Ready to ship` | Courier assigned, AWB generated, and barcode label ready for printing. |
| `Pickup scheduled` | Carrier pickup booked from your registered warehouse. |
| `Picked up` | Parcel handed over to the courier executive at the warehouse. |
| `In transit` | Parcel moving through carrier sorting hubs and line-hauls. |
| `Out for delivery` | Parcel assigned to a delivery rider for final-mile delivery. |
| `Delivered` | Successfully received and acknowledged by the customer. |
| `RTO` (Return to Origin) | Undelivered parcel being returned to your warehouse. |
| `Cancelled` | Shipment cancelled with the courier partner before dispatch. |

***

## 3. Courier Abstraction Guarantees

When interacting with the Shipdesk API, your application is shielded from carrier idiosyncrasies:

1. **Normalized Carrier Names**:
   Carriers are consistently identified as `Delhivery`, `Shadowfax`, `Xpressbees`, or `Ekart`.
2. **Normalized Service Modes**:
   Services are strictly categorized as `Surface` or `Express` (e.g., `Delhivery - Express`, `Ekart - Surface`).
3. **Normalized Tracking Events**:
   Scans are unified into ISO 8601 timestamps, standardized stages, clean English descriptions, and normalized locations (City, State).
4. **Standardized NDR Reasons**:
   Exceptions are classified into clear categories:
   * `customer_unreachable` (Customer phone switched off or unanswered)
   * `customer_rescheduled` (Customer requested delivery on a future date)
   * `address_incomplete` (Incorrect premises or missing landmark)
   * `cod_amount_not_ready` (Customer did not have cash ready)
   * `customer_refused` (Customer rejected package)
5. **No Credential Ingress**:
   Carrier tokens, API passwords, and webhook secrets are stored with AES-256-GCM encryption in isolated tables and are never surfaced in public API responses.

***

## 4. Standard Error Codes Reference

| Error Code | HTTP Status | Meaning |
| - | - | - |
| `unauthorized` | 401 | Missing or invalid API key |
| `forbidden` | 403 | API key lacks permission for the requested action |
| `resource_not_found` | 404 | Order, pickup, or AWB does not exist in your account |
| `validation_failed` | 400 | Request body failed schema validation (e.g. invalid phone number) |
| `courier_refused` | 422 | Courier API rejected the request (e.g. unserved PIN, wallet balance below minimum) |
| `pickup_conflict` | 409 | Pickup cannot be rescheduled for the requested time slot |
| `rate_limit_exceeded` | 429 | Exceeded per-minute request limit |
| `courier_unavailable` | 502 | Carrier network timed out or is temporarily unreachable |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.