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

# Developer Payouts

> Earnings summary, payout history, and payout details for an app developer.

A **payout** is a scheduled disbursement of a developer's accrued earnings,
sent to the destination configured at
[Payout Methods](/api-reference/developer/payout-methods). LaunchMyStore is
the merchant of record: when a merchant pays for an installed app, the
charge clears against the platform's Stripe account; the platform takes its
commission, and the residual `developerAmount` accumulates on the
developer's ledger. The payout job runs on a fixed cadence (monthly by
default) and sweeps the ledger to a single payout row per developer.

The developer-facing endpoints below are read-only from the developer's
perspective — payouts cannot be initiated from this API (use the admin
endpoint for SWIFT/PayPal manual ops, or wait for the scheduled cron).

**Auth:** developer JWT. The `developerId` is read from the token, not
from the URL.

***

## Earnings summary

`GET /apps/developer/earnings`

Returns the developer's running ledger — total earned, total paid out, and
balance remaining.

```bash theme={null}
curl -X GET "https://api.launchmystore.io/apps/developer/earnings" \
  -H "Authorization: Bearer <DEVELOPER_JWT>"
```

<ResponseField name="data.totalEarned" type="number">Lifetime sum of `developerAmount` across all `paid` transactions.</ResponseField>
<ResponseField name="data.totalPaidOut" type="number">Lifetime sum of `amount` across `paid` payouts.</ResponseField>
<ResponseField name="data.balance" type="number">Unpaid balance = `totalEarned − totalPaidOut − inFlight`.</ResponseField>
<ResponseField name="data.inFlight" type="number">Amount sitting in `pending` / `processing` / `in_transit` payouts.</ResponseField>
<ResponseField name="data.currency" type="string">ISO-4217 currency code. Single currency — multi-currency apps roll up to USD by default.</ResponseField>
<ResponseField name="data.nextPayoutAt" type="string">ISO date the next scheduled payout will run. `null` when the developer has no payout method configured.</ResponseField>
<ResponseField name="data.minimumPayoutAmount" type="number">Threshold below which a payout is rolled into the next cycle. Default `25.00` USD.</ResponseField>

```json theme={null}
{
  "status": 200,
  "data": {
    "totalEarned": "4827.61",
    "totalPaidOut": "3998.09",
    "balance":      "729.52",
    "inFlight":     "100.00",
    "currency":     "USD",
    "nextPayoutAt": "2026-06-01T00:00:00.000Z",
    "minimumPayoutAmount": "25.00"
  }
}
```

***

## List payouts

`GET /apps/developer/payouts`

Paginated payout history, newest first.

<ParamField query="page" type="integer" default="1" />

<ParamField query="limit" type="integer" default="50">Max 250.</ParamField>
<ParamField query="status" type="string">Filter to `pending`, `processing`, `in_transit`, `paid`, or `failed`.</ParamField>

```bash theme={null}
curl -X GET "https://api.launchmystore.io/apps/developer/payouts?status=paid&limit=20" \
  -H "Authorization: Bearer <DEVELOPER_JWT>"
```

<ResponseField name="data.items" type="array">Payout rows.</ResponseField>
<ResponseField name="data.pagination" type="object">`{ page, limit, total, hasMore }`.</ResponseField>

### Payout object

| Field               | Type           | Description                                                                          |
| ------------------- | -------------- | ------------------------------------------------------------------------------------ |
| `payoutId`          | UUID           | Primary key.                                                                         |
| `developerId`       | UUID           | Owning developer account.                                                            |
| `amount`            | decimal        | Gross payout amount (in `currency`).                                                 |
| `currency`          | string         | ISO-4217.                                                                            |
| `status`            | enum           | `pending`, `processing`, `in_transit`, `paid`, `failed`.                             |
| `payoutMethodType`  | enum           | Snapshot of the method type used: `bank` (SWIFT) or `paypal`.                        |
| `externalReference` | string\|null   | Wire reference (SWIFT) or PayPal payout id. Filled when status becomes `in_transit`. |
| `periodStart`       | datetime       | First day of the earnings window.                                                    |
| `periodEnd`         | datetime       | Last day of the window.                                                              |
| `transactionIds`    | string\[]      | UUIDs of billing transactions aggregated into this payout.                           |
| `failureReason`     | string\|null   | Reason for `failed` status.                                                          |
| `paidAt`            | datetime\|null | When the payout cleared.                                                             |
| `createdAt`         | datetime       | When the payout row was created (sweep time).                                        |

### Status lifecycle

```
   pending  ──► processing ──► in_transit ──► paid
       │             │              │
       └─────────────┴──────────────┴──► failed
```

* `pending`: row created by the sweep; queued for processing.
* `processing`: dispatcher locked the row, building the bank/PayPal request.
* `in_transit`: SWIFT wire submitted or PayPal payout dispatched; awaiting
  external confirmation. `externalReference` is set at this transition.
* `paid`: external system confirmed receipt. `paidAt` is set.
* `failed`: irrecoverable error; `failureReason` is set; balance is
  refunded to the ledger so the next cycle re-attempts.

### Example response

```json theme={null}
{
  "status": 200,
  "data": {
    "items": [
      {
        "payoutId": "8d4f1c10-3b6e-4e76-9b6a-1a17a5be58a0",
        "developerId": "f73049dc-…",
        "amount": "729.52",
        "currency": "USD",
        "status": "paid",
        "payoutMethodType": "bank",
        "externalReference": "WIRE-2026-04-17-A42",
        "periodStart": "2026-04-01T00:00:00.000Z",
        "periodEnd":   "2026-04-30T23:59:59.999Z",
        "transactionIds": ["…", "…", "…"],
        "failureReason": null,
        "paidAt":   "2026-05-02T14:18:11.881Z",
        "createdAt":"2026-05-01T01:00:00.000Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 7, "hasMore": false }
  }
}
```

***

## Get one payout

`GET /apps/developer/payouts/:payoutId`

Returns the same payout object plus the full list of contributing
transactions inlined.

```bash theme={null}
curl -X GET "https://api.launchmystore.io/apps/developer/payouts/<PAYOUT_ID>" \
  -H "Authorization: Bearer <DEVELOPER_JWT>"
```

<ResponseField name="data.payout" type="object">The payout row.</ResponseField>
<ResponseField name="data.transactions" type="array">Inlined billing transactions — `{ transactionId, appId, storeId, amount, developerAmount, currency, createdAt }`.</ResponseField>

```json theme={null}
{
  "status": 200,
  "data": {
    "payout": { "payoutId": "8d4f1c10-…", "amount": "729.52", "...": "..." },
    "transactions": [
      { "transactionId": "…", "appId": "…", "storeId": "…",
        "amount": "9.99", "developerAmount": "7.99",
        "currency": "USD", "createdAt": "2026-04-15T03:12:47.881Z" }
    ]
  }
}
```

***

## Requesting a payout

There is **no developer-facing "request payout" endpoint**. Payouts are
swept on a fixed cadence:

* Monthly on the 1st (default cadence, configurable per-developer to
  weekly / fortnightly via support).
* Only swept when `balance >= minimumPayoutAmount`.
* Below threshold balances roll into the next cycle.

For ad-hoc payouts (out-of-cycle SWIFT/PayPal disbursement), platform ops
calls the admin endpoint `POST /apps/admin/payouts/process-scheduled` or
manually marks an in-transit payout paid via
`POST /apps/admin/payouts/:payoutId/mark-paid` (admin-only). Developers
cannot trigger these themselves.

<Note>
  Stripe Connect (Express / Standard) payouts that disburse directly to a
  developer's connected account on a schedule are on the roadmap. The
  current implementation uses LaunchMyStore as merchant of record with
  manual SWIFT / PayPal dispatch.
</Note>

## Error codes

| Code  | Description                                            |
| ----- | ------------------------------------------------------ |
| `401` | Missing or invalid developer JWT.                      |
| `404` | Payout not found, or belongs to a different developer. |
| `400` | Invalid `status` filter.                               |