Shippo Official

Shippo Shipping Skill

Setup

MCP server: https://app.getgram.ai/mcp/shippo-mcp-beta with header Mcp-Shippo-Merged-Api-Key-Header set to the SHIPPO_API_KEY environment variable.

Prerequisites: A valid Shippo API key and at least one carrier account (Shippo provides managed accounts for USPS, UPS, FedEx, DHL Express by default). See references/tool-reference.md for the full tool catalog.

Test vs live mode -- check the API key prefix before any purchase workflow:

• shippo_test_*: Labels are free. No real charges. Tracking uses mock numbers only.
• shippo_live_*: Real charges. Inform the user which mode they are in.

Test and live mode have completely separate data and object IDs.

Address Validation

Address Field Format

The Shippo API uses v1 field names for address components in most endpoints (including shipments-create). Always use:

Note: The v2 address endpoints (addresses-create-v2, addresses-validate-v2) use different field names (address_line_1, city_locality, state_province, postal_code), but when passing addresses inline to shipments-create, you must use the v1 names above.

Validate a Structured Address

1. Collect at minimum: street1, city, state, zip, country (ISO 3166-1 alpha-2).
2. Call addresses-create-v2 with the address fields (creates the address, returns object ID).
3. Call addresses-validate-v2 with the same fields as query parameters (not object ID).
4. Check analysis.validation_result.value: "valid", "invalid", or "partially_valid". Check reasons for details.
5. Report the standardized address. Highlight corrected fields (changed_attributes). Note analysis.address_type ("residential", "commercial", "unknown") -- affects carrier surcharges.
6. If invalid: relay reasons. Present recommended_address if returned.
7. If partially_valid: show corrections and ask user to confirm.

Parse a Freeform Address

1. Call addresses-parse with the raw string. Response uses v2 field names: address_line_1, city_locality, state_province, postal_code.
2. The parse response does not include country. Ask the user or infer it, then add it.
3. Validate the parsed result by following the structured address workflow above from step 2.

International Addresses

• Always require the country field. Do not guess.
• Pass non-Latin characters as-is; the API handles encoding.
• Validation depth varies by country. US, CA, GB, AU, and major EU countries have deep validation. Others may only confirm structural completeness. Inform the user.

Bulk Address Validation

No batch endpoint. Call addresses-create-v2 per address. Track results and report a summary. For 50+ addresses, set expectations about processing time.

Rate Shopping

Get Rates for a Shipment

1. Collect: origin address, destination address, parcel (length, width, height, distance_unit, weight, mass_unit). All values must be strings (e.g., "10" not 10).
2. Optionally validate addresses (see Address Validation above).
3. Call shipments-create with address_from, address_to (inline v1 field names), and parcels.
4. Present the rates array as a table: carrier, service level, price, estimated days. Deduplicate by carrier/service combination.

Dimensional Weight

Carriers charge based on the greater of actual weight and dimensional weight:

dim_weight = (length x width x height) / divisor

If a package is large but light, dimensional weight will exceed actual weight and the carrier charges the higher rate. When rates seem surprisingly high, check if dimensional weight is the cause.

Flat Rate

USPS flat-rate options charge a fixed price regardless of weight (up to 70 lbs). Set the parcel template to a flat-rate token (e.g., USPS_SmallFlatRateBox) instead of custom dimensions. Flat rate wins for heavy or long-distance shipments; custom dimensions win for light, nearby packages.

Filter by Speed

Map user requests: "overnight" = estimated_days 1, "2-day" = estimated_days <= 2, "within N days" = estimated_days <= N. Filter the rates array accordingly. If nothing matches, show the fastest available.

International Rates

Some carriers require a customs declaration or phone number on the destination address for international rates. If no rates are returned, try attaching a customs declaration. See references/customs-guide.md for customs details.

Checkout Rates (Line Items)

Call rates-at-checkout-create instead of shipments-create. Accepts address_from, address_to, and line_items (each with title, quantity, total_price, currency, weight, weight_unit).

Recommendation

Identify the cheapest (lowest amount), fastest (lowest estimated_days), and best-value options. Compute by sorting -- these are not API fields. State the trade-off: "Option A is $X cheaper but takes Y more days."

Troubleshooting: No Rates

• Verify both addresses passed validation (most common cause).
• Confirm parcel dimensions are reasonable (not zero, not exceeding carrier limits).
• Shippo provides managed carrier accounts by default. Missing rates usually mean address issues, unsupported routes, or bad dimensions. Verify with carrier-accounts-list if needed.

Label Purchase

Purchase Confirmation Gate

Before every transactions-create, summarize carrier/service, cost, delivery time, and origin/destination. Do not proceed without explicit user confirmation.

Domestic Label

1. Optionally validate both addresses (see Address Validation above).
2. Call shipments-create with address_from, address_to (inline v1 field names), parcels, async: false.
3. Present rates. Let user choose. Confirm purchase (see gate above).
4. Call transactions-create with rate (object_id), label_file_type (default PDF_4x6), async: false.
5. Check status:
   • SUCCESS: return tracking_number, label_url (complete URL), tracking_url_provider.
   • QUEUED/WAITING: poll transactions-get until resolved.
   • ERROR: report messages array.

International Label

All domestic steps apply, plus customs before shipment creation. See references/customs-guide.md.

1. Validate addresses. Sender must include email and phone. Ask if missing.
2. Create customs items via customs-items-create per item, or pass inline objects in step 3.
3. Call customs-declarations-create with contents_type, non_delivery_option, certify: true, certify_signer, and items.
4. Call shipments-create with standard fields plus customs_declaration (object_id).
5. Present rates, confirm purchase, purchase label, return results.

Contents Type Decision Tree

Incoterms Decision Logic

• B2C / e-commerce (default): Use DDU (Delivered Duty Unpaid) -- recipient pays duties.
• Seller prepays duties: Use DDP (Delivered Duty Paid) -- seller covers duties/taxes.
• FedEx/DHL only: FCA (Free Carrier) for advanced trade scenarios.

Default to DDU if the user does not specify.

Label Format Options

Default to PDF_4x6 unless the user specifies otherwise.

Label Customization Options

Set these on the shipment's extra field:

• Signature confirmation (signature_confirmation): STANDARD, ADULT, CERTIFIED, INDIRECT, CARRIER_CONFIRMATION.
• Insurance (insurance): with amount, currency, provider.
• Saturday delivery (saturday_delivery): true. Only certain carriers/service levels.
• Reference fields: pass metadata on the transaction for order numbers.

Return Labels

Swap address_from and address_to so the original recipient becomes the sender. All other steps remain the same.

Voiding a Label

Call refunds-create with the transaction object_id. Eligibility depends on carrier and timing. If it fails, advise the user to contact Shippo support.

Orders and Packing Slips

1. Call orders-create with shipping address, line items, and order details.
2. Use the order data to call shipments-create, then follow the standard label purchase flow.
3. After purchasing, call orders-get-packing-slip for a PDF packing slip.

Tracking