# Shiprocket — Panel vs API: Feature & Data Availability Map

**Purpose.** A reference map of *what the Shiprocket seller panel exposes* vs *what is reachable through the external REST API* — so the DispatchWithAutomation PWA knows what to build via **API** and what still needs **panel automation (Playwright)**.

**Method.** Read-only Playwright sweep of the live seller panel (YEMO account, session `auth_state.json`) — **37 screens captured** on 2026-07-31 (headings, table columns, tabs, filters, actions). Cross-mapped against the Shiprocket external API (`https://apiv2.shiprocket.in/v1/external/…`), several endpoints verified firsthand during the TIMEX work.

**Legend.** ✅ Full API · 🟡 Partial / reconstructable · ⛔ Panel-only (no external API).

---

## 1. How Shiprocket works as a system (the pipeline)

Shiprocket is a **courier aggregator**: you never contract couriers directly — Shiprocket resells ~15–20 carriers on *your plan's* negotiated rates, and sits between you and them for booking, tracking, COD, and billing.

The core object flow:

```
ORDER  ──assign──▶  SHIPMENT + AWB  ──pickup──▶  IN-TRANSIT  ──▶  DELIVERED / NDR / RTO
 (create)          (courier chosen)   (scheduled)   (tracking)      (COD remittance ▶ billing)
```

- **Order** — buyer + product + package + payment(prepaid/COD) + pickup address. Created via API or panel or a connected **channel** (Shopify/Amazon/etc.).
- **Serviceability** decides which couriers can serve the lane and at what **rate** (per your plan's zone matrix: Zone A within-city → Zone E special-destination).
- **AWB assignment** picks a courier and generates the tracking number → a **Shipment**.
- **Pickup** is scheduled; courier collects.
- **Tracking** flows back as statuses; failures become **NDR** (non-delivery), which can end in re-attempt or **RTO** (return to origin).
- **COD** collected by courier is **remitted** to you on a cycle (CRF/UTR), minus **deductions** (freight, weight discrepancies).
- **Billing**: freight is charged from your **wallet**; **weight discrepancies** (courier-measured > declared) create post-facto charges you can dispute; monthly **invoices** summarize it.

Money/quality levers layered on top: **VAS** (insurance/Auto-Secure, WhatsApp Notify, Delivery Boost, Brand Boost), **Radar** (courier health / auto-block), **Business Success Score**, **Shiprocket Capital** (loans/credit — a separate product).

---

## 2. The map (by panel area)

### A. Dashboards & Scores
| Panel screen | What it shows / does | API | Endpoint / how | Notes |
|---|---|---|---|---|
| Homepage | Summary (orders, revenue), Actions-needing-attention, Upcoming pickups, quick rate calc | 🟡 | derive from `orders` list + `courier/track` | It's an aggregation UI; rebuild from order/shipment data |
| Domestic Dashboard | Shipment Overview, Pickup/Delivery Performance, SLA Adherence, NDR report, Weight Discrepancies, COD Remittance | ⛔ | — | Analytics roll-ups; **no external analytics API** — rebuild from raw order/shipment data yourself |
| Radar Dashboard | Courier-health "control tower", **auto-block stressed couriers**, map view | ⛔ | — | Panel-only feature; the per-courier **performance metrics DO come through** `courier/serviceability` (`SLA_Adherence`, `pickup/delivery_performance`, `RTO w/o_Attempt`, `rating`) so you can replicate the *scoring*, not the auto-block toggle |
| Business Success Score (6/7) | Gamified account-health score | ⛔ | — | Panel-only |

### B. Orders & Returns
| Panel screen | What it shows / does | API | Endpoint | Notes |
|---|---|---|---|---|
| New Orders (New / On Hold) | Order list: Order/Customer/Product/Package/Payment/Pickup/Status | ✅ | `GET orders`, `GET orders/show/{id}` | Full order CRUD via API |
| Add Order (manual) | Create a single order (buyer, address, product, COD/prepaid) | ✅ | `POST orders/create/adhoc` | This is the TIMEX booking path |
| Bulk order import | Upload many orders | 🟡 | loop `orders/create/adhoc` | Panel has an uploader; API = loop |
| New Returns | Return list: Return/Buyer/Product/Dimensions/Warehouse/Refund | ✅ | `POST orders/create/return`, `GET orders/processing/return` | Create **and** list returns via API; the panel adds QC/refund-status workflow |

### C. Shipping / Couriers / AWB
| Panel screen | What it shows / does | API | Endpoint | Notes |
|---|---|---|---|---|
| Rate Calculator | Per-lane rate quote (pickup/delivery/weight/dims/COD) | ✅ | `GET courier/serviceability/` | **Exactly the API** — returns per-courier rate/EDD/zone |
| **Rate Card** (zone matrix) | All couriers × Zone A–E × weight, **Forward\|RTO**, **COD\|COD%**, Other Charges | 🟡 | reconstruct via `serviceability` per zone-representative pincode × weight | Every column maps to an API field (`rate`, `rto_charges`, `cod_charges`, `cod_multiplier`, `other_charges`, `zone`); API even reflects *your* pickup's real zoning |
| Courier assign / AWB | Pick courier, generate AWB → shipment | ✅ | `POST courier/assign/awb` | |
| Schedule Pickup | Generate pickup request | ✅ | `POST courier/generate/pickup` | |
| Courier Selection | Enable/disable couriers, set priority per region | ⛔ | — | Config is **panel-only**; API just *reads* the serviceable set |
| Pincode Zone Mapping | Pickup→zone serviceability, **Export** | 🟡 | per-pincode via `serviceability` (`zone` field) | Bulk export is panel-only; per-pincode is API |
| Package Master | Saved package dimensions catalog | ⛔ | — | Panel-only master; you pass dims inline on `orders/create` |

### D. Post-ship: Tracking, NDR, Weight
| Panel screen | What it shows / does | API | Endpoint | Notes |
|---|---|---|---|---|
| All Shipments | Every shipment + status + invoice + insights | ✅ | `GET courier/track/awb/{awb}`, `…/track/shipment/{id}` | Tracking fully via API (+ webhooks) |
| NDR Management | Failed-delivery queue, attempt details, take action | 🟡 | `GET ndr/all`, `GET ndr/{awb}`, `POST ndr/{awb}/action` (reattempt/RTO) | List + reattempt/RTO via API; the panel's escalation/buyer-feedback flow is richer — **known-broken NDR ticket path** documented separately |
| Weight Discrepancy | Applied vs Courier vs Charged weight, Excess charge, **dispute** | ⛔ | — | **Panel-only** — no API to list/accept/dispute weight discrepancies (confirmed) |
| Weight Freeze | Shiprocket-suggested product weights, accept | ⛔ | — | Panel-only |

### E. Money: COD, Freight, Wallet, Bills
| Panel screen | What it shows / does | API | Endpoint | Notes |
|---|---|---|---|---|
| Freight & VAS Charges | Per-order **billed** freight, on-hold amount, billing status | ⛔ | — | Serviceability gives *quotes*; the **actually-billed** freight is panel-only (we scrape it — `playwright_freight_charges.py`) |
| COD Remittance | CRF, UTR, COD available, deductions, remitted amount, method, status | ⛔ | — | **Panel-only** — no external COD-remittance ledger endpoint |
| Wallet Transactions | Recharge history, balance | 🟡 | `GET account/details/wallet-balance` | **Balance IS in the API**; transaction/recharge *history* is panel-only |
| Bills / Invoices | Monthly invoices (id/service/date/amount/status) | ⛔ | — | Panel-only |

### F. Value-Added Services (all config = panel-only)
| Panel screen | What it does | API | Notes |
|---|---|---|---|
| Auto-Secure Shipments | Shipment insurance | ⛔ | Panel-only toggle |
| Early COD Remittance | Faster COD payout plan | ⛔ | Panel-only |
| Notify (WhatsApp) | Buyer WhatsApp comms per status | ⛔ | Panel-only |
| Delivery Boost | Paid delivery-success uplift | ⛔ | Panel-only |
| Brand Boost | Branded tracking page / widget | ⛔ | Panel-only |

### G. Setup / Ops / Misc
| Panel screen | What it does | API | Endpoint | Notes |
|---|---|---|---|---|
| Channels | Connect Shopify/Amazon/etc. stores | 🟡 | `GET channels` | Read via API; connect flow is panel |
| Pickup Addresses | Manage warehouse pickup locations | ✅ | `GET/POST settings/company/pickup` | |
| Products / Inventory | Product catalog | ✅ | `GET/POST products` | |
| Reports & Analytics | Downloadable reports (module/type/range) | ⛔ | — | Panel-only exports; rebuild from raw data |
| Bulk Actions | Bulk print Label/Invoice/Manifest/POD, bulk cancel | 🟡 | `label`, `manifests/generate`, `orders/print/invoice`, `orders/cancel` | Per-item endpoints exist; the *bulk* UI is convenience |
| Activity Logs | Bulk-import run logs | ⛔ | — | Panel-only |
| ZOP Dashboard | Zero-Order-Platform / social-commerce storefront | ⛔ | — | Separate product |
| Shiprocket Capital | Business loan / free credit score | ⛔ | — | Separate fintech product |
| Account Settings | Company/KYC/users/labels config | 🟡 | some `settings/*` | Mostly panel |

---

## 3. The bottom line — what's panel-only (must be Playwright-automated)

Everything the API **cannot** give you, and therefore still needs the saved-session Playwright approach:

1. **Billed freight & weight discrepancies** — the *actual* charge (vs the quote), excess-weight disputes, Weight Freeze. (You already scrape freight: `playwright_freight_charges.py`.)
2. **COD remittance ledger** — CRF/UTR/deductions/remitted (financial reconciliation).
3. **Wallet transaction history & invoices** — no external endpoint (the *balance alone* IS available via `account/details/wallet-balance`).
4. **Analytics / dashboards** — Domestic Dashboard, Radar, Business Success Score, Reports downloads. *(But per-courier performance metrics ARE in `serviceability` — you can rebuild the scorecard.)*
5. **Config toggles** — Courier Selection priority, all VAS (Auto-Secure, Notify, Delivery Boost, Brand Boost), Package Master, Pincode-zone export.
6. **NDR rich workflow** — beyond basic list/action.

Everything else — **orders, serviceability/rates (incl. the full rate card by reconstruction), AWB assignment, pickup, tracking, returns, pickup addresses, products** — is **fully API-driven**.

---

## 3.5. Known portal bugs, quirks & constraints (as of 2026-07-31)

**Confirmed Shiprocket-side BUGS (not ours):**
1. **NDR ticket creation is broken** for undelivered shipments. For an UNDELIVERED AWB, Support → "Delay in Forward Delivery" is refused (routes to NDR); the "correct" path **Shipment NDR & RTO → "Issue Over Undelivered Shipment"** fills fine but **Create Ticket fails with `NDR sub-flow failed for all rows`** — reproduced **3× (Playwright AND CiC, user-driven)**, so it's their bug, not our data. **Workaround: escalate by email** — the courier's care address (e.g. customercare@xpressbees.com) + escalation@shiprocket.in (flag the panel bug in the mail). *(Re-confirming requires a real ticket submit — do NOT re-trigger without owner go-ahead.)*
2. **Broken Capital nav links** — the "Business Loan" and "Free Credit Score" menu items carry an **unrendered Angular template literal** in the href (`{{environment.capital_panel_url}}home…`), so they silently fall back to the homepage instead of opening Shiprocket Capital. Cosmetic but real.
3. **Blank "Leads" page** and the **Rate Card** route mis-titled "Rate Calculator | Shiprocket" — minor UI defects seen in the sweep.

**Constraints/quirks that trip automation (NOT bugs — design):**
- **Orders lock after AWB** — `orders/update/*` (customer email/address etc.) is rejected once an AWB is assigned (`400 Order update not allowed`). Fix data *before* booking. (Hit on all 67 TIMEX orders with a placeholder email.)
- **Token expires ~10 days** — re-POST `auth/login`, no refresh token.
- **₹2 flat surcharge (excl. GST) since 13-Apr-2026, +5% for BlueDart/DTDC/Blitz** — already **baked into the API `rate`**, so API quotes ≈ billed freight (verified: BD 82 × 1.05 = 86.1).
- **Sub-500g bills at 0.5 kg minimum** (`min_weight`/`charge_weight` = 0.5) — no fractional-below-500g pricing.
- **Weight discrepancy, COD remittance ledger, invoices are panel-only** — reconcile finance via Playwright, not API.
- **"Queue-cleared ≠ delivered"** — a Shiprocket status can read Delivered while the courier portal still says In-Transit/OFD; always cross-confirm against the courier (learned on TIMEX).

**API health (probed 2026-07-31, read-only):** invalid pincode → clean `400 Invalid Delivery Pincode`; rates stable across calls; COD charges/multiplier populated; no anomalies. **No external-API bugs found** — the defects are all in the panel UI/workflows.

## 4. Implications for DispatchWithAutomation (360LM)

- **Build on the API:** order create → serviceability (rate + EDD + zone + carrier scorecard fields) → AWB assign → pickup → tracking. This is the entire auto-booking core and is 100% API.
- **Rate card:** don't scrape it — reconstruct the zone matrix from `serviceability` (one representative pincode per zone × weight); it's fresher and pickup-specific.
- **Keep the Playwright side ONLY for:** billed-freight reconciliation, weight-discrepancy disputes, COD-remittance ledger, wallet/invoices, and any VAS/config toggles — i.e., finance-reconcile + a few config actions.
- **Carrier scorecard:** `serviceability` already returns `SLA_Adherence`, `pickup/delivery/tracking_performance`, `RTO w/o_Attempt`, `rating`, `estimated_delivery_days` — enough to replicate Radar-style courier scoring inside the PWA without the panel.

---

## 5. API basics & endpoint quick-reference (verified)

- **Base:** `https://apiv2.shiprocket.in/v1/external/` · JSON · `Authorization: Bearer <token>` on every call.
- **Token:** `POST /auth/login {email,password}` → `token`, valid **~240 h (10 days)**, no refresh — just re-POST credentials.
- **Also confirmed to exist** (beyond the tables above): `POST orders/create/channel`, `POST orders/create/quick-create` (create+assign+label+manifest in one), `POST orders/cancel/shipment/awbs` (cancel by AWB), `POST courier/track/awbs` (bulk track), `GET courier/courierListWithCounts`, `GET shipments` / `GET shipments/{id}`, `GET warehouse/srf-serviceability`.
- **Webhooks** (tracking + return push) are registered **in the panel** (Settings → API → Webhooks: URL + secret) — not via API — even though the events themselves are the API's data.

**Verification.** Panel side = the 37-screen live sweep (this account). API side cross-checked against Shiprocket's official **helpsheet**, the official **MCP tool list** (github.com/bfrs/shiprocket-mcp), the **Postman collection** (postman.com/shiprocketdev), and two official-behavior Laravel SDKs (seshac, Aniket-IN). `apidocs.shiprocket.in` is a JS SPA (not fetchable); the **Postman collection is the machine-checkable source** — spot-check any `returns` / `wallet` / `courierListWithCounts` / `orders/update` slug there before coding.

*Generated 2026-07-31. Per-screen panel screenshots saved in `…/scratchpad/sr_sweep/`. Capture scripts: `sr_panel_sweep.py` (panel), `sr_vs_dakia.py` (rate pulls).*