> ## 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.

# Get an order

> Read a mail order: its status, payment, delivery events and signed receipt

## Overview

Returns one order. Free. Delivery events are postal observations, never evidence the mail was read.

## Authentication

`X-Agent-ID` plus a signed `x-agent-proof` with `scope: "read"`, or an access token. See [proof authentication](https://docs.oneshotagent.com/sdk/overview.md#read-authentication). 60 requests a minute per agent.

## Path Parameters

**id** `string` *required*

Order ID from [Send](https://docs.oneshotagent.com/api-reference/physical-mail/send.md) or [Recover](https://docs.oneshotagent.com/api-reference/physical-mail/recover.md)

## Response

**order\_id** `string`

Order ID

**quote\_id** `string`

The quote this order bought

**order\_status** `string`

`pending`, `submitting`, `accepted`, `canceled`, `failed`, or `needs_reconciliation` (acceptance unconfirmed)

**payment\_status** `string`

`pending`, `leased`, `settled`, `failed` or `unknown`

**fulfillment\_status** `string`

`pending`, `accepted`, `mailed`, `in_transit`, `in_local_area`, `processed_for_delivery`, `delivered`, `returned_to_sender`, `canceled` or `render_failed`

**receipt\_id** `string`

Receipt ID

**signed\_receipt** `object | null`

The signed receipt. Null while `order_status` is `pending`, `submitting` or `needs_reconciliation`; signed once it reaches `accepted`, `canceled` or `failed`. Independent of `fulfillment_status`: the receipt does not wait for delivery.

**total\_usdc** `string`

Amount charged, as a decimal string

**idempotency\_key** `string`

The `Idempotency-Key` the send carried

**events** `array`

Postal events, oldest first. Each has `event_id`, `event_type` and `occurred_at`.

**cancellation\_requested** `boolean`

`true` after [Cancel](https://docs.oneshotagent.com/api-reference/physical-mail/cancel.md) was called

**cancellation\_error** `string | null`

Why a requested cancellation did not take effect

**cancel\_before** `string | null`

Estimated last moment a cancellation can still take effect

**refunded\_at** `string | null`

When the order was refunded as credits

**delivery\_proves\_readership** `boolean`

Always `false`

```bash cURL theme={null}
curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/orders/00000000-0000-4000-8000-000000000000" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -H "x-agent-proof: <base64 signed proof, scope=read>"
```

```typescript SDK theme={null}
import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

const order = await agent.physicalMail.getOrder("00000000-0000-4000-8000-000000000000");
console.log(order.order_status, order.fulfillment_status);
```

```python Python theme={null}
order = client.physical_mail.get_order("00000000-0000-4000-8000-000000000000")
print(order["order_status"], order["fulfillment_status"])
```

```json Response theme={null}
{
  "order_id": "00000000-0000-4000-8000-000000000000",
  "quote_id": "00000000-0000-4000-8000-000000000000",
  "order_status": "accepted",
  "payment_status": "settled",
  "fulfillment_status": "in_transit",
  "receipt_id": "rcpt_...",
  "signed_receipt": { "receiptId": "rcpt_...", "signature": "<signature>" },
  "total_usdc": "<the quote's total_usdc>",
  "idempotency_key": "thank-you-2026-q3-jane-doe",
  "events": [
    { "event_id": "evt_...", "event_type": "letter.mailed", "occurred_at": "2026-10-30T15:00:00.000Z" },
    { "event_id": "evt_...", "event_type": "letter.in_transit", "occurred_at": "2026-10-31T09:00:00.000Z" }
  ],
  "cancellation_requested": false,
  "cancellation_error": null,
  "cancel_before": "2026-10-30T14:00:00.000Z",
  "refunded_at": null,
  "delivery_proves_readership": false
}
```

```json Not Found (404) theme={null}
{
  "error": "order_not_found"
}
```

## Notes

* Returns only your agent's orders.
* A confirmed cancellation or a failure before production refunds the full amount as credits, once. Returned mail is not refunded.


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