Update a payout

PATCH/api/v2/payouts/{id}

Allowed while status is created. An omitted field is unchanged; recipient is replaced as a whole. Needs payouts:write.

Path Parameters

id*string

The payout id (payout_…) or your customId.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

customId?|

Your own key for the payout. null removes it.

description?maxLength(5000)

What the payout is for. Shown to the recipient. Can span several lines: a literal \n becomes a line break, and consecutive line breaks collapse into one.

Length1 <= length <= 5000

amount?MoneyInput

a string matching the pattern ^\d+(.\d{1,2})?$

Match^\d+(\.\d{1,2})?$

currency?string

Currency of amount and of the invoices.

Value in

"USD"
"EUR"
"CHF"
"GBP"

recipient?|

Who is paid, discriminated on type: an email recipient claims by link, a counterparty can also be paid directly.

tags?array<>

Your labels for the payout. Filter the list with ?tag=. Up to 20 tags of 1 to 100 characters.

Itemsitems <= 20

availableOn?|

A future UTC day before which the payout cannot be claimed or paid. null removes it.

locked?boolean

true locks the payout. A locked payout refuses every later PATCH.

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v2/payouts/payout_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e" \  -H "Content-Type: application/json" \  -d '{}'

{  "object": "payout",  "id": "payout_0e4ba886-0bfe-4b6a-ae2e-d6d9d135dd1e",  "customId": "campaign-42",  "description": "string",  "amount": "100.00",  "currency": "USD",  "recipient": {    "type": "email",    "email": "jane@example.com",    "phone": "string"  },  "status": "created",  "locked": true,  "availableOn": "2026-10-01",  "expiresAt": "2026-09-24T10:00:00.000Z",  "tags": [    "string"  ],  "paymentMethod": {    "type": "crypto",    "asset": "string",    "currency": "EUR"  },  "senderInvoiceUrl": "string",  "recipientInvoiceUrl": "string",  "recipientInvoiceSource": "self_billing",  "failureCode": "account_closed",  "failureReason": "string",  "approvedAt": "2026-09-24T10:00:00.000Z",  "claimLinkSentAt": "2026-09-24T10:00:00.000Z",  "requestedAt": "2026-09-24T10:00:00.000Z",  "completedAt": "2026-09-24T10:00:00.000Z",  "createdAt": "2026-09-24T10:00:00.000Z",  "updatedAt": "2026-09-24T10:00:00.000Z"}

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`