`logistics.send_intercity_parcel` — Full Intent Specification

INTENT NAMESPACE: logistics
INTENT NAME:      send_intercity_parcel
FULL ID:          logistics.send_intercity_parcel
VERSION:          v1.0.0
STATUS:           live
TTBS WEIGHTS:     time 0.30 · taste 0.10 · budget 0.35 · safety 0.25
LAST UPDATED:     2026-05-14

City-to-city domestic parcel within India. Distinct from logistics.send_intracity_parcel because: (a) the carrier is a multi-leg network (pickup van → hub → linehaul truck → destination hub → last-mile rider), not a single rider; (b) ETA is in days, not minutes; (c) E-way bill applies above ₹50,000 declared value (GST regulation); (d) HAZMAT and prohibited items list is broader (lithium battery rules, ICAO/IATA-like surface restrictions); (e) tracking is at scan-event level (PICKED / IN_TRANSIT_HUB / OUT_FOR_DELIVERY / DELIVERED / RTO). Distinct from logistics.send_international_parcel (customs + HS code + IOR).

1. NATURAL LANGUAGE COVERAGE

Classifies IN

"send a parcel to Mumbai"
"courier from Hyderabad to Delhi"
"ship 5 kg carton to Bengaluru"
"send laptop to my brother in Pune"
"Delhivery 2 days Bangalore"
"express parcel Chennai overnight"
"send books to my college, Kolkata"
"DTDC pickup home, drop Jaipur"
"send saree to mom in Vizag"
"ship printer to office Mumbai, fragile"

Classifies OUT — borderline NO

"send across town" → logistics.send_intracity_parcel
"ship to USA" → logistics.send_international_parcel
"shift household, 12 cartons + furniture" → logistics.book_full_house_move
"send a bike Hyderabad to Pune" → logistics.book_bike_transport
"send cold-chain vaccine sample" → logistics.book_cold_chain_delivery

MULTI-INTENT TRIGGERS

"ship laptop Pune + book repair pickup" → logistics.send_intercity_parcel + auto-service-equivalent
"book flight + courier my forgotten ID" → travel.book_flight + logistics.send_intercity_parcel

2. INPUT — TOMO → PROVIDER

{
  "intent":          "logistics.send_intercity_parcel",
  "intent_version":  "v1.0.0",
  "request_id":      "req_ic_2q9w_2026-05-14T10:00:00Z",
  "user_session_id": "anon_user_token_or_uid",

  "pickup": {
    "address_id":   "addr_home_v1",
    "pin":          "500032",
    "city":         "Hyderabad",
    "contact_phone_e164": "+91XXXXXXXXXX",
    "ready_at_iso": "2026-05-14T15:00:00+05:30"
  },

  "drop": {
    "address_id":     "addr_mumbai_brother_v1",
    "pin":            "400076",
    "city":           "Mumbai",
    "contact_phone_e164": "+91XXXXXXXXXX",
    "recipient_name": "Rohit Gamasany"
  },

  "cargo": {
    "category":         "electronics",
    "sub_category":     "consumer_laptop_with_battery",
    "size_band":        "carton_medium",
    "dim_l_cm":         42,
    "dim_w_cm":         30,
    "dim_h_cm":         8,
    "weight_kg":        2.4,
    "declared_value_inr": 65000,
    "fragile":          true,
    "needs_signature":  true,
    "lithium_battery_present": true,
    "lithium_battery_wh":      55
  },

  "service_level": "express_2d",
  "service_levels_allowed": ["surface_5_7d", "express_2d", "overnight_1d"],

  "user_constants": {
    "preferred_partners": ["Delhivery", "DTDC", "BlueDart", "Shadowfax B2C"],
    "gstin_optional": null
  }
}

Field rules

declared_value_inr ≥ ₹50,000 → triggers E-way bill auto-creation (GST regulation).
lithium_battery_present + lithium_battery_wh mandatory for electronics containing batteries. ≥100Wh blocked on surface for some partners; UI must surface.
service_level STRICT ENUM.

3. PROVIDER TOOLS

`intercity.quote`

Multi-partner price + ETA + service level.

`intercity.eway_bill_required`

Returns true if value ≥ ₹50k and intercity; partner auto-handles generation.

`intercity.create_order`

Books with chosen partner; returns AWB (airway bill) / shipment ID.

`intercity.schedule_pickup`

Sets pickup slot.

`intercity.track`

Scan-event stream.

`intercity.dispute_lost_damaged`

Opens claim within partner's insurance window.

`intercity.cancel`

Pre-pickup only.

4. RESPONSE SHAPE

{
  "intent": "logistics.send_intercity_parcel",
  "request_id": "req_ic_2q9w_2026-05-14T10:00:00Z",
  "options": [
    {
      "tier": "OK",
      "provider": "DTDC",
      "service_level": "surface_5_7d",
      "price_inr": 180,
      "eta_business_days": 6,
      "pickup_within_hours": 24,
      "insurance_included_inr": 5000,
      "insurance_top_up_available": true,
      "lithium_battery_surface_allowed": true,
      "eway_bill_required": true,
      "eway_bill_partner_handled": true,
      "ttbs_score": 0.62,
      "tier_reason": "cheapest, 5-7 days"
    },
    {
      "tier": "GOOD",
      "provider": "Delhivery",
      "service_level": "express_2d",
      "price_inr": 420,
      "eta_business_days": 2,
      "pickup_within_hours": 6,
      "insurance_included_inr": 10000,
      "insurance_top_up_available": true,
      "lithium_battery_surface_allowed": true,
      "eway_bill_required": true,
      "eway_bill_partner_handled": true,
      "tracking_scan_granularity": "hub_plus_linehaul",
      "ttbs_score": 0.82,
      "tier_reason": "balanced — 2 days, decent insurance"
    },
    {
      "tier": "GREAT",
      "provider": "BlueDart",
      "service_level": "overnight_1d",
      "price_inr": 780,
      "eta_business_days": 1,
      "pickup_within_hours": 4,
      "insurance_included_inr": 65000,
      "insurance_cover_meets_declared_value": true,
      "lithium_battery_surface_allowed": true,
      "eway_bill_required": true,
      "eway_bill_partner_handled": true,
      "tracking_scan_granularity": "every_handover",
      "premium_packaging_included": true,
      "ttbs_score": 0.91,
      "tier_reason": "next-day + full declared-value cover + premium packaging"
    }
  ],
  "eway_bill_check": {
    "required": true,
    "reason": "declared_value ₹65,000 ≥ ₹50,000",
    "partner_will_generate": true
  }
}

5. CONTROLLED VOCABULARIES

`service_level`

surface_5_7d · express_2d · overnight_1d

`cargo.category`

documents · electronics · apparel · home_goods · pharmacy_otc · gift_box · food_non_perishable · other_lawful

BANNED

cash · gold_jewellery · narcotics · weapons · flammable_liquid · compressed_gas · radioactive · livestock · lithium_loose_over_100Wh · human_remains · pharmacy_prescription_controlled

`tracking_scan_granularity`

hub_only · hub_plus_linehaul · every_handover

All STRICT ENUM.

6. TTBS DIMENSIONS

TIME (weight 0.30)

eta_business_days
pickup_within_hours
Hub coverage of destination PIN
TIME = 1 − eta_business_days / 7

TASTE (weight 0.10)

Partner brand familiarity
Tracking UX granularity
TASTE = brand_band × tracking_granularity_band

BUDGET (weight 0.35)

price_inr vs best in tier
Insurance top-up cost transparency
Per-kg overage handling
BUDGET = 1 − (price − best) / best

SAFETY (weight 0.25)

insurance_cover_meets_declared_value boolean
Partner damage-claim historical settlement rate
Tracking granularity (every_handover best)
E-way bill compliance auto
Battery-rule compliance
SAFETY = insurance_fit × claim_band × tracking_band × eway_compliant × battery_compliant

HARD FILTERS

Cargo category not in banned list.
Lithium battery rule satisfied for chosen service_level.
E-way bill auto-generation available where required.
Destination PIN serviced by partner.
Insurance available ≥ declared_value (top-up acceptable) OR user-acknowledged gap.

7. COMPLETION CONTRACT

Success criteria

AWB issued; pickup slotted.
Pickup scan recorded with photo.
In-transit hub scans observed.
Out-for-delivery scan in destination city.
Delivered scan with recipient signature/OTP.
CPC webhook fires.

CPC webhook

{
  "event": "logistics.send_intercity_parcel.completed",
  "intent_id": "logistics.send_intercity_parcel",
  "request_id": "req_ic_2q9w_2026-05-14T10:00:00Z",
  "awb": "BD9KP2401223",
  "provider": "BlueDart",
  "service_level": "overnight_1d",
  "price_inr": 780,
  "tomo_commission_base_inr": 90,
  "tomo_commission_inr": 9,
  "pass_through_inr": 690,
  "declared_value_inr": 65000,
  "insurance_cover_inr": 65000,
  "eway_bill_no": "EW1245678901",
  "delivered_at_iso": "2026-05-15T17:21:00+05:30",
  "signature_hmac_sha256": "…"
}

Failure cases

lost_in_transit → claim via partner insurance.
damaged_at_delivery → recipient unboxing photo → claim.
rto_address_invalid → return-to-sender with partner-published fee.
pickup_failed_no_response → reschedule or cancel.

8. WIDGET

{
  "widget": "InterCityParcelWidget",
  "header": {
    "route_strip": "Hyderabad → Mumbai · ~750 km",
    "deadline_strip": "Choose service level",
    "eway_bill_strip": "E-way bill auto (₹65,000 ≥ ₹50k)"
  },
  "regions": {
    "region_1_intelligence": ["laptop, 2.4 kg, 55 Wh battery", "battery within surface rules", "declared ₹65,000"],
    "region_2_summary": "Pickup tomorrow, deliver per service level",
    "region_3_visual": null,
    "region_4_now_pin": "Book — pickup within 4 h",
    "region_5_tomo_choices": [
      {"tier": "OK", "label": "DTDC Surface · ₹180 · 5–7 days", "reason": "cheapest"},
      {"tier": "GOOD", "label": "Delhivery Express · ₹420 · 2 days", "reason": "balanced"},
      {"tier": "GREAT", "label": "BlueDart Overnight · ₹780 · 1 day · full cover", "reason": "fastest + full insurance"}
    ]
  },
  "footer_disclosures": [
    "Above ₹50,000 declared value, GST E-way bill is required — partner generates automatically.",
    "Batteries above 100 Wh can't go on surface — declare correctly to avoid pickup rejection.",
    "Keep an unboxing photo on delivery — needed if you file a damage claim."
  ]
}

9. CACHING POLICY

Quote: 5 min TTL.
PIN serviceability matrix: 24h.
Partner insurance cover bands: 7 days.
Past shipments: 1 year on-device, encrypted.

10. ERROR CODES

Code	Meaning	UI surface
`ERR_PIN_UNSERVICED_DESTINATION`	dest PIN not in partner network	Suggest alt partner
`ERR_BATTERY_OVER_LIMIT`	Wh > surface allowance	Switch service or remove battery
`ERR_BANNED_CATEGORY`	category in banned list	Plain blocker
`ERR_EWAY_BILL_MISSING_GSTIN`	partner needs GSTIN for E-way	Capture GSTIN inline
`ERR_INSURANCE_GAP`	cover < declared_value	Top-up offer or user override
`ERR_PICKUP_SLOT_UNAVAILABLE`	no slots in window	Re-pick slot
`ERR_AWB_GEN_FAILED`	partner rejected order	Retry / try next partner
`ERR_DAMAGE_CLAIM_WINDOW_CLOSED`	beyond claim window	Apology + escalation
`ERR_RTO_INITIATED`	recipient unreachable 3 tries	Plain explainer
`ERR_HAZMAT_FLAGGED`	partner-side hazmat detection	Block + refund

11. SANDBOX → PRODUCTION CHECKLIST

Sandbox banned-category reject every banned ENUM including battery edge cases.
Sandbox E-way bill auto-generates at ₹50,001; not at ₹49,999.
Sandbox insurance top-up flow ends with cover = declared_value.
Sandbox tracking scans: pickup, hub-in, hub-out, OFD, delivered.
Sandbox claim window enforced.
Production partner PIN matrix synced daily.
Production HSN/HSN-like cargo-category mapping reviewed quarterly.
Production AWB conflict-rate < 0.1%.
Production pickup-failed retry policy: max 3 attempts.
Production CPC HMAC-SHA256 5-min replay verified.

12. ANTI-FABRICATION RULES

NO paid_placement on partners — TTBS only.
NO synthetic ETA — partner quote only.
NO "guaranteed overnight" without partner SLA.
NO concealing surge / fuel surcharge.
NO claiming insurance cover > partner's actual.
NO using TOMO-issued AWB — always partner.
NO claiming E-way bill compliance for goods exempted (regulatory honesty).
NO holding parcel data — partner is custodian.
NO marketing of "smart logistics".
NO TOMO-issued "fastest in India" claim.

13. REGULATORY FRAMING

Carriage by Road Act 2007 governs intercity goods carriers.
GST E-way Bill Rules (Rule 138, CGST) — value ≥ ₹50k triggers E-way bill; partner auto-generates.
Civil Aviation Requirements (CAR) DGCA — surface lithium battery rules align with ICAO; >100 Wh restricted.
Consumer Protection Act 2019 — partner is service provider, TOMO is intermediary.
IRDAI — partner-issued insurance.
DPDPA 2023 — addresses/phone are personal data; partner is processor, TOMO holds pointer only.
TOMO does NOT operate trucks/hubs, does NOT issue AWBs, does NOT carry consignment liability.

logistics.send_intercity_parcel — Full Intent Specification