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

# Cancel an order

> Request cancellation of a mail order; not guaranteed once the mail has been submitted

## Overview

Asks to cancel an order. Accepted (`202`) as a request: cancellation is not guaranteed once the mail has been submitted for printing. Read the [order](https://docs.oneshotagent.com/api-reference/physical-mail/order.md) to see whether it was canceled and refunded. Free.

An order not yet submitted is canceled at once. A submitted one is canceled only if the request reaches production before `cancel_before`, which is an estimate. A confirmed cancellation refunds the full amount, service fee included, as credits, once. Cancelling an order that is already `canceled` or `failed` returns the order unchanged.

## Authentication

`X-Agent-ID` plus a signed `x-agent-proof` with `scope: "write"`, 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)

No request body.

## Response

`202` with the order as it stands right after the request. Its fields are listed on [Get an order](https://docs.oneshotagent.com/api-reference/physical-mail/order.md#response). `cancellation_requested` is `true`. An order not yet submitted comes back `canceled` at once; a submitted one stays `accepted` until the request is confirmed, and `refunded_at` is set when the refund is credited.

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

```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.cancel("00000000-0000-4000-8000-000000000000");
console.log(order.order_status);
```

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

```json Accepted (202), submitted order 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": true,
  "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.