# Change the amount of a payout that is still `awaiting_funds`

`PATCH /payouts/{id}` · Skerry · Paying out

Change the amount of a payout that is still `awaiting_funds`; once its funds have arrived it is refused with 409 `payout_not_amendable`. Needs an Idempotency-Key. A higher amount is checked as the payout was, for the difference: the freeze, risk rules, mandate limits, budget and approval; if it is held, send the same request again with `Skerry-Approval` once a person has approved it. A lower amount is not checked, and what was already counted against a limit stays counted. The stored record takes the new amount and the difference is booked in the payout's movement. `amount` is a decimal string in the payout's currency; `amount_minor` may be sent instead.

- Scope: payouts:write
- Moves money: yes
- Idempotency: required
- Untrusted: reference, external_ref, remittance, hold.reason

## Parameters

- `id` (path, required), string
- `Idempotency-Key` (header, required), string: A repeat with the same key and body returns the first answer instead of acting twice.

## Request body

`application/json`

```json
{
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "pattern": "^\\d{1,18}(\\.\\d{1,10})?$",
      "description": "The new amount, a decimal string in the payout's currency. Send this or `amount_minor`."
    },
    "amount_minor": {
      "type": "integer",
      "minimum": 1,
      "description": "The new amount in integer minor units of the payout's currency."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Check the request and report what would happen, without doing it."
    }
  }
}
```

## Responses

- `200`: Success.
- `202`: requires_approval — Not an error: the operation is held for a person. The body names the approval.
- `400`: price_below_minimum — The price is below the smallest single payment for a method (`detail.method`, `detail.minimum`), or has a part of a cent. Set `credit_only`, raise the price, or drop the method.
- `401`: dpop_invalid — The token is bound to a key and the DPoP proof was missing, wrong for this request, or already used.
- `402`: payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms.
- `403`: agent_payment_over_max — The merchant asks for more than `max_amount`. Nothing was signed. `detail.asked_minor` is the lowest price asked, in US cents.
- `404`: not_found — No such object in this project — including one that belongs to somebody else.
- `409`: token_not_issued — A delegated payment token could not be issued ready to use, for instance because the payer would have to act. Nothing was sent to the merchant.
- `429`: too_many_waiters — This key already has as many requests waiting (`?wait=`) as it may. Let one finish, or read without wait.
- `500`: internal_error — Ours. Quote the `request_id` and we can find the call.
- `502`: platform_error — A provider failed. Safe to retry with the same Idempotency-Key.
- `503`: oauth_unavailable — The authorisation server's keys could not be read, so tokens cannot be checked. API keys still work.

## Example

```sh
curl -X PATCH 'https://api.skerry.xyz/payouts/{id}' \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '"{ amount | amount_minor }"'
```