---
title: "Create or update a payout"
method: POST
path: "/v1/platform/businesses/{business_id}/payouts/"
tags: ["Payouts"]
---

# Create or update a payout

`POST /v1/platform/businesses/{business_id}/payouts/`

## Request

- Base URL: `https://docs.thredfi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.thredfi.com/v1/platform/businesses/{business_id}/payouts/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP basic
  - HTTP bearer
  - HTTP bearer

Create a new payout or update an existing one via external_id. Partners send completed processor settlements (Stripe, Adyen, etc.) with associated invoice payments and refund payments. Returns 201 for new payouts, 200 for updates. Updates are blocked if payout is already reconciled to a bank transaction.

## Path parameters

- `business_id` string, uuid, required

## Request body

- PayoutCreateRequest: Serializer for creating or updating payouts All amounts in cents (integers)
  - `external_id` string, required: Partner's unique payout ID (idempotency key)
  - `processor` 'stripe' | 'paypal' | 'square' | 'adyen' | 'worldpay' | 'sage_pay' | 'klarna' | 'other', required: Payment processor (stripe, adyen, paypal, etc.) * `stripe` - Stripe * `paypal` - PayPal * `square` - Square * `adyen` - Adyen * `worldpay` - Worldpay * `sage_pay` - Sage Pay * `klarna` - Klarna * `other` - Other
  - `processor_payout_id` string: Processor's payout ID reference
  - `paid_out_amount_cents` integer, required: Net payout amount in cents (can be negative if refunds exceed payments)
  - `fee_cents` integer, required: Processor fee charged in cents (must be >= 0)
  - `additional_refunds_amount_cents` integer: Additional refunds not tied to specific RefundPayment records in cents
  - `currency` 'EUR' | 'GBP' | 'USD' | 'SEK' | 'NOK' | 'DKK' | 'ISK' | 'MYR' | 'SGD', required: Payout currency (ISO 4217) * `EUR` - EUR * `GBP` - GBP * `USD` - USD * `SEK` - SEK * `NOK` - NOK * `DKK` - DKK * `ISK` - ISK * `MYR` - MYR * `SGD` - SGD
  - `status` 'pending' | 'processing' | 'paid' | 'failed' | 'cancelled', required: Payout status (must be 'paid') * `pending` - Pending * `processing` - Processing * `paid` - Paid * `failed` - Failed * `cancelled` - Cancelled
  - `completed_at` string, date-time, required: When payout was completed (ISO 8601)
  - `payment_ids` string[]: List of Payment UUIDs included in this payout
  - `refund_payment_ids` string[]: List of RefundPayment UUIDs included in this payout
  - `reference_number` string: User-visible payout reference number
  - `memo` string: Internal memo or notes
  - `metadata` unknown

## Response `200`

- PayoutResponse: Full payout serializer for detail views and create responses Includes all computed fields and expanded payment/refund arrays
  - `id` string, uuid, required
  - `business_id` string, uuid, required
  - `external_id` string
  - `processor` 'stripe' | 'paypal' | 'square' | 'adyen' | 'worldpay' | 'sage_pay' | 'klarna' | 'other' | '', required: * `stripe` - Stripe * `paypal` - PayPal * `square` - Square * `adyen` - Adyen * `worldpay` - Worldpay * `sage_pay` - Sage Pay * `klarna` - Klarna * `other` - Other
  - `processor_payout_id` string, required
  - `paid_out_amount_cents` integer, required: Net payout amount in cents (can be negative)
  - `fee_cents` integer
  - `additional_refunds_amount_cents` integer: Additional refunds not tied to specific RefundPayment records
  - `net_amount_cents` integer, required: Net amount: paid_out_amount - fee
  - `currency` 'EUR' | 'GBP' | 'USD' | 'SEK' | 'NOK' | 'DKK' | 'ISK' | 'MYR' | 'SGD': * `EUR` - Euro * `GBP` - British Pound * `USD` - US Dollar * `SEK` - Swedish Krona * `NOK` - Norwegian Krone * `DKK` - Danish Krone * `ISK` - Icelandic Króna * `MYR` - Malaysian Ringgit * `SGD` - Singapore Dollar
  - `status` 'pending' | 'processing' | 'paid' | 'failed' | 'cancelled': * `pending` - Pending * `processing` - Processing * `paid` - Paid * `failed` - Failed * `cancelled` - Cancelled
  - `completed_at` string, date-time, nullable
  - `imported_at` string, date-time, required
  - `reference_number` string
  - `memo` string
  - `metadata` unknown
  - `payment_count` integer, required: Number of payments in this payout
  - `refund_payment_count` integer, required: Number of refund payments in this payout
  - `gross_payments_amount_cents` integer, required: Total amount of invoice payments before refunds
  - `total_refunds_amount_cents` integer, required: Total amount of refund payments in cents
  - `expected_net_amount_cents` integer, required: Expected net: payments - refunds - additional_refunds - fees
  - `amount_variance_cents` integer, required: Difference between reported and expected net (for debugging)
  - `payments` unknown[], required: Expanded payment details
    - unknown
  - `refund_payments` unknown[], required: Expanded refund payment details
    - unknown
  - `reconciliation_status` 'unreconciled' | 'partially_reconciled' | 'fully_reconciled', required: Reconciliation state * `unreconciled` - Unreconciled * `partially_reconciled` - Partially Reconciled * `fully_reconciled` - Fully Reconciled
  - `settlement_file_id` string, uuid, nullable, required: Settlement file UUID if attached
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `201`
- `400`: Validation errors in request data
- `401`: Authentication required - missing or invalid API key
- `403`: Permission denied - insufficient privileges
- `404`: Resource not found
- `409`: Conflict - resource already exists or invalid state transition
- `422`: Unprocessable entity - business logic validation failed
- `500`: Internal server error

---

[API](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api.md) - [All operations](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/revisions/0c1918254db3?raw)