Payouts

Overview

The Payouts API helps you track your prop firm withdrawals and earnings. It automatically calculates profit splits, maintains cumulative totals, and syncs with your account balances.

Base URL: /api/v1/payouts

List Payouts

Retrieves your payout history with optional filters.

GET /api/v1/payouts

Query Parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "account_id": "uuid",
      "date": "2024-01-15",
      "total_amount": 5000.00,
      "profit_split": 80,
      "traders_share": 4000.00,
      "firms_share": 1000.00,
      "status": "completed",
      "reference": "PAYOUT-2024-001",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z",
      "account_number": "ACC-12345",
      "firm_id": "uuid",
      "firm_name": "Apex Trader Funding"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Cumulative Calculations

When include_cumulative=true, each payout includes cumulative totals:

{
  "data": [
    {
      "id": "uuid",
      "total_amount": 5000.00,
      "traders_share": 4000.00,
      "cumulative_total_amount": 15000.00,
      "cumulative_traders_share": 12000.00,
      "cumulative_total_amount_by_firm": 10000.00,
      "cumulative_traders_share_by_firm": 8000.00,
      "cumulative_total_amount_by_account": 5000.00,
      "cumulative_traders_share_by_account": 4000.00
    }
  ]
}

Get Single Payout

Retrieves details for a specific payout.

GET /api/v1/payouts/{id}

Create Payout

Records a new payout. The API automatically calculates profit splits and updates account balances.

POST /api/v1/payouts
Content-Type: application/json

{
  "date": "2024-01-15",
  "total_amount": 5000.00,
  "account_id": "uuid",
  "profit_split": 80,
  "status": "completed",
  "reference": "PAYOUT-2024-001"
}

Fields:

• date (required): Payout date (YYYY-MM-DD)
• total_amount (required): Total payout amount before split
• account_id (required): Account ID this payout is from
• profit_split (required): Your profit split percentage (0-100)
• status (required): Payout status
• reference (optional): Reference number or note

Auto-calculated fields:

• traders_share: Your portion (total_amount × profit_split / 100)
• firms_share: Firm's portion (total_amount - traders_share)

Response:

{
  "data": {
    "id": "uuid",
    "user_id": "uuid",
    "account_id": "uuid",
    "date": "2024-01-15",
    "total_amount": 5000.00,
    "profit_split": 80,
    "traders_share": 4000.00,
    "firms_share": 1000.00,
    "status": "completed",
    "reference": "PAYOUT-2024-001",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Update Payout

Updates an existing payout.

PUT /api/v1/payouts/{id}
Content-Type: application/json

{
  "status": "completed",
  "reference": "PAYOUT-2024-001-UPDATED"
}

Updatable fields:

• date
• total_amount (recalculates splits)
• profit_split (recalculates splits)
• status
• reference

Delete Payout

Deletes a payout and updates account balance accordingly.

DELETE /api/v1/payouts/{id}

Payout Status

Account Balance Impact

Creating, updating, or deleting payouts automatically recalculates:

• total_gross_payouts: Sum of all payout total_amounts
• total_net_payouts: Sum of all payout traders_shares
• balance: account_size + net_pnl - total_gross_payouts

This ensures your account balance always reflects payouts withdrawn.

Examples

Track Monthly Payouts by Firm

GET /api/v1/payouts?firm=Apex+Trader+Funding&start_date=2024-01-01&end_date=2024-01-31&include_cumulative=true

Search Payout by Reference

GET /api/v1/payouts?search=PAYOUT-2024-001

Get Cumulative Payout Chart Data

GET /api/v1/payouts?include_cumulative=true

Use cumulative_traders_share for charting total earnings over time.

Best Practices

1. Record payouts promptly - Create payout records when you request or receive them
2. Use consistent references - Use a naming scheme like PAYOUT-YYYY-MM-XXX for tracking
3. Track status changes - Update status as payouts progress through stages
4. Review profit splits - Double-check your profit split percentage before creating payouts
5. Monitor cumulative totals - Use cumulative data to track lifetime earnings trends