Skip to main content
POST
Shipping

Overview

Read-only tools on a connected shipping system (Connections): ShipEngine or Shippo. Nothing is bought, quoted, created or cancelled; nothing fetched is kept.
  • POST /v1/tools/shipping/shipments: shipments and labels.
  • POST /v1/tools/shipping/tracking: one shipment’s tracking.
  • POST /v1/tools/shipping/rates: rates already quoted on a shipment.
All take connection_id: list your connections (GET /v1/connections) and pick by system and account_label. No answer holds a street line or a recipient’s name. Shippo: from, to and status filter each page, so a page can hold fewer than limit shipments.

Authentication

Requires x402 payment in the payment-signature header. Refusals for the body, the connection or an unavailable system come before payment.

Shipments

POST /v1/tools/shipping/shipments
string
required
The connection to read.
integer
default:25
Shipments per page, 1 to 100.
string
The next_cursor of the previous page.
string
Shipments created on or after this day (YYYY-MM-DD).
string
Shipments created on or before this day (YYYY-MM-DD).
string
Only shipments in this status, as the system names it (for example label_purchased).

Response (200)

array
Each shipment: id, created_at, carrier, service, tracking_number, status, from and to (city, region, country), label_cost (amount, currency, or null without a label) and source (system, id).
string
Send as cursor for the next page; null on the last page.

Tracking

POST /v1/tools/shipping/tracking
string
required
The connection to read.
string
The shipment to track. Or send carrier and tracking_number instead.
string
The carrier code, with tracking_number.
string
The tracking number, with carrier.

Response (200)

string
pre_transit, in_transit, delivered, exception or unknown.
array
Each event: at, status, place (city, region, country) and description (the carrier’s text; a signer’s name reads “the recipient”). Also eta and source.

Rates

POST /v1/tools/shipping/rates
string
required
The connection to read.
string
required
The existing shipment whose quoted rates to read.

Response (200)

array
Each rate: carrier, service, amount (with surcharges), currency, estimated_days and source.

Errors