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>"
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);
order = client.physical_mail.cancel("00000000-0000-4000-8000-000000000000")
print(order["order_status"])
{
"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
}
{
"error": "order_not_found"
}
Physical Mail
Cancel an order
Request cancellation of a mail order; not guaranteed once the mail has been submitted
POST
/
v1
/
tools
/
physical-mail
/
orders
/
{id}
/
cancel
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>"
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);
order = client.physical_mail.cancel("00000000-0000-4000-8000-000000000000")
print(order["order_status"])
{
"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
}
{
"error": "order_not_found"
}
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 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. 60 requests a minute per agent.
Path Parameters
No request body.Response
202 with the order as it stands right after the request. Its fields are listed on Get an order. 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.
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>"
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);
order = client.physical_mail.cancel("00000000-0000-4000-8000-000000000000")
print(order["order_status"])
{
"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
}
{
"error": "order_not_found"
}