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 byhttps://api.apps.lute.co.in/v1 conforms to one of two shapes.
Successful Response Envelope
success(boolean): Alwaystruefor2xxHTTP status codes.data(object | array): The requested resource or collection.meta(object, optional): Includes ISO 8601 server timestamp, uniquerequest_idfor auditing, and API version.
Error Response Envelope
When a request cannot be processed (4xx or 5xx), Shipdesk returns a structured error envelope:
success(boolean): Alwaysfalse.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:- Normalized Carrier Names:
Carriers are consistently identified as
Delhivery,Shadowfax,Xpressbees, orEkart. - Normalized Service Modes:
Services are strictly categorized as
SurfaceorExpress(e.g.,Delhivery - Express,Ekart - Surface). - Normalized Tracking Events: Scans are unified into ISO 8601 timestamps, standardized stages, clean English descriptions, and normalized locations (City, State).
- 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)
- 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.