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

# Get payout activity

> Payout setup history now, plus payout-run activity when its ledger producer lands

`GET /api/v2/billing/payout-activity`

Returns payout activity for your organization. Today it returns `kind: "setup"`
rows showing when payout details were added, updated, or cleared and who made
the change. The response contract also reserves `kind: "ledger"` rows for
actual payout runs. It powers the **Payout activity** section at the top of the
Payouts tab on the org Billing page.

<Note>
  Payout runs are executed manually by Apostra finance team (see
  [Billing overview](/v2/storefront/billing/overview)). No producer projects those
  runs into `kind: "ledger"` rows yet. Setup/audit rows are live now; an empty list
  means there have been no qualifying payout-detail changes for the organization.
</Note>

## Request

```bash curl theme={null}
curl "https://api.apostra.com/api/v2/billing/payout-activity" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
```

## Parameters

| Parameter          | Type                      | Notes                                                                                                       |
| ------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `targetCustomerId` | integer (query, optional) | Read a child account's payout activity — parent-to-child only, validated against the organization hierarchy |

## From an agent (MCP)

The `get_payout_activity` operation on the legacy v2 Seller Account
`storefront` `api_call` tool returns the same rows.

## Response

```json theme={null}
{
  "rows": []
}
```

A current setup row looks like:

```json theme={null}
{
  "rows": [
    {
      "kind": "setup",
      "reason": "updated",
      "description": "Payout details updated",
      "actorEmail": "finance-admin@example.com",
      "occurredAt": "2026-08-18T08:15:00.000Z"
    }
  ]
}
```

### Setup row fields (live)

| Field                | Type           | Notes                                                                |
| -------------------- | -------------- | -------------------------------------------------------------------- |
| `rows[].kind`        | `"setup"`      | Identifies a payout-details audit row                                |
| `rows[].reason`      | string         | `updated`, `cleared`, or fallback `changed`                          |
| `rows[].description` | string         | Human-readable event description; never includes bank/account values |
| `rows[].actorEmail`  | string \| null | User who made the change, when known                                 |
| `rows[].occurredAt`  | string         | Event time (ISO 8601)                                                |

### Ledger row fields (reserved; producer not built)

| Field                 | Type             | Notes                                                                                                                                                                                                    |
| --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rows[].kind`         | `"ledger"`       | Identifies a future payout-run row                                                                                                                                                                       |
| `rows[].status`       | string           | `pending`, `paid`, or `failed`                                                                                                                                                                           |
| `rows[].periodLabel`  | string           | Human-readable payout period (e.g. "June 2026")                                                                                                                                                          |
| `rows[].entityName`   | string           | The legal payout entity this row was paid to — matches [payout payees](/v2/storefront/billing/tasks/list-payout-payees) for multi-entity sellers, or your organization name for the single default payee |
| `rows[].currency`     | string           | ISO 4217 payout currency                                                                                                                                                                                 |
| `rows[].amountMinor`  | integer          | Amount in minor units (e.g. cents for USD)                                                                                                                                                               |
| `rows[].expectedAt`   | string \| absent | Expected payout date (ISO 8601), when known and not yet paid                                                                                                                                             |
| `rows[].paidAt`       | string \| absent | When the payout actually landed (ISO 8601)                                                                                                                                                               |
| `rows[].statementRef` | string \| absent | Reference to the payout statement/remittance advice, when available                                                                                                                                      |

## Errors

* `401 UNAUTHORIZED` — missing or invalid bearer token.
* `403 ACCESS_DENIED` — `targetCustomerId` isn't a child of the requesting organization.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Get billing config" href="/v2/storefront/billing/tasks/get-billing-config" icon="gear">
    Fees, currency, net days, masked payout details
  </Card>

  <Card title="Billing overview" href="/v2/storefront/billing/overview" icon="credit-card">
    How payouts work
  </Card>
</CardGroup>