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

# Recover an order

> Find the order a send created, by its Idempotency-Key

## Overview

Finds the order created by a [Send](https://docs.oneshotagent.com/api-reference/physical-mail/send.md) that carried this `Idempotency-Key`. Use it after a timeout or a lost response instead of sending again. Free.

`404 order_not_found` means no send with that key reached OneShot, so it is safe to send with the same key.

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

## Query Parameters

**key** `string` *required*

The `Idempotency-Key` of the send (1 to 255 characters of `[A-Za-z0-9_.:-]`)

## Response

The order. Its fields are listed on [Get an order](https://docs.oneshotagent.com/api-reference/physical-mail/order.md#response).

```bash cURL theme={null}
curl -X GET "https://win.oneshotagent.com/v1/tools/physical-mail/orders/recover?key=thank-you-2026-q3-jane-doe" \
  -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.recover("thank-you-2026-q3-jane-doe");
console.log(order.order_id);
```

```python Python theme={null}
order = client.physical_mail.recover("thank-you-2026-q3-jane-doe")
print(order["order_id"])
```

```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": "accepted",
  "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": [],
  "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"
}
```


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