DocsAPI ReferencePayouts

Payouts

Overview

Payouts batch approved commissions into payments for partners. The provider generates payouts for a date range, then executes them via Stripe Connect or marks them as paid manually.

All endpoints require API key authentication.

List payouts

GET /api/v1/payouts

Query parameters

Param	Type	Default	Description
`page`	number	1	Page number
`per_page`	number	20	Results per page (max 100)

Example

curl "https://api.affihub.com/api/v1/payouts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "pay_abc123",
      "program_id": "prog_xxx",
      "partner_id": "par_abc123",
      "amount_cents": 18500,
      "status": "pending",
      "period_start": "2026-03-01",
      "period_end": "2026-03-31",
      "paid_at": null,
      "payout_ref": null,
      "created_at": "2026-04-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Generate payouts

POST /api/v1/payouts/generate

Generates payout records from approved commissions within a date range.

Request body

Field	Type	Required	Description
`period_start`	string	Yes	Start date (ISO 8601)
`period_end`	string	Yes	End date (ISO 8601)
`dry_run`	boolean	No	Preview without creating (default: false)

Example

curl -X POST "https://api.affihub.com/api/v1/payouts/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "period_start": "2026-03-01",
    "period_end": "2026-03-31"
  }'

Response

{
  "payouts": [
    {
      "id": "pay_abc123",
      "partner_id": "par_abc123",
      "amount_cents": 18500,
      "commission_count": 8,
      "status": "pending"
    },
    {
      "id": "pay_def456",
      "partner_id": "par_def456",
      "amount_cents": 7200,
      "commission_count": 3,
      "status": "pending"
    }
  ],
  "total_amount_cents": 25700,
  "partner_count": 2
}

What happens

Queries all approved commissions in the date range, grouped by partner
Skips partners below the min_payout_cents threshold
Creates a pending payout for each qualifying partner
Updates related commissions to processing status
Fires a payout.generated webhook event

Dry run

Pass "dry_run": true to preview the payouts without creating them:

curl -X POST "https://api.affihub.com/api/v1/payouts/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "period_start": "2026-03-01",
    "period_end": "2026-03-31",
    "dry_run": true
  }'

The response format is the same, but no records are created.

Update a payout

PATCH /api/v1/payouts/:id

Request body

Field	Type	Description
`status`	string	New status
`payout_ref`	string	External payment reference (e.g., PayPal transaction ID)

Status transitions

From	To	Description
`pending`	`paid`	Mark as paid (manual)
`pending`	`cancelled`	Cancel the payout
`requested`	`pending`	Accept a partner's request
`requested`	`cancelled`	Deny a partner's request

Example

curl -X PATCH "https://api.affihub.com/api/v1/payouts/pay_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paid",
    "payout_ref": "paypal-txn-abc123"
  }'

When status changes to paid, all related commissions are updated to paid and the paid_at timestamp is set.

Pay via Stripe Connect

POST /api/v1/payouts/:id/pay

Executes a Stripe Transfer to the partner's connected Stripe account.

Prerequisites

The partner must have completed Stripe Connect onboarding
The partner's stripe_account_id must be set
Your program must have a Stripe secret key configured

Example

curl -X POST "https://api.affihub.com/api/v1/payouts/pay_abc123/pay" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "pay_abc123",
  "status": "paid",
  "payout_ref": "tr_xxx",
  "paid_at": "2026-04-01T14:30:00Z"
}

What happens

Validates the partner has a connected Stripe account
Creates a Stripe Transfer for the payout amount
Stores the transfer ID in payout_ref
Updates payout status to paid
Updates all related commissions to paid
Fires a payout.paid webhook event

Payout statuses

Status	Description
`pending`	Generated, awaiting payment
`requested`	Partner requested this payout
`paid`	Payment completed
`cancelled`	Cancelled by provider

PreviousCommissions NextFlows