canonical: https://jentic.com/apis/goshippo.com/goshippo

# Goshippo Shippo external API

The Shippo external API provides multi-carrier shipping for e-commerce: address validation, parcel and shipment creation, rate quoting across 80+ carriers, label purchase, customs declarations, batch processing, manifests, and tracking. The 70-endpoint surface covers the full outbound logistics flow, with native support for carrier accounts, return labels, refunds, and pickup scheduling. Authentication uses an API key supplied via the Authorization header, scoped per Shippo account.

## For AI agents

Validate addresses, fetch live carrier rates, buy shipping labels, generate customs declarations, and track parcels across 80+ carriers via Shippo.

## Scope

Does not handle inventory management, payments, or warehouse robotics - use for shipping labels, rates, customs, and tracking only.

## Capabilities

- Validate and normalize a destination address before label purchase
- Quote rates across registered carrier accounts for a given parcel and route
- Purchase a shipping label from a chosen rate and download the PDF or PNG
- Generate customs declarations and items for international shipments
- Submit shipments in a batch and purchase the cheapest rate per shipment automatically
- Issue return labels tied to an original outbound shipment
- Track an in-transit parcel by carrier and tracking number

## Use cases

### Multi-Carrier Rate Shopping

Quote rates from every connected carrier for a given parcel and ship-to address, then purchase the cheapest or fastest option programmatically. Shippo normalizes pricing, transit time, and service codes across 80+ carriers so the merchant does not need separate USPS, UPS, FedEx, and DHL integrations. Address validation runs first to avoid label rejections.

Example prompt: POST /shipments with from, to, and parcel details, list rates, and POST /transactions with the lowest-priced rate object_id to purchase the label.

### International Shipping with Customs

Generate customs declarations and item lists, attach them to international shipments, and produce compliant labels and commercial invoices. The /customs/declarations and /customs/items endpoints capture HS codes, value, weight, and origin. Shippo bundles the documentation with the label PDF so warehouse staff print one file per parcel.

Example prompt: Create a customs declaration for shipment id abcd1234 with one item (HS code 6109.10, value $24, qty 2, origin US) and purchase the label that includes the commercial invoice.

### Self-Serve Returns Portal

Power a returns portal that generates a prepaid return label as soon as the shopper requests one. POST /shipments with the original outbound metadata flipped, fetch return-eligible rates, and purchase the chosen rate. Tracking on the return shipment feeds the warehouse so refunds can be issued on receipt rather than scan-in.

Example prompt: Create a return shipment from the customer address back to the warehouse, purchase the cheapest USPS rate, and email the resulting label PDF to the shopper.

### AI Agent Fulfillment Automation

An AI agent ingests new orders, validates addresses, batches them by service level, purchases labels, and posts tracking back to the e-commerce platform. Through Jentic, the agent finds the right Shippo operation by intent and uses a vault-stored API key, never exposing the raw token to the model.

Example prompt: For order 5544, validate the ship-to address via /addresses/{id}/validate, purchase a USPS Priority label via /transactions, and update the order with the tracking number.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /addresses | Create an address |
| POST | /addresses/{AddressId}/validate | Validate an address |
| POST | /shipments | Create a shipment and get rates |
| POST | /transactions | Purchase a label from a rate |
| POST | /customs/declarations | Create a customs declaration |
| POST | /batches | Create a batch of shipments |
| POST | /batches/{BatchId}/purchase | Purchase all shipments in a batch |
| POST | /carrier_accounts | Connect a carrier account |

## Key resources

- **Addresses** — Create and validate addresses for senders and recipients
- **Shipments and Rates** — Build shipments and quote multi-carrier rates
- **Transactions** — Purchase labels from a chosen rate object
- **Customs** — Customs declarations and item lists for international shipping
- **Batches** — Bulk shipment processing and automated cheapest-rate purchase
- **Carrier Accounts** — Connect, configure, and manage carrier accounts
- **Tracks and Manifests** — Tracking lookups and end-of-day manifest creation

## Why Jentic

- **Setup:** Wiring the Shippo external API by hand means provisioning the API token, attaching it in the Authorization header on every call, and matching address, shipment, and transaction paths against the api.goshippo.com host. Through Jentic you install once, import the Shippo external API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Shippo external API puts resource ids in the URL path (/batches/{BatchId}/purchase), so a rule can pin your agent to one batch or address: it can validate or purchase that resource and nothing else. You choose the operations it may call, so creating carrier accounts or buying arbitrary labels is not included unless you add them.
- **Credential handling:** Your Shippo API token is stored once, encrypted, by your own Jentic One instance and injected at execution time in the Authorization header. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'buy the cheapest shipping label' or 'validate a shipping address', and Jentic returns the matching Shippo operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ShipStation** — Multi-carrier shipping platform with merchant order management
- **Stamps.com** — USPS-focused shipping platform for SMB volume
- **Stripe** — Payment processor that pairs with shipping for end-to-end commerce

## FAQ

### What authentication does the Shippo API use?

An API key sent in the Authorization header with the value 'ShippoToken <YOUR_TOKEN>'. Tokens come from the Shippo dashboard and can be live or test. Through Jentic, the token is held in the encrypted vault and injected into the request at execution time.

### How do I buy a shipping label through the Shippo API?

POST /shipments with from, to, and parcel details to receive a list of rate objects. Pick a rate by object_id, then POST /transactions with that rate to purchase the label. The transaction response includes the label_url for download as PDF, PNG, or ZPL.

### Can I generate customs declarations with the Shippo API?

Yes. POST /customs/declarations with declaration metadata, attach a list of /customs/items objects (HS code, description, value, weight, origin), and reference the declaration object_id when creating an international shipment. Shippo bundles the commercial invoice with the label.

### What carriers does Shippo support?

Shippo connects to 80+ carriers including USPS, UPS, FedEx, DHL Express, Canada Post, Royal Mail, Australia Post, and many regional carriers. Use POST /carrier_accounts to attach your carrier credentials, or use the included Shippo USPS account.

### How do I integrate the Shippo API with an AI agent through Jentic?

Run pip install jentic, search 'buy a shipping label' to find POST /transactions, load its schema, and execute. Jentic injects the ShippoToken header from the vault. Get started with Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the Shippo API?

Yes. Because you run Jentic One yourself, your own rules decide which Shippo operations and credentials the agent may use, so you can allow it to validate an address or purchase a label while keeping everything else off limits. Shippo puts resource ids in the URL path, such as /batches/{BatchId}/purchase, so a rule can pin the agent to one specific batch or address and let it act only on that resource. Higher-impact calls like connecting carrier accounts via /carrier_accounts or buying arbitrary labels through /transactions stay excluded unless you explicitly add them.