Shippo User Management API Guide

Auth method: API Token (Bearer token passed in Authorization header)

Setup steps

1. Log in to the Shippo dashboard at app.goshippo.com.
2. Navigate to Settings > API.
3. Generate or copy your API token (test or live).
4. Pass the token in the Authorization header as: 'Authorization: ShippoToken '.

User object field mapping is not yet verified for this app.

List Shipments

• Method: GET
• URL: https://api.goshippo.com/shipments/
• Watch out for: Shippo uses 'results' (not 'limit') for page size and 'page' for pagination; max results per page is 100.

Request example

GET /shipments/?results=5&page=1
Authorization: ShippoToken <token>

Response example

{
  "count": 42,
  "next": "https://api.goshippo.com/shipments/?page=2",
  "results": [{"object_id": "abc123", ...}]
}

Create Shipment

• Method: POST
• URL: https://api.goshippo.com/shipments/
• Watch out for: Setting async=false blocks until rates are returned; async=true returns immediately and rates must be polled.

Request example

POST /shipments/
Authorization: ShippoToken <token>
{
  "address_from": "<address_id>",
  "address_to": "<address_id>",
  "parcels": ["<parcel_id>"],
  "async": false
}

Response example

{
  "object_id": "shipment_abc",
  "status": "SUCCESS",
  "rates": [...]
}

Create Address

• Method: POST
• URL: https://api.goshippo.com/addresses/
• Watch out for: Address validation is a separate call (POST /addresses//validate/); creation does not auto-validate.

Request example

POST /addresses/
Authorization: ShippoToken <token>
{
  "name": "Jane Doe",
  "street1": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94105",
  "country": "US"
}

Response example

{
  "object_id": "addr_xyz",
  "is_complete": true,
  "validation_results": {}
}

Purchase Label (Transaction)

• Method: POST
• URL: https://api.goshippo.com/transactions/
• Watch out for: Transactions consume label credits or trigger billing; test tokens generate test labels that are not mailed.

Request example

POST /transactions/
Authorization: ShippoToken <token>
{
  "rate": "<rate_id>",
  "label_file_type": "PDF",
  "async": false
}

Response example

{
  "object_id": "txn_abc",
  "status": "SUCCESS",
  "label_url": "https://...",
  "tracking_number": "9400..."
}

Get Transaction

• Method: GET
• URL: https://api.goshippo.com/transactions/{transaction_id}/
• Watch out for: Use this endpoint to poll status when async=true was used during transaction creation.

Request example

GET /transactions/txn_abc/
Authorization: ShippoToken <token>

Response example

{
  "object_id": "txn_abc",
  "status": "SUCCESS",
  "label_url": "https://..."
}

List Carrier Accounts

• Method: GET
• URL: https://api.goshippo.com/carrier_accounts/
• Watch out for: Carrier account management (adding/removing carriers) is primarily done via the Shippo dashboard, not the API.

Request example

GET /carrier_accounts/
Authorization: ShippoToken <token>

Response example

{
  "count": 2,
  "results": [{"object_id": "ca_abc", "carrier": "usps", "active": true}]
}

Track Shipment

• Method: GET
• URL: https://api.goshippo.com/tracks/{carrier}/{tracking_number}/
• Watch out for: Tracking data availability depends on carrier; not all carriers provide real-time updates.

Request example

GET /tracks/usps/9400111899223397846246/
Authorization: ShippoToken <token>

Response example

{
  "tracking_status": {"status": "DELIVERED"},
  "tracking_history": [...]
}

Register Tracking Webhook

• Method: POST
• URL: https://api.goshippo.com/tracks/
• Watch out for: This registers a tracking number for webhook push updates; webhook URL must be configured separately in the Shippo dashboard.

Request example

POST /tracks/
Authorization: ShippoToken <token>
{
  "carrier": "usps",
  "tracking_number": "9400..."
}

Response example

{
  "carrier": "usps",
  "tracking_number": "9400...",
  "tracking_status": {"status": "UNKNOWN"}
}

• Rate limits: Shippo enforces rate limits on API requests. The official docs note limits exist but do not publicly specify exact request-per-minute figures per plan tier.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: Rate limit details are not publicly documented. Contact Shippo support for enterprise-level rate limit information.

• Pagination method: cursor

• Default page size: 5

• Max page size: 100

• Pagination pointer: page, results (results controls page size; page controls offset-style page number)

• Webhooks available: Yes

• Webhook notes: Shippo supports webhooks for tracking and transaction events. Webhook URLs are configured in the Shippo dashboard under Settings > Webhooks. Shippo sends POST requests to the configured URL when events occur.

• Alternative event strategy: Poll GET /tracks/{carrier}/{tracking_number}/ or GET /transactions/{id}/ for status updates if webhooks are not configured.

• Webhook events: track_updated, transaction_created

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• Shippo does not publicly document SCIM support.
• No SSO or SCIM provisioning is listed in official Shippo documentation or pricing pages.
• User management (team members, roles) is handled exclusively through the Shippo dashboard UI.

The core label-purchase flow requires four sequential API calls: POST /addresses/ twice (sender and recipient), POST /parcels/ with dimensions and weight, POST /shipments/ with async=false to retrieve rated options synchronously, then POST /transactions/ with the selected rate_id to purchase.

Using async=true on either shipments or transactions returns immediately but requires polling the respective GET endpoint until status reaches SUCCESS - async=false is simpler but can time out on slower carriers.

Address validation is a discrete step: POST /addresses/ creates the object, but validation requires a separate POST to /addresses//validate/.

Skipping validation before purchasing a label is a common source of downstream carrier rejections.

For tracking automation, register a shipment via POST /tracks/ with carrier and tracking_number to receive track_updated webhook pushes.

The webhook destination URL must be pre-configured in the Shippo dashboard under Settings > Webhooks - there is no API endpoint to register webhook URLs programmatically.

If webhooks are not configured, poll GET /tracks/{carrier}/{tracking_number}/ directly.

Purchase and retrieve a shipping label

1. POST /addresses/ to create sender and recipient address objects.
2. POST /parcels/ to create a parcel object with dimensions and weight.
3. POST /shipments/ with address_from, address_to, parcels, and async=false to retrieve available rates.
4. Select a rate object_id from the shipment response.
5. POST /transactions/ with the chosen rate_id and async=false to purchase the label.
6. Retrieve label_url and tracking_number from the transaction response.

Watch out for: Using async=true on shipments or transactions requires polling until status is SUCCESS; async=false is simpler but may time out for some carriers.

Set up tracking webhook for a shipment

1. Configure a publicly accessible webhook URL in the Shippo dashboard under Settings > Webhooks.
2. POST /tracks/ with carrier and tracking_number to register the shipment for push updates.
3. Shippo will POST track_updated events to your webhook URL as the shipment status changes.
4. Validate incoming webhook payloads using the shared secret provided in the dashboard.

Watch out for: Webhook registration via POST /tracks/ only works if a webhook URL is already configured in the dashboard; there is no API endpoint to register webhook URLs programmatically.

Retrieve rates for a shipment without purchasing

1. POST /addresses/ for from and to addresses.
2. POST /parcels/ with weight, length, width, height, and distance_unit.
3. POST /shipments/ with async=false to get rates immediately.
4. Inspect the 'rates' array in the response to compare carriers and prices without committing to a purchase.

Watch out for: Rates are only valid for a limited time; do not cache rate object_ids for extended periods before purchasing.

The most significant integration trap is assuming Shippo exposes a user API because it has a robust REST surface. It does not.

Any identity graph built to automate provisioning across your SaaS stack - including an MCP server with 60+ deep IT/identity integrations - will hit a hard wall with Shippo: there are no user endpoints to call, no SCIM schema to map, and no token model that scopes to individual users.

The API token is account-level, meaning any service using it has the same access footprint as the account owner, with no delegation boundary.

A secondary trap is the async parameter behavior. Developers defaulting to async=true for perceived performance gains must implement a polling loop with appropriate backoff; missing a SUCCESS status check before downstream processing will result in label purchases that appear to succeed but have not completed.

Rate limit opacity compounds this: because Shippo does not expose rate-limit headers or document per-plan thresholds, burst workloads risk silent throttling with no programmatic signal to back off.