{
    "openapi": "3.1.0",
    "info": {
        "title": "ShipSeth Ship API",
        "version": "2026-09-08",
        "summary": "External merchant-facing Booking API for ShipSeth.",
        "description": "Server-to-server API for B2C forward and reverse (RVP) shipments — all payment\nmodes (prepaid, COD, to-pay on forward). Authenticate once with a scoped\n`ship-api:*` token, then manage pickup warehouses, price routes, create a\nshipment in one async call, cancel, schedule pickup, track (single or bulk, by\ntracking number or courier AWB), print labels (single or one merged PDF),\npickup manifests and seller invoices, act on NDRs, and receive signed\n`shipment.status` webhooks.\n\n**Envelope.** Every response body carries `success`, `status`, `message`,\n`request_id`, plus `data` (success) or `code` + `errors` (error). The\n`X-Request-Id` response header echoes the correlation id.\n\n**Auth.** A Ship API token is a Bearer token with scoped abilities\n`ship:booking`, `ship:tracking` and optionally `ship:test`. Mint one with\n`POST /auth/login`.\n",
        "contact": {
            "name": "ShipSeth Developer Support",
            "url": "https://shipseth.com/developers"
        }
    },
    "servers": [
        {
            "url": "https://api.shipseth.com/api/ext/v1",
            "description": "Production"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "Auth"
        },
        {
            "name": "Warehouses"
        },
        {
            "name": "Config"
        },
        {
            "name": "Rates"
        },
        {
            "name": "Shipments"
        },
        {
            "name": "Tracking"
        },
        {
            "name": "Labels"
        },
        {
            "name": "Documents"
        },
        {
            "name": "NDR"
        },
        {
            "name": "Sandbox"
        },
        {
            "name": "Webhooks"
        },
        {
            "name": "Meta"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "A Ship API token (Sanctum PAT named `ship-api:*`). Scoped abilities:\n`ship:booking` (rates, create, cancel, pickup, label, manifest, invoice, NDR action,\nwebhook retry), `ship:tracking` (list, details, track, NDR read, webhook\nlog), `ship:test`\n(test-mode create — no wallet hold, `NullCourierDriver`, excluded from\nfinance).\n"
            }
        },
        "parameters": {
            "Warehouse": {
                "name": "warehouse",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            },
            "Shipment": {
                "name": "shipment",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            },
            "TrackingNumber": {
                "name": "tracking_number",
                "in": "path",
                "required": true,
                "description": "Our `tracking_number` OR the courier AWB (`waybill`).",
                "schema": {
                    "type": "string"
                }
            },
            "BatchFile": {
                "name": "file",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string"
                }
            },
            "Delivery": {
                "name": "delivery",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            },
            "LabelToken": {
                "name": "token",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string"
                }
            },
            "IdempotencyKey": {
                "name": "Idempotency-Key",
                "in": "header",
                "required": true,
                "description": "A UUID unique to this create attempt. Required on `POST /shipments`.",
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            }
        },
        "headers": {
            "X-Request-Id": {
                "description": "Correlation id (echoes an inbound `X-Request-Id` when valid, else a fresh UUID).",
                "schema": {
                    "type": "string"
                }
            },
            "Retry-After": {
                "description": "Seconds to wait before retrying (on `429`).",
                "schema": {
                    "type": "integer"
                }
            },
            "X-RateLimit-Limit": {
                "schema": {
                    "type": "integer"
                }
            },
            "X-RateLimit-Remaining": {
                "schema": {
                    "type": "integer"
                }
            }
        },
        "schemas": {
            "ErrorCode": {
                "type": "string",
                "description": "The full Ship API error-code vocabulary.",
                "enum": [
                    "idempotency_key_required",
                    "idempotency_key_conflict",
                    "idempotency_in_progress",
                    "invalid_credentials",
                    "unauthenticated",
                    "no_account",
                    "account_suspended",
                    "not_a_ship_api_token",
                    "insufficient_ability",
                    "kyc_required",
                    "merchant_agreement_required",
                    "no_warehouse",
                    "invalid_warehouse",
                    "invalid_webhook_url",
                    "unsupported_unit",
                    "no_courier",
                    "no_reverse_courier",
                    "rate_unavailable",
                    "payment_mode_not_allowed_for_reverse",
                    "cod_amount_not_allowed_for_to_pay",
                    "cod_amount_required",
                    "eway_bill_required",
                    "insurance_value_required",
                    "b2b_not_supported",
                    "return_reason_required",
                    "too_many_items",
                    "duplicate_order_reference",
                    "insufficient_balance",
                    "too_many_in_flight",
                    "not_cancellable",
                    "not_ready_for_pickup",
                    "pickup_already_scheduled",
                    "pickup_rejected",
                    "not_booked",
                    "not_manifestable",
                    "no_open_ndr",
                    "ndr_action_failed",
                    "not_a_test_shipment",
                    "invalid_transition",
                    "validation_error",
                    "not_found",
                    "method_not_allowed",
                    "rate_limited",
                    "server_error"
                ]
            },
            "Envelope": {
                "type": "object",
                "required": [
                    "success",
                    "status",
                    "message",
                    "request_id"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": true
                    },
                    "status": {
                        "type": "integer"
                    },
                    "message": {
                        "type": "string"
                    },
                    "data": [],
                    "request_id": {
                        "type": "string"
                    }
                }
            },
            "ErrorEnvelope": {
                "type": "object",
                "required": [
                    "success",
                    "status",
                    "message",
                    "code",
                    "request_id"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": false
                    },
                    "status": {
                        "type": "integer"
                    },
                    "message": {
                        "type": "string"
                    },
                    "code": {
                        "$ref": "#/components/schemas/ErrorCode"
                    },
                    "errors": {
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "nullable": true
                    },
                    "request_id": {
                        "type": "string"
                    }
                }
            },
            "Dimensions": {
                "type": "object",
                "required": [
                    "length",
                    "width",
                    "height"
                ],
                "properties": {
                    "length": {
                        "type": "number"
                    },
                    "width": {
                        "type": "number"
                    },
                    "height": {
                        "type": "number"
                    },
                    "unit": {
                        "type": "string",
                        "enum": [
                            "cm",
                            "mm",
                            "in"
                        ],
                        "default": "cm"
                    }
                }
            },
            "Parcel": {
                "type": "object",
                "required": [
                    "weight",
                    "dimensions"
                ],
                "properties": {
                    "weight": {
                        "type": "number"
                    },
                    "weight_unit": {
                        "type": "string",
                        "enum": [
                            "kg",
                            "g"
                        ],
                        "default": "kg"
                    },
                    "package_count": {
                        "type": "integer",
                        "minimum": 1,
                        "default": 1
                    },
                    "dimensions": {
                        "$ref": "#/components/schemas/Dimensions"
                    }
                }
            },
            "Item": {
                "type": "object",
                "required": [
                    "name",
                    "quantity"
                ],
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "sku": {
                        "type": "string"
                    },
                    "hsn": {
                        "type": "string"
                    },
                    "quantity": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "unit_price": {
                        "type": "number",
                        "description": "Rupees, ≤ 2 decimals."
                    },
                    "discount": {
                        "type": "number"
                    },
                    "tax_rate": {
                        "type": "number",
                        "description": "Percent."
                    }
                }
            },
            "Consignee": {
                "type": "object",
                "required": [
                    "name",
                    "address",
                    "pincode",
                    "city",
                    "state",
                    "phone"
                ],
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "address": {
                        "type": "string"
                    },
                    "address_line_2": {
                        "type": "string"
                    },
                    "pincode": {
                        "type": "string",
                        "pattern": "^\\d{6}$"
                    },
                    "city": {
                        "type": "string"
                    },
                    "state": {
                        "type": "string"
                    },
                    "phone": {
                        "type": "string"
                    },
                    "email": {
                        "type": "string",
                        "format": "email"
                    }
                }
            },
            "RateOption": {
                "type": "object",
                "properties": {
                    "rate_id": {
                        "type": "string",
                        "description": "Opaque, stable for the quote's life. The booking key."
                    },
                    "courier_code": {
                        "type": "string"
                    },
                    "courier_name": {
                        "type": "string"
                    },
                    "service": {
                        "type": "string"
                    },
                    "mode": {
                        "type": "string"
                    },
                    "total": {
                        "type": "number"
                    },
                    "freight": {
                        "type": "number"
                    },
                    "cod_charge": {
                        "type": "number"
                    },
                    "surcharges": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "code": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "amount": {
                                    "type": "number"
                                }
                            }
                        }
                    },
                    "gst": {
                        "type": "number"
                    },
                    "edd_min": {
                        "type": [
                            "integer",
                            "string",
                            "null"
                        ]
                    },
                    "edd_max": {
                        "type": [
                            "integer",
                            "string",
                            "null"
                        ]
                    },
                    "edd_source": {
                        "type": "string"
                    }
                }
            },
            "Warehouse": {
                "type": "object",
                "properties": {
                    "warehouse_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "contact_person": {
                        "type": "string"
                    },
                    "address": {
                        "type": "string"
                    },
                    "address_line_2": {
                        "type": "string",
                        "nullable": true
                    },
                    "city": {
                        "type": "string"
                    },
                    "state": {
                        "type": "string"
                    },
                    "pincode": {
                        "type": "string"
                    },
                    "phone": {
                        "type": "string"
                    },
                    "alternate_phone": {
                        "type": "string",
                        "nullable": true
                    },
                    "email": {
                        "type": "string",
                        "nullable": true
                    },
                    "gstin": {
                        "type": "string",
                        "nullable": true
                    },
                    "is_default": {
                        "type": "boolean"
                    }
                }
            },
            "CanonicalStatus": {
                "type": "string",
                "description": "`LOST` / `DAMAGED` come from the courier's own label while the parcel\nis moving (picked up → out for delivery, or on the RTO leg). They are\nfinal unless the courier later recovers the parcel, in which case the\nnext scan's status is sent.\n",
                "enum": [
                    "PROCESSING",
                    "MANIFESTED",
                    "PICKUP_SCHEDULED",
                    "PICKED_UP",
                    "IN_TRANSIT",
                    "OUT_FOR_DELIVERY",
                    "DELIVERED",
                    "NDR",
                    "RTO_INITIATED",
                    "RTO_DELIVERED",
                    "CANCELLED",
                    "FAILED",
                    "LOST",
                    "DAMAGED"
                ]
            },
            "Milestone": {
                "type": "object",
                "properties": {
                    "canonical_status": {
                        "$ref": "#/components/schemas/CanonicalStatus"
                    },
                    "current_status": {
                        "type": "string"
                    },
                    "location": {
                        "type": "string",
                        "nullable": true
                    },
                    "remarks": {
                        "type": "string",
                        "nullable": true
                    },
                    "scanned_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                }
            },
            "Failure": {
                "type": [
                    "object",
                    "null"
                ],
                "description": "Set only when `canonical_status = FAILED`. A cleaned reason — never the raw courier response.",
                "properties": {
                    "category": {
                        "type": "string",
                        "enum": [
                            "serviceability",
                            "warehouse",
                            "infra",
                            "transient",
                            "other"
                        ]
                    },
                    "reason": {
                        "type": "string"
                    }
                }
            },
            "Ndr": {
                "type": "object",
                "properties": {
                    "attempt_number": {
                        "type": "integer"
                    },
                    "reason": {
                        "type": "string",
                        "nullable": true,
                        "description": "Courier's non-delivery reason."
                    },
                    "reason_code": {
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "open",
                            "actioned",
                            "resolved",
                            "escalated"
                        ]
                    },
                    "action": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "re_attempt",
                            "change_address",
                            "change_phone",
                            "rto",
                            null
                        ]
                    },
                    "action_deadline": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true,
                        "description": "Act before this or the shipment auto-escalates."
                    },
                    "actionable": {
                        "type": "boolean",
                        "description": "true → POST /shipments/{shipment}/ndr/action will be accepted."
                    },
                    "sent_to_courier": {
                        "type": "boolean"
                    },
                    "raised_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "resolved_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                }
            },
            "Tracking": {
                "type": "object",
                "properties": {
                    "tracking_number": {
                        "type": "string"
                    },
                    "waybill": {
                        "type": "string",
                        "nullable": true
                    },
                    "order_reference": {
                        "type": "string"
                    },
                    "direction": {
                        "type": "string",
                        "enum": [
                            "forward",
                            "reverse"
                        ]
                    },
                    "canonical_status": {
                        "$ref": "#/components/schemas/CanonicalStatus"
                    },
                    "current_status": {
                        "type": "string"
                    },
                    "courier_code": {
                        "type": "string",
                        "nullable": true
                    },
                    "origin": {
                        "type": "object",
                        "properties": {
                            "city": {
                                "type": "string"
                            },
                            "state": {
                                "type": "string"
                            }
                        }
                    },
                    "destination": {
                        "type": "object",
                        "properties": {
                            "city": {
                                "type": "string"
                            },
                            "state": {
                                "type": "string"
                            }
                        }
                    },
                    "eta": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "is_test": {
                        "type": "boolean"
                    },
                    "failure": {
                        "$ref": "#/components/schemas/Failure"
                    },
                    "ndr": {
                        "description": "Latest NDR attempt — set only when `canonical_status = NDR`.",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/Ndr"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "milestones": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Milestone"
                        }
                    }
                }
            },
            "PageMeta": {
                "type": "object",
                "properties": {
                    "page": {
                        "type": "integer"
                    },
                    "per_page": {
                        "type": "integer"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "last_page": {
                        "type": "integer"
                    }
                }
            }
        },
        "responses": {
            "Error": {
                "description": "Error (see `code`).",
                "headers": {
                    "X-Request-Id": {
                        "$ref": "#/components/headers/X-Request-Id"
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorEnvelope"
                        }
                    }
                }
            }
        }
    },
    "webhooks": {
        "shipment.status": {
            "post": {
                "summary": "Outbound shipment status webhook",
                "description": "Sent to the account's `webhook_url` on every merchant-visible transition\nof an `api`-sourced shipment (internal churn Draft→…→Booking_Requested is\nnever sent). Headers: `X-ShipSeth-Event: shipment.status`,\n`X-ShipSeth-Delivery: <uuid>`, `X-ShipSeth-Timestamp: <unix>`,\n`X-ShipSeth-Signature: t=<unix>,v1=<hex hmac_sha256(<unix> \".\" <raw_body>, webhook_secret)>`.\nReject if `abs(now - t) > 300`. 5 attempts: first send, then retries\n1m, 5m, 30m and 2h apart (~2h36m in all) → `exhausted`. Redirects are not followed.\n",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "event": {
                                        "type": "string",
                                        "const": "shipment.status"
                                    },
                                    "id": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "created": {
                                        "type": "integer",
                                        "description": "unix seconds"
                                    },
                                    "data": {
                                        "type": "object",
                                        "properties": {
                                            "tracking_number": {
                                                "type": "string"
                                            },
                                            "shipment_id": {
                                                "type": "string",
                                                "format": "uuid"
                                            },
                                            "waybill": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "order_reference": {
                                                "type": "string"
                                            },
                                            "direction": {
                                                "type": "string",
                                                "enum": [
                                                    "forward",
                                                    "reverse"
                                                ]
                                            },
                                            "canonical_status": {
                                                "$ref": "#/components/schemas/CanonicalStatus"
                                            },
                                            "current_status": {
                                                "type": "string"
                                            },
                                            "location": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "remarks": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "scanned_at": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "pickup_date": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "manifested_date": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "delivered_date": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "payment_mode": {
                                                "type": "string",
                                                "enum": [
                                                    "prepaid",
                                                    "cod",
                                                    "to_pay"
                                                ]
                                            },
                                            "is_test": {
                                                "type": "boolean"
                                            },
                                            "failure": {
                                                "$ref": "#/components/schemas/Failure"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "2XX": {
                        "description": "Any 2xx marks the delivery successful."
                    }
                }
            }
        }
    },
    "paths": {
        "/health": {
            "get": {
                "tags": [
                    "Meta"
                ],
                "operationId": "health",
                "summary": "Service health + version",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "const": "ok"
                                        },
                                        "version": {
                                            "type": "string"
                                        },
                                        "time": {
                                            "type": "string",
                                            "format": "date-time"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/openapi.yaml": {
            "get": {
                "tags": [
                    "Meta"
                ],
                "operationId": "openapiYaml",
                "summary": "This document (YAML)",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/yaml": []
                        }
                    }
                }
            }
        },
        "/openapi.json": {
            "get": {
                "tags": [
                    "Meta"
                ],
                "operationId": "openapiJson",
                "summary": "This document (JSON)",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": []
                        }
                    }
                }
            }
        },
        "/docs/reference": {
            "get": {
                "tags": [
                    "Meta"
                ],
                "operationId": "docsReference",
                "summary": "Self-contained interactive reference (HTML)",
                "description": "The same Scalar-rendered reference page as `ship-api-reference.html`, with this spec inlined. Embedded by the public /developers page via an <iframe>; also linkable directly and safe to open standalone.\n",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "text/html": []
                        }
                    }
                }
            }
        },
        "/docs/guide.pdf": {
            "get": {
                "tags": [
                    "Meta"
                ],
                "operationId": "docsGuidePdf",
                "summary": "Plain-English PDF developer guide",
                "description": "A narrative, step-by-step walkthrough (warehouse → rates → create → track → label, plus webhooks, payment modes and errors) for reading top-to-bottom or printing — as opposed to the interactive reference.\n",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/pdf": []
                        }
                    }
                }
            }
        },
        "/auth/login": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "operationId": "authLogin",
                "summary": "Exchange account credentials for a scoped Ship API token",
                "security": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email_or_username",
                                    "password"
                                ],
                                "properties": {
                                    "email_or_username": {
                                        "type": "string"
                                    },
                                    "password": {
                                        "type": "string"
                                    },
                                    "label": {
                                        "type": "string",
                                        "maxLength": 40
                                    },
                                    "test": {
                                        "type": "boolean",
                                        "description": "Also grant `ship:test`."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Token issued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "token": {
                                                            "type": "string"
                                                        },
                                                        "token_type": {
                                                            "type": "string",
                                                            "const": "Bearer"
                                                        },
                                                        "abilities": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "label": {
                                                            "type": "string"
                                                        },
                                                        "environment": {
                                                            "type": "string",
                                                            "enum": [
                                                                "live",
                                                                "test"
                                                            ]
                                                        },
                                                        "token_id": []
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    },
                    "403": {
                        "$ref": "#/components/responses/Error"
                    },
                    "429": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/auth/rotate": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "operationId": "authRotate",
                "summary": "Mint a fresh token; schedule the calling token for revocation",
                "description": "The calling token stays valid for `rotation_grace_hours` (72).",
                "responses": {
                    "200": {
                        "description": "Rotated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/auth/revoke": {
            "post": {
                "tags": [
                    "Auth"
                ],
                "operationId": "authRevoke",
                "summary": "Revoke the calling token immediately",
                "responses": {
                    "200": {
                        "description": "Revoked",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/auth/tokens": {
            "get": {
                "tags": [
                    "Auth"
                ],
                "operationId": "authTokens",
                "summary": "List the account's active ship-api tokens (never the secret)",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/warehouses": {
            "get": {
                "tags": [
                    "Warehouses"
                ],
                "operationId": "listWarehouses",
                "summary": "List pickup warehouses",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "warehouses": {
                                                            "type": "array",
                                                            "items": {
                                                                "$ref": "#/components/schemas/Warehouse"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            },
            "post": {
                "tags": [
                    "Warehouses"
                ],
                "operationId": "createWarehouse",
                "summary": "Create a pickup warehouse",
                "description": "Requires KYC + accepted merchant agreement.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name",
                                    "contact_person",
                                    "address",
                                    "city",
                                    "state",
                                    "pincode",
                                    "phone"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "contact_person": {
                                        "type": "string"
                                    },
                                    "address": {
                                        "type": "string"
                                    },
                                    "address_line_2": {
                                        "type": "string"
                                    },
                                    "city": {
                                        "type": "string"
                                    },
                                    "state": {
                                        "type": "string"
                                    },
                                    "pincode": {
                                        "type": "string",
                                        "pattern": "^\\d{6}$"
                                    },
                                    "phone": {
                                        "type": "string"
                                    },
                                    "alternate_phone": {
                                        "type": "string"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "gstin": {
                                        "type": "string"
                                    },
                                    "is_default": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#/components/schemas/Warehouse"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/warehouses/{warehouse}": {
            "patch": {
                "tags": [
                    "Warehouses"
                ],
                "operationId": "updateWarehouse",
                "summary": "Update a pickup warehouse",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Warehouse"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "contact_person": {
                                        "type": "string"
                                    },
                                    "address": {
                                        "type": "string"
                                    },
                                    "address_line_2": {
                                        "type": "string"
                                    },
                                    "city": {
                                        "type": "string"
                                    },
                                    "state": {
                                        "type": "string"
                                    },
                                    "pincode": {
                                        "type": "string",
                                        "pattern": "^\\d{6}$"
                                    },
                                    "phone": {
                                        "type": "string"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "is_default": {
                                        "type": "boolean"
                                    },
                                    "is_active": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#/components/schemas/Warehouse"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Warehouses"
                ],
                "operationId": "deleteWarehouse",
                "summary": "Delete a non-default pickup warehouse",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Warehouse"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/config": {
            "get": {
                "tags": [
                    "Config"
                ],
                "operationId": "getConfig",
                "summary": "Read the account's Ship API configuration",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "default_warehouse_id": {
                                                            "type": "string",
                                                            "format": "uuid",
                                                            "nullable": true
                                                        },
                                                        "courier_priority": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "webhook_url": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "webhook_active": {
                                                            "type": "boolean"
                                                        },
                                                        "webhook_secret_set": {
                                                            "type": "boolean"
                                                        },
                                                        "environment": {
                                                            "type": "string"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            },
            "put": {
                "tags": [
                    "Config"
                ],
                "operationId": "updateConfig",
                "summary": "Update the account's Ship API configuration",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "default_warehouse_id": {
                                        "type": "string",
                                        "format": "uuid",
                                        "nullable": true
                                    },
                                    "courier_priority": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "webhook_url": {
                                        "type": "string",
                                        "nullable": true,
                                        "description": "Must be an https URL that resolves to a public address."
                                    },
                                    "webhook_secret": {
                                        "type": "string",
                                        "minLength": 16
                                    },
                                    "webhook_active": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`invalid_warehouse` | `invalid_webhook_url` | `validation_error`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/rates": {
            "post": {
                "tags": [
                    "Rates"
                ],
                "operationId": "getRates",
                "summary": "Priced courier options for a route + parcel + direction",
                "description": "RateMaster only — courier `getRates()` is never called. `reverse` returns\nonly reverse-capable couriers (Delhivery, Ekart). Throttle `120/min` per token.\n",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "origin_pincode",
                                    "destination_pincode",
                                    "payment_mode",
                                    "parcel"
                                ],
                                "properties": {
                                    "direction": {
                                        "type": "string",
                                        "enum": [
                                            "forward",
                                            "reverse"
                                        ],
                                        "default": "forward"
                                    },
                                    "origin_pincode": {
                                        "type": "string",
                                        "pattern": "^\\d{6}$"
                                    },
                                    "destination_pincode": {
                                        "type": "string",
                                        "pattern": "^\\d{6}$"
                                    },
                                    "payment_mode": {
                                        "type": "string",
                                        "enum": [
                                            "prepaid",
                                            "cod",
                                            "to_pay"
                                        ]
                                    },
                                    "cod_amount": {
                                        "type": "number"
                                    },
                                    "declared_value": {
                                        "type": "number"
                                    },
                                    "insurance": {
                                        "type": "boolean"
                                    },
                                    "self_drop": {
                                        "type": "boolean"
                                    },
                                    "parcel": {
                                        "$ref": "#/components/schemas/Parcel"
                                    },
                                    "items": {
                                        "type": "array",
                                        "maxItems": 100,
                                        "items": {
                                            "$ref": "#/components/schemas/Item"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "quote_id": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        },
                                                        "currency": {
                                                            "type": "string",
                                                            "const": "INR"
                                                        },
                                                        "options": {
                                                            "type": "array",
                                                            "items": {
                                                                "$ref": "#/components/schemas/RateOption"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`no_courier` | `no_reverse_courier` | `unsupported_unit` | `payment_mode_not_allowed_for_reverse` | `cod_amount_not_allowed_for_to_pay` | `cod_amount_required` | `validation_error`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/shipments": {
            "post": {
                "tags": [
                    "Shipments"
                ],
                "operationId": "createShipment",
                "summary": "Create + book a shipment in one call (async, 202)",
                "description": "`Idempotency-Key` header required. Returns immediately with\n`tracking_number` + `shipment_id`; the waybill arrives via track-poll +\nwebhook. Wallet balance is held at create (skipped for `is_test`).\nThrottle `60/min` per token.\n",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "order_reference",
                                    "payment_mode",
                                    "parcel",
                                    "consignee"
                                ],
                                "properties": {
                                    "direction": {
                                        "type": "string",
                                        "enum": [
                                            "forward",
                                            "reverse"
                                        ],
                                        "default": "forward"
                                    },
                                    "warehouse_id": {
                                        "type": "string",
                                        "format": "uuid",
                                        "description": "Defaults to config.default_warehouse_id."
                                    },
                                    "rate_id": {
                                        "type": "string"
                                    },
                                    "courier_code": {
                                        "type": "string"
                                    },
                                    "service": {
                                        "type": "string"
                                    },
                                    "order_reference": {
                                        "type": "string"
                                    },
                                    "payment_mode": {
                                        "type": "string",
                                        "enum": [
                                            "prepaid",
                                            "cod",
                                            "to_pay"
                                        ]
                                    },
                                    "cod_amount": {
                                        "type": "number",
                                        "description": "Required for cod; must be 0/absent for to_pay & reverse."
                                    },
                                    "return_reason": {
                                        "type": "string",
                                        "description": "Required when direction=reverse."
                                    },
                                    "invoice_number": {
                                        "type": "string"
                                    },
                                    "invoice_date": {
                                        "type": "string",
                                        "format": "date"
                                    },
                                    "invoice_amount": {
                                        "type": "number",
                                        "description": "> 50000 with a blank eway_bill → 422 eway_bill_required."
                                    },
                                    "eway_bill": {
                                        "type": "string"
                                    },
                                    "gstin": {
                                        "type": "string"
                                    },
                                    "hsn": {
                                        "type": "string"
                                    },
                                    "insurance": {
                                        "type": "boolean"
                                    },
                                    "insurance_declared_value": {
                                        "type": "number"
                                    },
                                    "self_drop": {
                                        "type": "boolean",
                                        "description": "Forward only; silently dropped on reverse with a warnings[] note."
                                    },
                                    "auto_pickup": {
                                        "type": "boolean",
                                        "default": true
                                    },
                                    "parcel": {
                                        "$ref": "#/components/schemas/Parcel"
                                    },
                                    "items": {
                                        "type": "array",
                                        "maxItems": 100,
                                        "items": {
                                            "$ref": "#/components/schemas/Item"
                                        }
                                    },
                                    "consignee": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/Consignee"
                                            }
                                        ],
                                        "description": "forward: the delivery recipient. reverse: the consumer the parcel is COLLECTED FROM."
                                    },
                                    "billing_return_address": {
                                        "type": "object",
                                        "description": "Overrides the warehouse as the return-to address."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Accepted — booking in progress",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "shipment_id": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "tracking_number": {
                                                            "type": "string"
                                                        },
                                                        "order_reference": {
                                                            "type": "string"
                                                        },
                                                        "direction": {
                                                            "type": "string",
                                                            "enum": [
                                                                "forward",
                                                                "reverse"
                                                            ]
                                                        },
                                                        "payment_mode": {
                                                            "type": "string",
                                                            "enum": [
                                                                "prepaid",
                                                                "cod",
                                                                "to_pay"
                                                            ]
                                                        },
                                                        "canonical_status": {
                                                            "type": "string",
                                                            "const": "PROCESSING"
                                                        },
                                                        "environment": {
                                                            "type": "string",
                                                            "enum": [
                                                                "live",
                                                                "test"
                                                            ]
                                                        },
                                                        "warnings": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "`insufficient_balance` — `data.required_paise` / `data.available_paise`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "`idempotency_in_progress` | `idempotency_key_conflict` | `rate_unavailable` (fresh `data.options[]`) | `duplicate_order_reference` (a live shipment already holds this `order_reference` + `direction` — `data.shipment_id`, `data.tracking_number`, `data.canonical_status`)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`idempotency_key_required` | `no_warehouse` | `invalid_warehouse` | `b2b_not_supported` | `too_many_items` | `return_reason_required` | `eway_bill_required` | `insurance_value_required` | `unsupported_unit` | payment-matrix codes | `validation_error`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "`rate_limited` | `too_many_in_flight` (+ `Retry-After`)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            },
            "get": {
                "tags": [
                    "Shipments"
                ],
                "operationId": "listShipments",
                "summary": "Paginated shipment list",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 100
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "$ref": "#/components/schemas/CanonicalStatus"
                        }
                    },
                    {
                        "name": "direction",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "forward",
                                "reverse"
                            ]
                        }
                    },
                    {
                        "name": "payment_mode",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "prepaid",
                                "cod",
                                "to_pay"
                            ]
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "order_reference",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "courier_code",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "items": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object"
                                                            }
                                                        },
                                                        "meta": {
                                                            "$ref": "#/components/schemas/PageMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/shipments/{shipment}": {
            "get": {
                "tags": [
                    "Shipments"
                ],
                "operationId": "getShipment",
                "summary": "Shipment details (explicit allowlist — no cost/margin/rate-card data)",
                "description": "Includes `failure` (when FAILED) and `ndr` (latest attempt, when NDR) — same shapes as on track.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Shipment"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/shipments/{shipment}/cancel": {
            "post": {
                "tags": [
                    "Shipments"
                ],
                "operationId": "cancelShipment",
                "summary": "Cancel a shipment",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Shipment"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Cancelled",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "description": "`not_cancellable` — `data.status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/shipments/{shipment}/pickup": {
            "post": {
                "tags": [
                    "Shipments"
                ],
                "operationId": "schedulePickup",
                "summary": "Schedule a courier pickup",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Shipment"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "pickup_date"
                                ],
                                "properties": {
                                    "pickup_date": {
                                        "type": "string",
                                        "format": "date",
                                        "description": ">= today"
                                    },
                                    "pickup_time_slot": {
                                        "type": "string"
                                    },
                                    "expected_package_count": {
                                        "type": "integer",
                                        "minimum": 1
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "pickup_status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "scheduled",
                                                                "auto",
                                                                "failed"
                                                            ]
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "description": "`not_ready_for_pickup` (+ `data.status`) | `pickup_already_scheduled` | `pickup_rejected` | `validation_error`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/shipments/{shipment}/label": {
            "post": {
                "tags": [
                    "Labels"
                ],
                "operationId": "getLabel",
                "summary": "Shipping label (base64 PDF or a signed URL)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Shipment"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "size": {
                                        "type": "string",
                                        "enum": [
                                            "a4",
                                            "4x6",
                                            "4x2.5",
                                            "3x2",
                                            "2x3"
                                        ],
                                        "default": "a4"
                                    },
                                    "format": {
                                        "type": "string",
                                        "enum": [
                                            "base64",
                                            "url"
                                        ],
                                        "default": "base64"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "size": {
                                                            "type": "string"
                                                        },
                                                        "format": {
                                                            "type": "string",
                                                            "enum": [
                                                                "base64",
                                                                "url"
                                                            ]
                                                        },
                                                        "content": {
                                                            "type": "string",
                                                            "description": "base64 PDF, or a signed short-TTL URL."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "description": "`not_booked`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/shipments/track/{tracking_number}": {
            "get": {
                "tags": [
                    "Tracking"
                ],
                "operationId": "trackShipment",
                "summary": "Track one shipment by tracking number or courier AWB",
                "description": "Throttle `300/min` per token.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/TrackingNumber"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#/components/schemas/Tracking"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/shipments/track": {
            "post": {
                "tags": [
                    "Tracking"
                ],
                "operationId": "trackShipments",
                "summary": "Bulk track — up to 50 numbers (tracking number or AWB, mixed)",
                "description": "Shares the `300/min` track limiter. Numbers that are unknown or belong to another account land in `not_found` — never an error.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "numbers"
                                ],
                                "properties": {
                                    "numbers": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 50,
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "items": {
                                                            "type": "array",
                                                            "items": {
                                                                "allOf": [
                                                                    {
                                                                        "type": "object",
                                                                        "properties": {
                                                                            "query": {
                                                                                "type": "string",
                                                                                "description": "The number you sent."
                                                                            }
                                                                        }
                                                                    },
                                                                    {
                                                                        "$ref": "#/components/schemas/Tracking"
                                                                    }
                                                                ]
                                                            }
                                                        },
                                                        "not_found": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/labels": {
            "post": {
                "tags": [
                    "Labels"
                ],
                "operationId": "getLabels",
                "summary": "Bulk labels — one merged PDF for up to 100 shipments",
                "description": "Pages follow the order of `shipment_ids`. Unknown / other-account ids\n(`not_found`) and unbooked shipments (`not_booked`) are listed in\n`skipped`; the call fails only when nothing is printable.\n",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "shipment_ids"
                                ],
                                "properties": {
                                    "shipment_ids": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 100,
                                        "items": {
                                            "type": "string",
                                            "format": "uuid"
                                        }
                                    },
                                    "size": {
                                        "type": "string",
                                        "enum": [
                                            "a4",
                                            "4x6",
                                            "4x2.5",
                                            "3x2",
                                            "2x3"
                                        ],
                                        "default": "a4"
                                    },
                                    "format": {
                                        "type": "string",
                                        "enum": [
                                            "base64",
                                            "url"
                                        ],
                                        "default": "base64"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "size": {
                                                            "type": "string"
                                                        },
                                                        "format": {
                                                            "type": "string",
                                                            "enum": [
                                                                "base64",
                                                                "url"
                                                            ]
                                                        },
                                                        "generated": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "format": "uuid"
                                                            }
                                                        },
                                                        "skipped": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "shipment_id": {
                                                                        "type": "string",
                                                                        "format": "uuid"
                                                                    },
                                                                    "code": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "not_found",
                                                                            "not_booked"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "string",
                                                            "description": "base64 PDF, or a signed 15-minute `GET /documents/{file}` URL."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`not_booked` (nothing printable — `data.skipped`) | `validation_error`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/manifests": {
            "post": {
                "tags": [
                    "Documents"
                ],
                "operationId": "createManifest",
                "summary": "Pickup manifest — the courier hand-over sheet",
                "description": "One A4 manifest per (warehouse × courier) for shipments that are booked\nand not yet picked up (`MANIFESTED` / `PICKUP_SCHEDULED`): AWB barcodes,\nconsignee, payment mode, COD to collect, weight, pieces, and signature\nboxes for the seller and the courier executive. Stateless and\nreprintable — the same shipments always give the same\n`manifest_number`. Others are reported in `skipped`\n(`not_found` | `not_booked` | `not_manifestable`).\n",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "shipment_ids"
                                ],
                                "properties": {
                                    "shipment_ids": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 100,
                                        "items": {
                                            "type": "string",
                                            "format": "uuid"
                                        }
                                    },
                                    "format": {
                                        "type": "string",
                                        "enum": [
                                            "base64",
                                            "url"
                                        ],
                                        "default": "base64"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "format": {
                                                            "type": "string",
                                                            "enum": [
                                                                "base64",
                                                                "url"
                                                            ]
                                                        },
                                                        "manifests": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "manifest_number": {
                                                                        "type": "string",
                                                                        "example": "MF-20261029-5FEB32"
                                                                    },
                                                                    "courier_code": {
                                                                        "type": "string"
                                                                    },
                                                                    "warehouse_id": {
                                                                        "type": "string",
                                                                        "format": "uuid"
                                                                    },
                                                                    "shipment_ids": {
                                                                        "type": "array",
                                                                        "items": {
                                                                            "type": "string",
                                                                            "format": "uuid"
                                                                        }
                                                                    },
                                                                    "count": {
                                                                        "type": "integer"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "skipped": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "shipment_id": {
                                                                        "type": "string",
                                                                        "format": "uuid"
                                                                    },
                                                                    "code": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "not_found",
                                                                            "not_booked",
                                                                            "not_manifestable"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "string",
                                                            "description": "base64 PDF, or a signed 15-minute URL."
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`not_manifestable` (nothing eligible — `data.skipped`) | `validation_error`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/invoices": {
            "post": {
                "tags": [
                    "Documents"
                ],
                "operationId": "createInvoices",
                "summary": "Seller invoices — one A4 page per shipment, merged",
                "description": "Rendered from the shipment's `items[]` and the seller's own data\n(`gstin` on create, else the account GSTIN): `TAX INVOICE` when a GSTIN\nis known, otherwise `INVOICE`. CGST + SGST or IGST follows the same rule\nas the label (seller GSTIN state vs delivery pincode state). Available\nbefore booking; the AWB and its barcode are printed once assigned.\nNumber = `invoice_number` from create, else `order_reference`.\n",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "shipment_ids"
                                ],
                                "properties": {
                                    "shipment_ids": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 100,
                                        "items": {
                                            "type": "string",
                                            "format": "uuid"
                                        }
                                    },
                                    "format": {
                                        "type": "string",
                                        "enum": [
                                            "base64",
                                            "url"
                                        ],
                                        "default": "base64"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "format": {
                                                            "type": "string",
                                                            "enum": [
                                                                "base64",
                                                                "url"
                                                            ]
                                                        },
                                                        "generated": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "format": "uuid"
                                                            }
                                                        },
                                                        "skipped": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "shipment_id": {
                                                                        "type": "string",
                                                                        "format": "uuid"
                                                                    },
                                                                    "code": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "not_found"
                                                                        ]
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "content": {
                                                            "type": "string"
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/documents/{file}": {
            "get": {
                "tags": [
                    "Documents"
                ],
                "operationId": "documentView",
                "summary": "Signed short-TTL PDF (bulk labels, manifests, invoices)",
                "description": "URL-signed (no bearer token). Issued by `POST /labels`, `POST /manifests` or `POST /invoices` with `format=url`.",
                "security": [],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/BatchFile"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF",
                        "content": {
                            "application/pdf": []
                        }
                    },
                    "403": {
                        "description": "Signature invalid or expired"
                    },
                    "404": {
                        "description": "Not found"
                    }
                }
            }
        },
        "/shipments/{shipment}/ndr": {
            "get": {
                "tags": [
                    "NDR"
                ],
                "operationId": "listNdrAttempts",
                "summary": "Every NDR attempt for a shipment, latest first",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Shipment"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "shipment_id": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "tracking_number": {
                                                            "type": "string"
                                                        },
                                                        "attempts": {
                                                            "type": "array",
                                                            "items": {
                                                                "$ref": "#/components/schemas/Ndr"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/shipments/{shipment}/ndr/action": {
            "post": {
                "tags": [
                    "NDR"
                ],
                "operationId": "actOnNdr",
                "summary": "Act on the latest open NDR (re-attempt, new address/phone, or RTO)",
                "description": "Keyed by shipment — you never need an NDR id. `re_attempt`,\n`change_address` and `change_phone` are forwarded to the courier and\nthe shipment stays `NDR` until the courier reports the next scan.\n`rto` closes the NDR and moves the shipment to `RTO_INITIATED`\n(RTO freight applies). Throttle `30/min` per token.\n",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Shipment"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "action"
                                ],
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "re_attempt",
                                            "change_address",
                                            "change_phone",
                                            "rto"
                                        ]
                                    },
                                    "re_attempt_date": {
                                        "type": "string",
                                        "format": "date",
                                        "description": "> today. Optional for re_attempt."
                                    },
                                    "new_address": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "description": "Required for change_address."
                                    },
                                    "new_phone": {
                                        "type": "string",
                                        "pattern": "^[6-9]\\d{9}$",
                                        "description": "Required for change_phone."
                                    },
                                    "instructions": {
                                        "type": "string",
                                        "maxLength": 500
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Submitted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "shipment_id": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "tracking_number": {
                                                            "type": "string"
                                                        },
                                                        "ndr": {
                                                            "$ref": "#/components/schemas/Ndr"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "409": {
                        "description": "`no_open_ndr` — `data.status`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "`validation_error` | `ndr_action_failed`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/test/shipments/{shipment}/scan": {
            "post": {
                "tags": [
                    "Sandbox"
                ],
                "operationId": "sandboxScan",
                "summary": "Simulate a courier scan on a test-mode shipment",
                "description": "`ship:test` tokens and `is_test` shipments only. Moves the shipment\nexactly as a real courier scan would — same state machine, same NDR\ncreation, same `shipment.status` webhooks — so every status can be\nexercised before go-live. Intermediate statuses are walked for you\n(MANIFESTED → DELIVERED fires each step's webhook).\n",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Shipment"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "status"
                                ],
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "PICKUP_SCHEDULED",
                                            "PICKED_UP",
                                            "IN_TRANSIT",
                                            "OUT_FOR_DELIVERY",
                                            "DELIVERED",
                                            "NDR",
                                            "RTO_INITIATED",
                                            "RTO_DELIVERED",
                                            "LOST",
                                            "DAMAGED"
                                        ]
                                    },
                                    "location": {
                                        "type": "string",
                                        "maxLength": 120
                                    },
                                    "remarks": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "On NDR this becomes the non-delivery reason."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The tracking payload after the scan.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#/components/schemas/Tracking"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/Error"
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "description": "`not_a_test_shipment` | `invalid_transition` (`data.status`) | `validation_error`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/shipments/label/{token}": {
            "get": {
                "tags": [
                    "Labels"
                ],
                "operationId": "labelView",
                "summary": "Signed short-TTL label PDF view",
                "description": "URL-signed (no bearer token). Issued by `POST /shipments/{shipment}/label` with `format=url`.",
                "security": [],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/LabelToken"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF",
                        "content": {
                            "application/pdf": []
                        }
                    },
                    "403": {
                        "description": "Signature invalid or expired"
                    },
                    "404": {
                        "description": "Not found"
                    }
                }
            }
        },
        "/webhooks/deliveries": {
            "get": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "listWebhookDeliveries",
                "summary": "Webhook delivery log",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/Envelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "properties": {
                                                        "items": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "object",
                                                                "properties": {
                                                                    "id": {
                                                                        "type": "string",
                                                                        "format": "uuid"
                                                                    },
                                                                    "event": {
                                                                        "type": "string"
                                                                    },
                                                                    "canonical_status": {
                                                                        "$ref": "#/components/schemas/CanonicalStatus"
                                                                    },
                                                                    "attempt": {
                                                                        "type": "integer"
                                                                    },
                                                                    "response_status": {
                                                                        "type": "integer",
                                                                        "nullable": true
                                                                    },
                                                                    "status": {
                                                                        "type": "string",
                                                                        "enum": [
                                                                            "pending",
                                                                            "delivered",
                                                                            "failed",
                                                                            "exhausted"
                                                                        ]
                                                                    },
                                                                    "created_at": {
                                                                        "type": "string",
                                                                        "format": "date-time"
                                                                    }
                                                                }
                                                            }
                                                        },
                                                        "meta": {
                                                            "$ref": "#/components/schemas/PageMeta"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Error"
                    }
                }
            }
        },
        "/webhooks/deliveries/{delivery}/retry": {
            "post": {
                "tags": [
                    "Webhooks"
                ],
                "operationId": "retryWebhookDelivery",
                "summary": "Re-queue an exhausted / failed delivery",
                "description": "Resets `attempt` to 0 (fresh backoff ladder).",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Delivery"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Re-queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Envelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/Error"
                    },
                    "422": {
                        "description": "Only `exhausted` / `failed` deliveries can be retried.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}