> ## 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.totalEarnings" 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.pendingBalance" type="number">Unpaid balance remaining on the ledger.</ResponseField>
<ResponseField name="data.pendingPayoutAmount" type="number">Amount sitting in `pending` / `processing` / `in_transit` payouts.</ResponseField>
<ResponseField name="data.minimumPayoutAmount" type="number">Threshold below which a payout is rolled into the next cycle. Default `25.00` USD.</ResponseField>
<ResponseField name="data.earningsByApp" type="array">Per-app earnings breakdown.</ResponseField>

```json theme={null}
{
  "status": 200,
  "data": {
    "totalEarnings": "4827.61",
    "totalPaidOut": "3998.09",
    "pendingBalance": "729.52",
    "pendingPayoutAmount": "100.00",
    "minimumPayoutAmount": "25.00",
    "earningsByApp": []
  }
}
```

***

## 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": "d290f1ee-…",
        "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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.