> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipping

> Read shipments, tracking and quoted rates from your connected shipping system

## Overview

Read-only tools on a connected shipping system ([Connections](/api-reference/connections/overview)): 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`

<ParamField body="connection_id" type="string" required>
  The connection to read.
</ParamField>

<ParamField body="limit" type="integer" default={25}>
  Shipments per page, 1 to 100.
</ParamField>

<ParamField body="cursor" type="string">
  The `next_cursor` of the previous page.
</ParamField>

<ParamField body="from" type="string">
  Shipments created on or after this day (`YYYY-MM-DD`).
</ParamField>

<ParamField body="to" type="string">
  Shipments created on or before this day (`YYYY-MM-DD`).
</ParamField>

<ParamField body="status" type="string">
  Only shipments in this status, as the system names it (for example `label_purchased`).
</ParamField>

<Snippet file="audit-context-params.mdx" />

### Response (200)

<ResponseField name="data.shipments" type="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`).
</ResponseField>

<ResponseField name="data.next_cursor" type="string">
  Send as `cursor` for the next page; null on the last page.
</ResponseField>

## Tracking

`POST /v1/tools/shipping/tracking`

<ParamField body="connection_id" type="string" required>
  The connection to read.
</ParamField>

<ParamField body="shipment_id" type="string">
  The shipment to track. Or send `carrier` and `tracking_number` instead.
</ParamField>

<ParamField body="carrier" type="string">
  The carrier code, with `tracking_number`.
</ParamField>

<ParamField body="tracking_number" type="string">
  The tracking number, with `carrier`.
</ParamField>

### Response (200)

<ResponseField name="data.status" type="string">
  `pre_transit`, `in_transit`, `delivered`, `exception` or `unknown`.
</ResponseField>

<ResponseField name="data.events" type="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`.
</ResponseField>

## Rates

`POST /v1/tools/shipping/rates`

<ParamField body="connection_id" type="string" required>
  The connection to read.
</ParamField>

<ParamField body="shipment_id" type="string" required>
  The existing shipment whose quoted rates to read.
</ParamField>

### Response (200)

<ResponseField name="data.rates" type="array">
  Each rate: `carrier`, `service`, `amount` (with surcharges), `currency`, `estimated_days` and `source`.
</ResponseField>

```json theme={null}
{
  "success": true,
  "data": {
    "rates": [
      { "carrier": "ups", "service": "ups_ground", "amount": 12, "currency": "USD", "estimated_days": 3, "source": { "system": "shipengine", "id": "se-rate-1" } }
    ]
  }
}
```

## Errors

| Status | Error | Meaning |
| - | - | - |
| 400 | `invalid_request` | The body is not valid. |
| 400 | `unsupported_for_system` | The system cannot serve this input (a foreign cursor). |
| 400 | `connection_wrong_system` | The connection is not on a shipping system. |
| 400 | `not_supported` | No label to track yet, or more labels (send a smaller `limit`) or rates than one read covers; a paid call is returned as account credit. |
| 404 | `connection_not_found` | No such connection for this agent. |
| 409 | `connection_expired`, `connection_revoked`, `connection_not_active` | Reconnect or start a new connection. |
| 503 | `not_configured` | The system is not available right now. |
| 503 | `rate_limited`, `system_unavailable` | The system is busy or did not answer; a paid call is returned as account credit. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.