VX Agents

OpenAPI Marketplace · Commerce & Payments

Shippo Shipping Labels & Tracking

v1.0.0 · 16 endpoints · 0 connections · shared by vx.ai

An order is paid and needs to ship: check the address, compare USPS, UPS and FedEx rates for the parcel, buy the cheapest label, then track it by carrier and tracking number. Shippo test tokens let you try the whole flow without paying for postage.

Connect this API to an AI agent Browse all specs

What you can do with Shippo Shipping Labels & Tracking via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
POST /addresses createAddress Save an address (set validate=true to check it)
GET /addresses/{AddressId}/validate validateAddress Validate a saved address and get suggestions
POST /shipments createShipment Create a shipment and get rate quotes for it
GET /shipments/{ShipmentId} getShipment Get a shipment with its rates
GET /shipments/{ShipmentId}/rates listShipmentRates List the rate quotes for a shipment
GET /rates/{RateId} getRate Get one rate quote
POST /transactions buyShippingLabel Buy a shipping label for a rate
GET /transactions listShippingLabels List shipping labels you bought
GET /transactions/{TransactionId} getShippingLabel Get a label: status, tracking number and label URL
GET /tracks/{Carrier}/{TrackingNumber} getTrackingStatus Track a package by carrier and tracking number
GET /orders listOrders List orders imported from your store
GET /orders/{OrderId} getOrder Get one order with its items and address
GET /carrier_accounts listCarrierAccounts List the carrier accounts you can ship with
GET /user-parcel-templates listParcelTemplates List your saved box sizes (parcel templates)
POST /refunds refundShippingLabel Request a refund for an unused label
GET /refunds/{RefundId} getRefund Check the status of a label refund

Authentication

APIKeyHeader

API key — sent as the Authorization header

Shippo API token, sent as Authorization: ShippoToken <token>.

How to get a credential

  1. Sign up or log in at https://apps.goshippo.com.
  2. Open Settings > Advanced > API.
  3. Generate a token. shippo_test_... tokens create test labels for free; shippo_live_... tokens buy real postage charged to your Shippo billing method.
  4. Store the value as ShippoToken <token> (the word ShippoToken, a space, then the token).

Permissions used

Shippo tokens carry full account access; there are no per-scope tokens.

Token Operations
Test or live createAddress, validateAddress, createShipment, getShipment, listShipmentRates, getRate, getTrackingStatus, listOrders, getOrder, listCarrierAccounts, listParcelTemplates, listShippingLabels, getShippingLabel, getRefund
Live (charges money) buyShippingLabel, refundShippingLabel

Common errors

  • 401 Unauthorized: the token is wrong or the ShippoToken prefix is missing.
  • 403 Forbidden: the account cannot use that carrier or feature yet (e.g. billing not set up for live labels).
  • 400 Bad Request: missing or invalid address, parcel or rate fields; the response lists the field.
  • 429 Too Many Requests: rate limited. Wait a few seconds and retry; test tokens have lower limits.

Save it in VX Agents as an API key credential for this spec.

Usage guide

Setup

  • Credential: a Shippo API token stored as ShippoToken <token>. Start with a shippo_test_ token: test labels are free and not real.
  • Worth pinning: your sender address object_id (create it once with createAddress) and your usual box (from listParcelTemplates).

Ship an order

  1. Optional: listOrders / getOrder to get the recipient and items of a store order.
  2. createAddress with validate: true for the recipient, or validateAddress on a saved one. Look at validation_results.is_valid and its messages; fix the address with the user before going on.
  3. createShipment with address_from, address_to (objects or object_ids) and parcels (length, width, height, distance_unit, weight, mass_unit). Leave async false so the rates come back in the response.
  4. Compare the rates (provider, servicelevel.name, amount, currency, estimated_days). listShipmentRates or getRate re-reads them.
  5. Show the user the chosen rate and price. Only after they confirm, buyShippingLabel with rate = the rate object_id (and label_file_type, e.g. PDF_4x6).
  6. getShippingLabel until status is SUCCESS, then give the user label_url and tracking_number. If status is ERROR, read messages.
  7. getTrackingStatus with the carrier token (e.g. usps, ups, fedex) and the tracking number for updates.

Good to know

  • Ask before buyShippingLabel and refundShippingLabel: with a live token, buying a label charges your Shippo account.
  • Rates expire after a while. If buying fails because a rate is stale, run createShipment again.
  • refundShippingLabel takes transaction = the label object_id and only works for unused labels. Track progress with getRefund.
  • Weights and dimensions are strings ("2.5"). Times are ISO 8601 UTC. List calls page with page and results.
  • With a test token, tracking only works with Shippo's predefined test tracking numbers (see the Tracking tutorial).
  • Source: Shippo API reference (https://docs.goshippo.com/api-reference/overview), checked 2026-10-16.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Shippo Shipping Labels & Tracking” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs