logistics.send_international_parcel — Full Intent Specification

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

International outbound parcel from India. Distinct from logistics.send_intercity_parcel because: (a) customs is mandatory — commercial invoice + HS code + declared value in destination currency; (b) destination country has its own prohibited list (e.g., wood items to Australia, food to Japan); (c) duties/taxes paid by recipient (DDU) or sender (DDP); (d) battery rules under IATA-DGR; (e) sanctions / export-control screening (DGFT, BIS, OFAC where applicable); (f) shipping mode = air parcel (DHL/FedEx/Aramex) or international postal (India Post / EMS); (g) insurance, customs duty, and last-mile fee tend to dwarf the carriage fee. TOMO surfaces the all-in landed cost honestly — never partial.

1. NATURAL LANGUAGE COVERAGE

Classifies IN

• "send parcel to USA"
• "ship to my son in Toronto"
• "courier documents to UK"
• "DHL Dubai 2 kg gift"
• "international shipping medicines London"
• "send saree to Sydney"
• "FedEx Germany overnight"
• "EMS to Japan, 3 days"
• "ship laptop to Singapore"
• "send gift hamper to Doha"

Classifies OUT — borderline NO

• "send to Mumbai" → logistics.send_intercity_parcel
• "send to friend across town" → logistics.send_intracity_parcel
• "ship a car/bike abroad" → out of v1 (vehicle export = specialty)
• "send cash abroad" → BANNED; user redirected to travel.book_forex / banking wire
• "tickets to international concert" → entertainment.book_concert_ticket

MULTI-INTENT TRIGGERS

• "ship docs to UK + book forex" → logistics.send_international_parcel + travel.book_forex
• "send Diwali hamper to NYC + virtual greeting"

2. INPUT — TOMO → PROVIDER

{
  "intent":          "logistics.send_international_parcel",
  "intent_version":  "v1.0.0",
  "request_id":      "req_intl_3z2k_2026-05-14T11: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": {
    "country_iso2":   "US",
    "country_subdivision_iso_3166_2": "US-NY",
    "city":           "New York",
    "postal_code":    "10001",
    "address_lines":  ["123 5th Ave", "Apt 4B"],
    "contact_phone_e164": "+1XXXXXXXXXX",
    "recipient_name": "Rohit Gamasany"
  },

  "cargo": {
    "category":         "gift_box",
    "sub_category":     "non_perishable_food_and_apparel",
    "hs_code":          "62052000",
    "size_band":        "carton_small",
    "dim_l_cm":         30, "dim_w_cm": 22, "dim_h_cm": 12,
    "weight_kg":        1.6,
    "declared_value_inr": 8500,
    "declared_value_usd_equivalent": 102,
    "commercial_or_gift": "gift",
    "lithium_battery_present": false
  },

  "service_mode": "air_express",
  "service_modes_allowed": ["air_express", "air_economy", "ems_postal"],
  "duty_mode": "ddu",
  "duty_modes_allowed": ["ddu", "ddp"],

  "screening": {
    "sender_name":      "Keerthi Krishna Gamasany",
    "sender_id_type":   "PAN",
    "sender_id_value":  "XXXXX1234X",
    "kyc_band":         "full"
  },

  "user_constants": {
    "preferred_partners": ["DHL", "FedEx", "Aramex", "India Post EMS"]
  }
}

Field rules

• hs_code STRICT 6-8 digit HS / Indian Tariff. Partner / TOMO may suggest but user must confirm.
• declared_value_usd_equivalent computed using daily RBI ref rate.
• commercial_or_gift drives customs paperwork. Gift exemption thresholds vary by destination — partner surfaces.
• duty_mode DDU (recipient pays) vs DDP (sender pays) — explicit user choice.

3. PROVIDER TOOLS

intl.quote

Multi-partner price + ETA + duty estimate + landed cost.

intl.prohibited_check

Returns whether HS code + cargo category is allowed into destination country.

intl.duty_estimate

Estimates destination duties + taxes (HMRC, USCBP, GCC, EU VAT). Always labelled as estimate.

intl.sanctions_screen

Screens recipient name + address against DGFT/OFAC/EU sanctions lists. Hard block on hit.

intl.create_order

Books with partner; returns AWB + customs paperwork bundle (commercial invoice / pro forma / CN23).

intl.kyc_submit

Uploads sender KYC (PAN / passport) per partner + ECCN/EAR if export-controlled.

intl.track

Cross-border scan stream.

intl.dispute

Lost/damaged claim within partner window.

intl.cancel

Pre-pickup only.

4. RESPONSE SHAPE

{
  "intent": "logistics.send_international_parcel",
  "request_id": "req_intl_3z2k_2026-05-14T11:00:00Z",
  "prohibited_check": {"passed": true, "destination_country_iso2": "US"},
  "sanctions_screen": {"passed": true, "lists_checked": ["DGFT", "OFAC", "EU"]},
  "options": [
    {
      "tier": "OK",
      "provider": "India Post EMS",
      "service_mode": "ems_postal",
      "carriage_inr": 1450,
      "duty_estimate_inr": 0,
      "fuel_surcharge_inr": 0,
      "all_in_inr": 1450,
      "eta_business_days": 7,
      "tracking_scan_granularity": "country_handover",
      "insurance_included_inr": 0,
      "insurance_top_up_available": true,
      "ttbs_score": 0.58,
      "tier_reason": "cheapest but slow, low tracking"
    },
    {
      "tier": "GOOD",
      "provider": "Aramex",
      "service_mode": "air_economy",
      "carriage_inr": 2200,
      "duty_estimate_inr": 0,
      "fuel_surcharge_inr": 180,
      "all_in_inr": 2380,
      "eta_business_days": 5,
      "tracking_scan_granularity": "hub_plus_handover",
      "insurance_included_inr": 5000,
      "ttbs_score": 0.75,
      "tier_reason": "balanced — 5 days, decent tracking"
    },
    {
      "tier": "GREAT",
      "provider": "DHL Express",
      "service_mode": "air_express",
      "carriage_inr": 4100,
      "duty_estimate_inr": 0,
      "fuel_surcharge_inr": 220,
      "all_in_inr": 4320,
      "eta_business_days": 3,
      "tracking_scan_granularity": "every_handover",
      "insurance_included_inr": 8500,
      "insurance_cover_meets_declared_value": true,
      "customs_paperwork_pre_filed": true,
      "ttbs_score": 0.89,
      "tier_reason": "fastest + full cover + customs pre-filed"
    }
  ],
  "duty_disclosure": {
    "destination_country_iso2": "US",
    "gift_threshold_usd": 100,
    "declared_value_usd_equivalent": 102,
    "duty_likely": "yes_small",
    "estimate_band_usd": "5_to_15",
    "payable_by": "recipient_at_delivery_if_DDU",
    "estimate_source": "partner_quote",
    "disclaimer": "Destination customs may revise — actual duty determined at port of entry"
  }
}

5. CONTROLLED VOCABULARIES

service_mode

air_express · air_economy · ems_postal

duty_mode

ddu (Delivered Duty Unpaid — recipient pays) · ddp (Delivered Duty Paid — sender pays)

cargo.category

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

BANNED — universal

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

BANNED — country-dependent (partial list, partner-resolved)

• wood_untreated to AU/NZ
• meat_dairy_animal_product to AU/JP/EU varies
• seeds_plants to most countries
• electronic_cigarette_vape to many
• cosmetic_alcohol_volume_over_70pct to many

All STRICT ENUM; country layer resolved via intl.prohibited_check.

6. TTBS DIMENSIONS

TIME (weight 0.25)

• eta_business_days
• Pre-filed customs reduces clearance time
• Pickup-within-hours
• TIME = 1 − eta_business_days / 10

TASTE (weight 0.10)

• Partner brand familiarity
• Tracking granularity (every_handover best)
• App / portal UX
• TASTE = brand_band × tracking_band

BUDGET (weight 0.30)

• all_in_inr (carriage + fuel + duty estimate + insurance top-up)
• Duty mode honesty
• Hidden last-mile fee
• BUDGET = 1 − (all_in − best) / best

SAFETY (weight 0.35 — dominant)

• Sanctions/prohibited screen passed
• insurance_cover_meets_declared_value
• Tracking granularity
• Partner claim-settlement band
• Customs paperwork accuracy (HS code, commercial invoice)
• Battery rules compliance
• SAFETY = sanctions_pass × prohibited_pass × insurance_fit × tracking_band × paperwork_band × battery_compliance

HARD FILTERS

1. Sanctions screen passes.
2. Prohibited-list check passes for destination country.
3. HS code present and plausible.
4. Battery rules satisfied for service mode.
5. Sender KYC complete.

7. COMPLETION CONTRACT

Success criteria

1. AWB issued.
2. Customs paperwork bundle pre-filed (where partner supports).
3. Pickup scan.
4. India export customs cleared.
5. Destination import customs cleared.
6. Out-for-delivery scan in destination city.
7. Delivered scan with recipient signature.
8. CPC webhook fires.

CPC webhook

{
  "event": "logistics.send_international_parcel.completed",
  "intent_id": "logistics.send_international_parcel",
  "request_id": "req_intl_3z2k_2026-05-14T11:00:00Z",
  "awb": "DHL12345678",
  "provider": "DHL Express",
  "service_mode": "air_express",
  "destination_iso2": "US",
  "carriage_inr": 4100,
  "fuel_surcharge_inr": 220,
  "duty_paid_inr": 0,
  "duty_mode": "ddu",
  "all_in_inr": 4320,
  "tomo_commission_base_inr": 540,
  "tomo_commission_inr": 54,
  "pass_through_inr": 3780,
  "delivered_at_iso": "2026-05-17T10:42:00-04:00",
  "signature_hmac_sha256": "…"
}

Failure cases

• customs_held → user notified with action items (additional docs, duty payment).
• sanctions_hit → block at intake, refund pre-pickup.
• recipient_refused_duty → return-to-sender; partner fees apply.
• lost_in_transit → claim under partner insurance.

8. WIDGET

{
  "widget": "IntlParcelWidget",
  "header": {
    "route_strip": "Hyderabad → New York · ~12,500 km",
    "country_strip": "US · gift exemption $100",
    "sanctions_strip": "Sanctions screen passed"
  },
  "regions": {
    "region_1_intelligence": ["gift box, 1.6 kg, $102 declared", "HS 62052000", "no battery", "DDU — recipient may pay small duty"],
    "region_2_summary": "Pickup tomorrow, deliver in 3–7 days based on service",
    "region_3_visual": null,
    "region_4_now_pin": "Book — pickup in 4 h",
    "region_5_tomo_choices": [
      {"tier": "OK", "label": "India Post EMS · ₹1,450 · 7 days", "reason": "cheapest"},
      {"tier": "GOOD", "label": "Aramex Air Economy · ₹2,380 · 5 days", "reason": "balanced"},
      {"tier": "GREAT", "label": "DHL Express · ₹4,320 · 3 days + full cover", "reason": "fastest + safest"}
    ]
  },
  "footer_disclosures": [
    "Destination customs decides final duty — partner estimate is informational.",
    "Recipient may need to pay a small duty on delivery (DDU) — switch to DDP if you want to pre-pay.",
    "Prohibited list varies by country — we screen automatically but recipient address details matter."
  ]
}

9. CACHING POLICY

• Quote: 5 min TTL.
• Sanctions list refresh: daily.
• Country prohibited matrix: weekly partner pull.
• HS code suggestions: cached 30 days on-device.
• Past international shipments: 1 year on-device, encrypted.

10. ERROR CODES

11. SANDBOX → PRODUCTION CHECKLIST

• Sandbox sanctions screen blocks known-test entries.
• Sandbox prohibited matrix tested for 10 destination countries.
• Sandbox HS code helper rejects invalid codes.
• Sandbox battery rule blocks >100Wh on air.
• Sandbox DDP flow charges sender for estimated duty up front.
• Sandbox DDU flow returns "may be charged at delivery" disclosure.
• Sandbox customs-held flow surfaces inline action.
• Production sanctions list refreshed daily from DGFT / OFAC / EU feeds.
• Production duty estimate disclaimer visible on every quote.
• Production partner AWB issuance latency < 90s p95.
• Production claim window enforced per partner.
• Production multi-currency display: INR + destination currency equivalent.

12. ANTI-FABRICATION RULES

• NO synthetic duty estimate — partner-quoted with disclaimer only.
• NO "sanctions-safe" claim without screen.
• NO concealing duty mode (DDU/DDP) in price.
• NO bundling "free customs clearance" if recipient may still be charged.
• NO claiming "delivered cleared" until partner clears customs.
• NO TOMO-issued AWB.
• NO paid_placement on partners.
• NO "Worldwide express" / marketing language.
• NO synthetic country-by-country prohibited list — partner authoritative.
• NO holding customs paperwork at TOMO — partner is custodian.

13. REGULATORY FRAMING

• Customs Act 1962 + Foreign Trade (Development & Regulation) Act 1992 — DGFT export control.
• Indian Tariff / HS code — 6-8 digit classification mandatory.
• DGCA / IATA-DGR — battery air rules.
• FEMA 1999 — outward parcel containing currency banned (already in BANNED list).
• Sanctions — DGFT consolidated list + OFAC (where transit/finance touches US) + EU.
• Destination country customs — partner is filer-of-record on Indian export side; destination broker on import side.
• DPDPA 2023 + GDPR (if EU recipient) — addresses are personal data; partner is processor.
• TOMO is router only — does NOT operate carrier, does NOT clear customs, does NOT pay duty on behalf.