Skip to main content

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:
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

  • 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:
  • 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:

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