Shippo Agent Skill

Shippo

Purpose

Ship through many carriers (USPS, UPS, FedEx, DHL and others) with one API: get rates for a shipment; buy a printable postage label; track a parcel; refund unused labels. Reach for this when the user needs to price or purchase shipping for a package.

Tooling

All commands go through bin/shippo.py:

bin/shippo.py auth                                    # verify the API token
bin/shippo.py rates --file shipment.json              # rates for a shipment (no label bought)
bin/shippo.py get-shipment --id SHIPMENT_ID           # retrieve a shipment
bin/shippo.py track --carrier usps --number 940011... # tracking status
bin/shippo.py buy --shipment-id SHIPMENT_ID --rate-id RATE_ID \  # buy a label from a rate
    --confirm "buy 12.40 USD USPS Priority label for rate RATE_ID"  # confirmation required
bin/shippo.py buy --shipment-id SHIPMENT_ID --rate-id RATE_ID \
    --live \                                                        # production key path: --live AND --confirm
    --confirm "buy 12.40 USD USPS Priority label for rate RATE_ID"
bin/shippo.py refund --transaction-id TXN_ID          # refund/void an unused label

shipment.json holds a Shippo shipment object: address_from, address_to, and parcels. rates never buys anything; only buy spends money.

Auth

• Provider id: shippo (credential is collected as custom.shippo)
• Collection: API token via the secure credential flow (credentials.request_api_access); issued in the Shippo dashboard
• Auth scheme: token in the Authorization header (raw token, no Bearer prefix); this is the documented scheme and the credential config places it there
• Allowed hosts: api.goshippo.com
• Status check: bin/shippo.py auth
• Honesty note: the research dossier flagged the exact header name as a build-time open item; the dossier's own documented scheme is the raw token in Authorization, which is what this connector implements. Re-verify against docs.goshippo.com before relying on it in production.

Operating Rules

• Test keys are the default path. Test keys generate free test labels marked was_test; nothing is billed. Use them for every dry run.
• Production label purchase is a HIGH actuation: POST /transactions buys real postage immediately, the account is billed, and the label authorizes physical transport of the parcel. The CLI enforces the gate: the buy command resolves the rate from the shipment, echoes the exact confirmation string (carrier, service, amount, rate id), and refuses to call the purchase endpoint until --confirm matches that string exactly. Passing --live is additionally required when the stored key is a production key; it is your explicit acknowledgment that real money will move.
• Always show the user the rate details (carrier, service, price, delivery estimate) before asking them to confirm a purchase.
• Refunds: a label can only be refunded/voided within carrier-specific windows and only if unused. Once the parcel is inducted into the carrier network, the postage is spent and cannot come back.
• Rate limits are plan-based. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/shippo.py). Do not print, log, or transmit the token value.

Files

• SKILL.md
• bin/shippo.py

Maturity

Draft: written from Shippo's public API docs; not yet live-tested end-to-end.