---
title: "Create a Custom Payout"
method: POST
path: "/affiliates/{affiliate_id}/payouts"
tags: ["Affiliates"]
---

# Create a Custom Payout

`POST /affiliates/{affiliate_id}/payouts`

Creates a custom payout for the affiliate — an amount of the project's own for the days it covers, outside the monthly payouts. It is `pending` right away and is never sent automatically: it must be sent from the dashboard. Note 1: custom payouts must be enabled for the project. Note 2: this endpoint is only accessible with a secret API key.

## Path parameters

- `affiliate_id` string, required

## Headers

- `x-api-key` string, required

## Request body

- AffiliateCustomPayoutCreateRequest
  - `amount` integer, required — The amount to pay the affiliate, in USD cents — from 1000 ($10) to 1000000 ($10,000)
  - `description` string, required — What the payout is for, from 10 to 200 characters. Shown to the affiliate
  - `period_start` string, date, required — The first day the payout covers, YYYY-MM-DD — from the first day of last month
  - `period_end` string, date, required — The last day the payout covers, YYYY-MM-DD — on or after `period_start`, and no later than the last day of next month. The same day as `period_start` for a single day
  - `operation_id` string, nullable — An optional operation id that ensures the same payout won't be created again

## Response `201`

The payout has been created.

- AffiliatePayoutResponse
  - `data` AffiliatePayoutResponseData, required
    - `payout` AffiliatePayout, required
      - `id` string, required — The payout id
      - `affiliate_id` string, required — The id of the affiliate the payout is to
      - `type` 'performance' | 'custom', required — What the payout is: `performance` collects what the affiliate earned in a calendar month; `custom` is an amount the project set itself
      - `status` 'upcoming' | 'holding' | 'pending' | 'processing' | 'sent' | 'completed' | 'failed' | 'cancelled', required — Where the payout is: `upcoming` and `holding` still collect or wait out refunds, `pending` is ready to be sent, `processing` is on its way, `completed` has been paid, `failed` goes back to pending, `cancelled` will not be paid
      - `amount` integer, required — The amount, in USD cents
      - `description` string, nullable, required — What a `custom` payout is for, as the project put it. Null for `performance` payouts
      - `period_start` string, date, required — The first day the payout covers, in UTC
      - `period_end` string, date, nullable, required — The last day the payout covers, in UTC. Null while an `upcoming` payout is still collecting
      - `created_at` string, date-time, required — When the payout was created
      - `completed_at` string, date-time, nullable, required — When the payout was paid. Null until it is

## Other responses

- `401` — Unauthorized
- `403` — Custom payouts are not enabled for the project, or the operation id has already been used.
- `404` — The affiliate is not an approved affiliate of the project.
- `422` — The request is invalid.
- `429` — The rate limit for this endpoint has been exceeded.

## Changes

- **2026-09-30** `f3e82ba251e6` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/winwinkit/apis/winwinkit-api/changes/affiliates/:affiliate_id/payouts/post.md)

---

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