---
title: "Propose a refund"
method: POST
path: "/agent/orders/{orderId}/refund"
tags: ["Checkout"]
---

# Propose a refund

`POST /agent/orders/{orderId}/refund`

## Request

- Base URL: `https://api.trusteed.xyz/api/v1`
- URL: `https://api.trusteed.xyz/api/v1/agent/orders/{orderId}/refund`
- Auth: API key in header `X-Agent-Api-Key`

Propose a refund for a PayPal order (status PENDING_APPROVAL) — requires human merchant approval via the dashboard. The calling agent key must hold a non-blocked merchant allowlist binding for the order's store.

## Path parameters

- `orderId` string, required

## Request body

- ProposeRefundRequest
  - `amount` integer: Cents. Omit for a full refund.
  - `reason` string

## Response `201`

Refund request created — awaiting merchant approval

## Other responses

- `400`: Invalid order ID or refund request
- `404`: Order not found (including cross-merchant allowlist mismatch)

---

[API](https://skmtc.dev/trusteed/apis/trusteed-api.md) · [All operations](https://skmtc.dev/trusteed/apis/trusteed-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trusteed/apis/trusteed-api/revisions/14ce607accce?raw)