Shippo support ticket

<!-- ⚠️ DO NOT EDIT. Auto-generated from skills/shippo-support-ticket/SKILL.md by scripts/sync.js Edits here will be overwritten on the next sync. To change this content, edit the canonical source and re-run the sync script. -->

Shippo Support Ticket Builder

Turn a single shipment identifier into a complete, classified, well-structured support package for the Shippo support team. The agent classifies the issue, gathers every relevant fact from the Shippo MCP (running issue-type-specific lookups, not just the lost-package set), computes the triage timeline, and emits two things:

1. A human copy-paste block for the ticket body.
2. A structured JSON block tagged with a routing queue, so the ticket can be piped into the ticketing system and land in the right pipeline without a human re-classifying it.

This dual output is the point: completeness and correct routing are what kill the back-and-forth.

Audience: Shippo support agents. Output uses Shippo terminology, object IDs, and an internal routing tag. It is not customer-facing copy.

When to use

Use this skill when someone wants to escalate or document a shipping problem and asks for a support ticket / message to Shippo support, e.g. "package is stuck," "label was charged but never shipped," "why was I charged more than the rate I saw," "refund this label I never used," "where is this delivery," "the address looks wrong," "tracking updates aren't coming through," "can't get rates from this carrier." It produces text + JSON to copy and paste; it does not open a Jira ticket or send Slack/email itself.

Step 1: Classify the issue (do this first)

Pick exactly one canonical issue type from the customer's description. The issue type drives both the routing tag and which extra lookups you run in Step 4. If the wording is ambiguous, ask one clarifying question before building.

Issue type (canonical)	Triggers / signals	Routing tag
lost_or_delayed	stuck, late, no movement, "where is my package", lost	queue:tracking-ops
unused_label_refund	"never shipped", "refund this label", bought-but-unused	queue:billing-refunds
billing_adjustment	"charged more than the rate", surcharge, reweigh, dim-weight, address-correction fee	queue:billing-adjustments
address_exception	undeliverable, returned to sender, bad/invalid address, address correction	queue:address-exceptions
customs_international	customs hold, duties/taxes, missing HS code, commercial invoice, international	queue:customs-intl
carrier_account	"can't get rates from <carrier>", connection failed, registration pending	queue:carrier-onboarding
tracking_webhook	"tracking updates aren't coming through", webhook not firing	queue:integrations
other	anything that doesn't fit above	queue:general-triage

The routing tags above are a stable, machine-parseable routing schema; the receiving team maps each queue:* tag to its own ticketing queue, so the exact queue strings are configurable to match your support system. The skill's value is producing a consistent, machine-parseable tag; the exact strings should match your ticketing system.

Inputs accepted

The user may start from any one of these. Ask which one they have if it is ambiguous; do not guess an ID type.

Input	What it anchors
Tracking number + carrier	Drives GetTrack directly. Best for delivery/lost-package issues.
Transaction (label) object ID	Cleanest anchor: label creation time + tracking number + the rate/shipment link, all derivable.
Shipment object ID	Gives from/to addresses, requested shipment_date, and rates; tracking number comes from the purchased transaction.

Resolving a tracking number to its label. First detect the carrier and map it to the Shippo carrier token (see the note below), then call GetTrack. When the label was purchased through Shippo, the GetTrack response carries the transaction object_id; use that with GetTransaction to pull the label and billing facts. If the label was not bought through Shippo (no transaction comes back), there is nothing to resolve: build the ticket from GetTrack plus whatever the user supplied and mark the label fields "Not available." ListTransactions has no server-side tracking_number filter, so paging it to match by hand is a rarely-useful last resort, not the primary path.

Carrier token: GetTrack expects a Shippo carrier token, not a display name, e.g. usps, ups, fedex, dhl_express, dhl_ecommerce, canada_post. If you only have a display name (often from a rate's provider), map it to the token. If unsure, ask the user for the carrier.

Shippo MCP tools used

Discover/confirm with shippo_list_tools and shippo_describe_tool; execute read-only lookups with shippo_read_execute_tool. Everything this skill needs is a read operation; never call a write tool (e.g. CreateRefund) from this skill; the ticket only documents and recommends.

Core reads (all issue types):

• GetTransaction: label creation time (object_created), tracking_number, status, rate reference, eta, metadata (order/internal reference)
• GetShipment: address_from, address_to, requested shipment_date, parcels, rates, customs_declaration, extra (added services + references), messages
• GetTrack: current tracking_status, full tracking_history[], eta, and (for Shippo-purchased labels) the transaction object reference

Issue-type-specific reads (Step 4):

• GetRate: purchased amount, currency, provider, servicelevel, estimated_days (billing)
• GetParcel: declared length/width/height, distance_unit, weight, mass_unit (billing)
• ListRefunds / GetRefund: existing refund object + status (refund)
• ValidateAddress / ValidateAddressByID: is_valid, messages, residential flag (address)
• GetCustomsDeclaration / GetCustomsItem: contents_type, incoterm, eel_pfc, per-item tariff_number (HS code), value_amount, origin_country (customs)
• ListCarrierAccounts / GetCarrierAccount / GetCarrierRegistrationStatus: active, registration status (carrier-account)
• listWebhooks / getWebhook: url, event, active (webhook)

Step 2: Resolve the anchor object

Always work toward having the four core objects: transaction, shipment, addresses, and tracking. Stop early only when the issue genuinely needs nothing more (e.g. a pure tracking-status question with no label on file).

• Transaction ID → GetTransaction. Read object_created (label creation time), tracking_number, tracking_url_provider, status, and the rate reference. Inspect for a shipment reference to get the shipment ID.
• Shipment ID → GetShipment. Read address_from, address_to, shipment_date (the requested ship date), parcels, rates, customs_declaration. Find the purchased rate/transaction for the tracking #.
• Tracking number + carrier → map the carrier to its token and call GetTrack. For a Shippo-purchased label the response carries the transaction object_id; follow it with GetTransaction to get the billing/label facts.

Step 3: Pull the core facts

Pull the shipment (GetShipment) for address_from, address_to, shipment_date if not already loaded, and tracking (GetTrack with carrier token + tracking number) for tracking_status, tracking_history[], and eta.

From each address object capture only its object_id and coarse geography (city, state, zip, country) for the ticket, not name, street1, or street2 (see PII minimization in guardrails).

• First carrier scan = the earliest tracking_history event representing physical acceptance by the carrier (the first TRANSIT/DELIVERED-class scan, or the carrier's "accepted/picked up" event). Pre-transit / "label created" / "shipment info received" pseudo-events do not count; call those out separately if present.
• Added services and order reference (capture them): surface the shipment's extra block (added services such as signature_confirmation, insurance, Saturday delivery, QR-code labels) and the customer's own order / internal reference number. That reference can live in two places depending on the integration: the transaction's metadata field (the documented home for order numbers) and/or the shipment extra reference fields. Capture it from wherever it actually appears, so the agent can tie the ticket back to the order without searching on an order number. The extra schema is nuanced and carrier/service-dependent, so read the actual response fields rather than assuming names: the label-purchase skill documents the common added-service options (signature, insurance, Saturday delivery) and shippo/references/carrier-guide.md covers per-carrier availability. Surface only what is actually present; omit the rest.
• messages noise: a shipment's messages array often carries routine "carrier doesn't support option" / "out of service area" entries. These are informational. Only surface messages tied to a carrier that actually appears in rates.
• Read the actual response fields: do not assume names. If a field is absent, record "Not available" rather than inventing a value.

Step 4: Run the issue-type branch

After the core facts, run only the lookups for the classified issue type and fill the matching section of the output. Skip branches that don't apply.

• lost_or_delayed: no extra reads; the core timeline carries it. Emphasize "last scan → now" and "overdue vs ETA."
• unused_label_refund: Was the label ever scanned? Re-check GetTrack: if there is a real carrier scan, the label is used (not eligible as an unused refund). Say so. Compute label age from object_created to now. Call ListRefunds (and GetRefund) to report any existing refund object + its status. Do not assert a specific eligibility window from memory; state the facts (used/unused, age, existing refund) and let the queue apply policy.
• billing_adjustment: GetRate for the purchased amount/currency; GetParcel (or shipment parcels) for declared dims/weight; compare the transaction's charged amount to the quoted rate. Flag the likely cause: dimensional-weight reweigh (declared vs billed dims), address-correction surcharge, or service upgrade. Report declared-vs-billed as the core evidence. Note: the reweigh/adjustment amount and the carrier's billed dims may not be exposed by these read ops; if so, record "Not available" rather than inferring.
• address_exception: run ValidateAddress/ValidateAddressByID on address_to; report is_valid, any validation messages, and the residential/commercial flag. Note whether validation was bypassed at purchase.
• customs_international: pull GetCustomsDeclaration + each GetCustomsItem. Check completeness: contents_type, incoterm, eel_pfc/AES exemption, and per item a tariff_number (HS code), value_amount, and origin_country. Flag missing HS codes / values, the usual cause of customs holds.
• carrier_account: ListCarrierAccounts, then GetCarrierAccount / GetCarrierRegistrationStatus for the relevant carrier. Report active and registration status; an incomplete registration is the usual "no rates" cause.
• tracking_webhook: listWebhooks + getWebhook. Report whether an active webhook exists for the relevant track_updated/tracking event and the configured url.

Timeline to compute

These derived metrics pre-diagnose the issue so support doesn't have to:

• Label created → first carrier scan: how long the label sat before entering the network. A large gap is the classic "bought but never shipped" signature.
• Requested shipment_date → first carrier scan: picked up on/near intent?
• First scan → last scan: total time in transit so far.
• Last scan → now: days of silence; a long gap signals a stalled/lost parcel.
• ETA vs. now: is it overdue?

State each as an absolute date/time and a duration (e.g. "Label created 2026-06-01 14:02 UTC; first scan 2026-06-05 09:11 UTC, a 3d 19h gap"). Use UTC and label it. In the JSON block, also emit each gap in whole hours.

Output

Emit both blocks below, each as its own fenced block. Replace every <...> placeholder; use "Not available" for anything you could not retrieve; never invent values.

Provenance (required). Both blocks carry a generation stamp so support can tell at a glance that the ticket was machine-assembled, and so ticket quality can be tracked over time. Stamp:

• the skill name (shippo-support-ticket),
• the source (Shippo MCP),
• the generation time in UTC (ISO 8601).

Never alter or omit the stamp, and never present an auto-generated ticket as if it were hand-written.

After the blocks, add a short plain-language triage summary (1-3 sentences) naming the most likely problem based on the classification + timeline, and list any data you could not retrieve.

Block A: Human ticket (copy-paste)

Subject: [<issue_type>] <one-line summary>, tracking <tracking_number>

ROUTING
  Issue type:      <canonical issue type>
  Routing tag:     <queue:...>
  Confidence:      <high | medium | low; note if classified from sparse info>

ISSUE
  Reported by:     <customer name / email, if known>
  Summary:         <2-3 sentence description in plain language>

SHIPMENT
  Shipment ID:     <shipment object_id>
  Transaction ID:  <transaction object_id>
  Carrier:         <carrier display name> (<carrier token>)
  Service level:   <servicelevel name>
  Tracking #:      <tracking_number>
  Tracking URL:    <tracking_url_provider>
  Parcel:          <declared dimensions + weight, if available>
  References:      <order/internal ref from transaction metadata or shipment extra, else "none">
  Added services:  <signature / insurance / QR code / etc. from extra, else "none">

ADDRESSES (no street-level PII; run GetAddress on an ID for full details)
  From address ID: <address_from object_id>
  From region:     <city> <state> <zip> <country>
  To address ID:   <address_to object_id>
  To region:       <city> <state> <zip> <country>

TIMELINE (all times UTC)
  Label created:           <object_created>
  Requested ship date:     <shipment_date>
  First carrier scan:      <status_date> @ <location>   (<status>)
  Last/most recent scan:   <status_date> @ <location>   (<status>)
  Current status:          <tracking_status>
  Carrier ETA:             <eta or "Not available">

  Label created → first scan:     <duration, e.g. 3d 19h>
  Requested ship → first scan:    <duration or note>
  First scan → last scan:         <duration>
  Last scan → now:                <duration>
  Overdue vs ETA:                 <yes/no + by how much>

ISSUE-SPECIFIC FINDINGS
  <Only the block for the classified issue type; examples:>
  [unused_label_refund]  Label used (scanned)? <yes/no>; Label age: <duration>;
                         Existing refund: <refund object_id + status or "none">
  [billing_adjustment]   Quoted rate: <amount> <ccy>; Charged: <amount> <ccy>;
                         Declared dims/wt: <...>; Likely cause: <reweigh/surcharge>
  [address_exception]    Address valid: <yes/no>; Validation messages: <...>;
                         Residential: <yes/no/unknown>
  [customs_international] Contents type: <...>; Incoterm: <...>;
                         Items missing HS code/value: <list or "none">
  [carrier_account]      Carrier: <...>; Active: <yes/no>; Registration: <status>
  [tracking_webhook]     Active webhook for tracking events: <yes/no>; URL: <...>

TRACKING HISTORY (most recent first)
  <status_date>  <status>  <location>  <substatus/text>
  <... one line per scan ...>

WHAT WE NEED FROM SUPPORT
  <the specific ask: locate package / refund label / explain charge / fix
   address / clear customs / complete carrier registration / fix webhook>

(Auto-generated by the "shippo-support-ticket" skill via the Shippo MCP on
  <generation time UTC>. Facts collected automatically; verify before acting.)

Block B: Structured JSON (for the pipeline)

{
  "issue_type": "<canonical issue type>",
  "routing_tag": "<queue:...>",
  "classification_confidence": "<high|medium|low>",
  "reported_by": "<email or name or null>",
  "summary": "<one-line summary>",
  "identifiers": {
    "transaction_id": "<or null>",
    "shipment_id": "<or null>",
    "tracking_number": "<or null>",
    "carrier_token": "<or null>",
    "service_level": "<or null>",
    "order_reference": "<order/internal ref from transaction metadata or shipment extra, or null>"
  },
  "shipment_extra": {
    "<only the added-service `extra` fields actually present; e.g. signature_confirmation, insurance, qr_code>": ""
  },
  "addresses": {
    "from": { "address_id": "<or null>", "city": "", "state": "", "zip": "", "country": "" },
    "to":   { "address_id": "<or null>", "city": "", "state": "", "zip": "", "country": "" }
  },
  "timeline_utc": {
    "label_created": "<ISO8601 or null>",
    "requested_ship_date": "<ISO8601 or null>",
    "first_carrier_scan": "<ISO8601 or null>",
    "last_scan": "<ISO8601 or null>",
    "carrier_eta": "<ISO8601 or null>",
    "current_status": "<or null>"
  },
  "gaps_hours": {
    "label_to_first_scan": "<int or null>",
    "requested_ship_to_first_scan": "<int or null>",
    "first_to_last_scan": "<int or null>",
    "last_scan_to_now": "<int or null>",
    "overdue_vs_eta": "<int or null>"
  },
  "issue_findings": {
    "<keys depend on issue_type; e.g. label_used, label_age_hours, existing_refund_status, quoted_amount, charged_amount, declared_dims, address_is_valid, items_missing_hs_code, carrier_active, registration_status, webhook_active>": ""
  },
  "requested_action": "<the specific ask>",
  "data_gaps": ["<fields that could not be retrieved>"],
  "generated_by": {
    "skill": "shippo-support-ticket",
    "source": "shippo-mcp",
    "generated_at": "<ISO8601 UTC>"
  }
}

Edge cases & guardrails

• Read-only: This skill never calls write operations. Recommend a refund; don't issue one.
• Multiple matches when paging ListTransactions as a fallback: list the candidates and ask the user to pick before building the ticket.
• Stale objects: objects older than 390 days aren't returned. If lookups fail for that reason, note it and build from whatever the user provided plus tracking.
• Classification confidence: if you classified from sparse wording, set confidence low and say why, so the queue knows to sanity-check the tag.
• PII minimization (required): Do not put recipient/sender names or street lines (street1/street2) in the ticket, not in the human block and not in the JSON. Reference the address_from / address_to object_ids instead; support can run GetAddress on an ID to retrieve full details and replicate the issue only when they actually need to. Coarse geography (city, state/province, ZIP/postal, country) is retained, since support needs it for zone/routing triage. Tracking-history location values (typically city/state) are fine. Don't pull in unrelated shipments, and don't include API tokens or raw object dumps beyond what the templates ask for.
• Never invent timestamps, statuses, addresses, IDs, or HS codes. Missing → "Not available" (human block) / null (JSON).