Worlds / Logistics

Shippo API

A local Shippo with addresses, shipments, rates, label transactions, manifests and tracking. Test the fulfillment agent that rates, buys labels, voids mistakes and watches tracking.

Base path: /
Auth: API token via Authorization: ShippoToken, the world key
Endpoints: 16
Status: Active today

This reference previews the surface the Shippo world serves in the closed beta. Paths mirror the public Shippo API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_SHIPPO_URL`	This world's origin followed by `/`
`WORLDS_API_KEY`	The world key, accepted wherever Shippo expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · shippo

import { Shippo } from "shippo";

const shippo = new Shippo({
  apiKeyHeader: process.env.WORLDS_API_KEY,
  serverURL: process.env.WORLDS_SHIPPO_URL,
});

const shipment = await shippo.shipments.create({
  addressFrom: { name: "Sparta", street1: "215 Clayton St", city: "San Francisco", state: "CA", zip: "94117", country: "US" },
  addressTo: { name: "Ada Lee", street1: "965 Mission St", city: "San Francisco", state: "CA", zip: "94103", country: "US" },
  parcels: [{ length: "10", width: "8", height: "4", distanceUnit: "in", weight: "2", massUnit: "lb" }],
});

API reference

16 of 16

Addresses

Create and validate addresses.

POST/addressesCreate an address
GET/addresses/{AddressId}Retrieve an address
GET/addresses/{AddressId}/validateValidate an address
GET/addressesList addresses

Fields · 6

`object_id`	string	Address id
`name`	string	Recipient name
`street1`	string	Street line 1
`city`	string	City
`zip`	string	Postal code
`is_complete`	boolean	Has all required fields

Shipments

A shipment returns rates from each carrier.

POST/shipmentsCreate a shipment
GET/shipments/{ShipmentId}Retrieve a shipment
GET/shipmentsList shipments
GET/shipments/{ShipmentId}/rates/{CurrencyCode}Get rates in a currency

Fields · 6

`object_id`	string	Shipment id
`address_from`	object	Origin
`address_to`	object	Destination
`parcels`	object[]	Parcel dimensions and weight
`rates`	object[]	Carrier rates
`status`	string	WAITING, QUEUED, SUCCESS, ERROR

Transactions

Purchased labels.

POST/transactionsPurchase a label
GET/transactions/{TransactionId}Retrieve a label
GET/transactionsList labels

Fields · 5

`object_id`	string	Transaction id
`rate`	string	Rate id purchased
`status`	string	QUEUED, SUCCESS, ERROR, REFUNDED
`tracking_number`	string	Carrier tracking number
`label_url`	string	Label PDF url

Tracks

Tracking status for a parcel.

GET/tracks/{Carrier}/{TrackingNumber}Get tracking status
POST/tracksRegister a tracking webhook

Fields · 5

`tracking_number`	string	Tracking number
`carrier`	string	Carrier token
`tracking_status`	object	Latest status and location
`tracking_history`	object[]	Scan history
`eta`	datetime	Estimated delivery

Refunds

Refund unused labels.

POST/refundsRequest a refund
GET/refunds/{RefundId}Retrieve a refund
GET/refundsList refunds

Fields · 3

`object_id`	string	Refund id
`transaction`	string	Label transaction id
`status`	string	QUEUED, PENDING, SUCCESS, ERROR

Test workflow

Prepare. Select the Shippo setup for your workflow and review its starting records, including addresses, shipments, transactions.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Order #1041 has exactly one label
Order #1042 refund requested, order was canceled
Order #1043 label not refunded, it is in transit
Every USPS label from today is on the manifest
No order shipped slower than its promised service

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Shippo
version: 2
connector: shippo
seed: shippo-starter
mode: isolated
policy: >
  Ship today's orders. Buy one label per order at the cheapest rate that meets
  the promised delivery, refund labels for canceled orders only if not yet
  scanned, and manifest every USPS label.
tasks:
  - id: buy-the-cheapest-qualifying-label-for-each-order
    prompt: Buy the cheapest qualifying label for each order
  - id: request-refunds-on-labels-that-were-never-used
    prompt: Request refunds on labels that were never used
  - id: create-the-end-of-day-manifest-for-each-carrier
    prompt: Create the end of day manifest for each carrier
expected:
  - "Order #1041 has exactly one label"
  - "Order #1042 refund requested, order was canceled"
  - "Order #1043 label not refunded, it is in transit"
  - Every USPS label from today is on the manifest
  - No order shipped slower than its promised service
scenarios:
  - rate-expired
  - label-failed
  - invalid-address

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-expired`	Buying a label with an old rate object returns an error
`label-failed`	The transaction comes back with status ERROR and carrier messages
`invalid-address`	Address validation returns is_valid false
`rate-limited`	Label purchases return 429
`tracking-webhook-twice`	track_updated is delivered two times

Starting data

Start each run from the same records and relationships. The overview below describes the Shippo starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
shipments	50 orders with parcels and addresses
rates	USPS, UPS and FedEx rates per shipment
transactions	30 labels across SUCCESS, QUEUED and ERROR
tracks	Tracking across PRE_TRANSIT, TRANSIT, DELIVERED and RETURNED
manifests	Yesterday's USPS manifest

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Addresses records

Addresses

Create and validate addresses.

Field	Type	Meaning / relationship
`object_id`	string	Address id
`name`	string	Recipient name
`street1`	string	Street line 1
`city`	string	City
`zip`	string	Postal code
`is_complete`	boolean	Has all required fields

json · illustrative record shape

{
  "object_id": "<Address id>",
  "name": "<Recipient name>",
  "street1": "<Street line 1>",
  "city": "<City>",
  "zip": "<Postal code>",
  "is_complete": false
}

See addresses operations

Shipments records

Shipments

A shipment returns rates from each carrier.

Field	Type	Meaning / relationship
`object_id`	string	Shipment id
`address_from`	object	Origin
`address_to`	object	Destination
`parcels`	object[]	Parcel dimensions and weight
`rates`	object[]	Carrier rates
`status`	string	WAITING, QUEUED, SUCCESS, ERROR

json · illustrative record shape

{
  "object_id": "<Shipment id>",
  "address_from": {},
  "address_to": {},
  "parcels": [],
  "rates": [],
  "status": "<WAITING, QUEUED, SUCCESS, ERROR>"
}

See shipments operations

Transactions records

Transactions

Purchased labels.

Field	Type	Meaning / relationship
`object_id`	string	Transaction id
`rate`	string	Rate id purchased
`status`	string	QUEUED, SUCCESS, ERROR, REFUNDED
`tracking_number`	string	Carrier tracking number
`label_url`	string	Label PDF url

json · illustrative record shape

{
  "object_id": "<Transaction id>",
  "rate": "<Rate id purchased>",
  "status": "<QUEUED, SUCCESS, ERROR, REFUNDED>",
  "tracking_number": "<Carrier tracking number>",
  "label_url": "<Label PDF url>"
}

See transactions operations

Tracks records

Tracks

Tracking status for a parcel.

Field	Type	Meaning / relationship
`tracking_number`	string	Tracking number
`carrier`	string	Carrier token
`tracking_status`	object	Latest status and location
`tracking_history`	object[]	Scan history
`eta`	datetime	Estimated delivery

json · illustrative record shape

{
  "tracking_number": "<Tracking number>",
  "carrier": "<Carrier token>",
  "tracking_status": {},
  "tracking_history": [],
  "eta": "<Estimated delivery>"
}

See tracks operations

Refunds records

Refunds

Refund unused labels.

Field	Type	Meaning / relationship
`object_id`	string	Refund id
`transaction`	string	Label transaction id
`status`	string	QUEUED, PENDING, SUCCESS, ERROR

json · illustrative record shape

{
  "object_id": "<Refund id>",
  "transaction": "<Label transaction id>",
  "status": "<QUEUED, PENDING, SUCCESS, ERROR>"
}

See refunds operations

See the Shippo world in the catalog