> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Earnings & payouts

> Track accrued affiliate commission, export it for accounting, and mark conversions paid once you settle with your affiliates.

Macropay tracks every affiliate conversion and the commission it accrues, so you always know what you owe and what you have already paid. In v1, Macropay does **not** move money to your affiliates — you pay them with your own method (bank transfer, PayPal, gift card, however you settle) and mark the conversions paid for your records.

<Note>
  Macropay does not send payouts to affiliates. The Earnings view is a ledger
  for tracking accrued commission and recording your own settlements. You remain
  responsible for paying affiliates and for any tax reporting that applies.
</Note>

## Conversion lifecycle

Every referred sale becomes a conversion. Its status tells you where the commission sits:

| Status     | Meaning                                                                              |
| ---------- | ------------------------------------------------------------------------------------ |
| `pending`  | Commission accrued from a sale, not yet cleared (e.g. still inside a refund window). |
| `approved` | Commission cleared and owed to the affiliate — ready to pay.                         |
| `paid`     | You settled with the affiliate and marked the conversion paid.                       |
| `reversed` | The underlying sale was refunded or disputed; the commission is clawed back.         |

A conversion typically moves `pending → approved → paid`. A refund or dispute moves it to `reversed`, removing it from what you owe.

## Earnings in the dashboard

Open **Affiliates → Earnings** to review and settle commission.

<Steps>
  <Step title="Review the totals">
    The header shows total conversions, **owed** (unpaid `approved` commission),
    and **paid** to date — so you can see your outstanding affiliate liability at
    a glance.
  </Step>

  <Step title="Filter the conversions table">
    Filter by affiliate and by conversion status to isolate exactly what you
    intend to settle this cycle.
  </Step>

  <Step title="Export for accounting">
    Click **Export CSV** to download the filtered conversions for bookkeeping,
    reconciliation, or your payout spreadsheet.
  </Step>

  <Step title="Pay affiliates, then mark paid">
    Settle with your affiliates using your own payment method, then select the
    conversions and use bulk **Mark paid** to record the settlement.
  </Step>
</Steps>

<Tip>
  Use the **batch ID** when marking paid to group everything from one payout run
  (for example, a monthly bank transfer batch). It makes reconciliation against
  your bank statement straightforward.
</Tip>

## Payouts tab — settle per affiliate, net of fees

**Affiliates → Payouts** rolls commission up **per affiliate** so you can pay each
one in a single transfer to the PayPal or bank details they saved in their portal.

| Column        | Meaning                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Held**      | Commission still inside your **payout hold window** — a refund/chargeback buffer. Set the days in **Program** settings (default 30). |
| **Available** | Commission past the hold window, ready to pay.                                                                                       |
| **Paid**      | The **net** you've already sent (after fees).                                                                                        |

To settle an affiliate, click **Pay**, enter the **actual fee** your bank or PayPal
charged, and Macropay shows the **net to send** (gross − fee) and records the
payout. **Export CSV** gives every affiliate's amount + payout method/details for a
bulk run. Each settlement is logged under **Recent payouts** with gross, fee, and
net. Macropay records the payout — **you send the net** with your own method; it
never moves money to affiliates.

### One-click PayPal payouts (optional)

If you connect a PayPal Business account (with Payouts enabled), affiliates who
chose **PayPal** as their method get a **Send via PayPal** button on the Pay
dialog — it sends the net straight to their PayPal email via the PayPal Payouts
API and records the payout, no manual transfer. Bank/Wise affiliates continue to
use the export + your own transfer. PayPal is off until credentials are
configured; set it up in **sandbox** first, verify a test payout, then switch to
live.

## API reference

All endpoints use the base URL `https://api.macropay.ai` and a bearer token.

### List conversions

`GET /v1/affiliates/conversions` returns conversions, with optional filters for `affiliate_id` and `conversion_status`.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.macropay.ai/v1/affiliates/conversions \
    -G \
    --data-urlencode "affiliate_id=aff_8842" \
    --data-urlencode "conversion_status=approved" \
    -H "Authorization: Bearer <token>"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.macropay.ai/v1/affiliates/conversions",
      params={"affiliate_id": "aff_8842", "conversion_status": "approved"},
      headers={"Authorization": "Bearer <token>"},
  )
  conversions = resp.json()
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({
    affiliate_id: "aff_8842",
    conversion_status: "approved",
  });

  const resp = await fetch(
    `https://api.macropay.ai/v1/affiliates/conversions?${params}`,
    { headers: { Authorization: "Bearer <token>" } },
  );
  const conversions = await resp.json();
  ```
</CodeGroup>

### Export conversions as CSV

`GET /v1/affiliates/conversions/export` returns the same filtered set as a CSV file — ideal for handing to accounting.

```bash cURL theme={null}
curl https://api.macropay.ai/v1/affiliates/conversions/export \
  -G \
  --data-urlencode "conversion_status=approved" \
  -H "Authorization: Bearer <token>" \
  -o affiliate-conversions.csv
```

### Mark conversions paid

`POST /v1/affiliates/conversions/mark-paid` records that you have settled the listed conversions. Pass the `conversion_ids` to settle and an optional `batch_id` to tag the payout run.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.macropay.ai/v1/affiliates/conversions/mark-paid \
    -X POST \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "conversion_ids": ["conv_a1b2", "conv_c3d4", "conv_e5f6"],
      "batch_id": "payout_2026_05"
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.macropay.ai/v1/affiliates/conversions/mark-paid",
      headers={"Authorization": "Bearer <token>"},
      json={
          "conversion_ids": ["conv_a1b2", "conv_c3d4", "conv_e5f6"],
          "batch_id": "payout_2026_05",
      },
  )
  result = resp.json()
  ```
</CodeGroup>

<Warning>
  Marking a conversion paid only updates your Macropay records — it does not
  trigger any transfer. Always complete the actual payment to your affiliate
  first, then mark the conversions paid.
</Warning>

## Where to send the money

Each affiliate provides their own payout details from their portal, so you
always know where to send commission.

<Steps>
  <Step title="The affiliate adds payout details">
    In their portal (`/affiliate?org=<your-org-id>`) the affiliate opens
    **Payout details**, picks a method — **PayPal**, **bank transfer**, **Wise**,
    or **Other** — and fills in the fields (e.g. PayPal email, or account holder

    * IBAN/account number + SWIFT/routing + country).
  </Step>

  <Step title="You read them in the affiliate's detail view">
    On **Dashboard → Affiliates**, expand an affiliate ("View details, payout &
    earnings") to see their earnings rollup (earned / owed / paid), the payout
    details they entered, and their conversions — with a per-affiliate
    **Mark N paid** button.
  </Step>

  <Step title="Pay them, then mark paid">
    Send the payment with the method they specified, then mark their pending
    conversions paid.
  </Step>
</Steps>

<Note>
  Payout details are provided and owned by the affiliate — you view them to pay,
  but you don't edit them. If an affiliate hasn't added details yet, their detail
  view shows "Not provided yet".
</Note>

## FAQ

**Does Macropay pay my affiliates?**
No. In v1, Macropay tracks accrued commission and lets you record settlements, but it does not move money to affiliates. You pay them with your own method and use **Mark paid** (or the `mark-paid` endpoint) to keep your ledger accurate.

**How do I export earnings for accounting?**
Filter the conversions table in **Affiliates → Earnings** and click **Export CSV**, or call `GET /v1/affiliates/conversions/export` with the same filters. The CSV is ready to hand to bookkeeping or reconcile against a payout batch.

**What happens to commission on a refund or dispute?**
The related conversion moves to `reversed` and its commission is clawed back, so it no longer counts toward what you owe. If you had already marked it paid before the reversal, reconcile that overpayment with the affiliate directly.

**What's the difference between owed and paid totals?**
**Owed** is the sum of cleared (`approved`) commission you have not yet settled — your outstanding affiliate liability. **Paid** is the running total you have already marked paid.

**Can I group conversions from a single payout run?**
Yes. Pass a `batch_id` when marking paid (in the dashboard or via the API) to tag everything from one payout, which makes reconciling against your bank statement easy.

## Related

<CardGroup cols={2}>
  <Card title="Set up affiliates" icon="gear" href="/features/affiliates/setup">
    Create affiliates, configure commission rates, and generate referral links.
  </Card>

  <Card title="Affiliates introduction" icon="users" href="/features/affiliates/introduction">
    How referral tracking and commission accrual work end to end.
  </Card>
</CardGroup>