> ## 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 invoice activity

> Invoice activity for your organization — status, kind, currency, amount, and due/paid dates

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

Returns invoice activity for your organization — one summary row per issued
invoice, with its status, kind, currency, gross amount, and due or paid date.
It powers the **Invoice activity** section at the top of the Invoices tab on
the org Billing page. This endpoint is shared: both buyer and seller
organizations can read their own invoice activity.

<Note>
  The first live producer is the IU fee-invoice store: each issued fee invoice
  appears once as `kind: "fees"`. Media, standalone usage, and credit-purchase
  producers are not wired yet, so those reserved kinds do not currently appear.
  Dark-metered usage (cost absorbed by Apostra) and shadow bills are never served.
  An empty list means this organization has no issued fee invoice yet.
</Note>

## Request

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

## Parameters

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

## From an agent (MCP)

The `get_invoice_activity` operation is available on both the buyer and legacy
v2 `storefront` `api_call` tools, and returns the same rows.

## Response

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

An issued fee invoice looks like:

```json theme={null}
{
  "rows": [
    {
      "status": "open",
      "ref": "FEE-000001",
      "label": "Platform fees — 2026-07",
      "kind": "fees",
      "currency": "USD",
      "amountMinor": 12500,
      "dueAt": "2026-08-31T00:00:00.000Z",
      "invoiceRef": "FEE-000001"
    }
  ]
}
```

| Field              | Type             | Notes                                                                                                                         |
| ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `status`           | string           | Fee invoices currently emit `open` or `paid`; `accruing` and `overdue` are reserved for future producers/lifecycle projection |
| `ref`              | string \| absent | Short reference/number for this activity row, when assigned                                                                   |
| `label`            | string           | Human-readable description of the activity                                                                                    |
| `kind`             | string           | `media`, `fees`, `usage`, or `credit_purchase`                                                                                |
| `currency`         | string           | ISO 4217 currency                                                                                                             |
| `amountMinor`      | integer          | Amount in minor units (e.g. cents for USD)                                                                                    |
| `dueAt`            | string \| absent | Payment due date (ISO 8601), for a formal invoice                                                                             |
| `paidAt`           | string \| absent | When the invoice was paid (ISO 8601)                                                                                          |
| `invoiceRef`       | string \| absent | Reference to the underlying invoice document, when one exists                                                                 |
| `meta.activityKey` | string \| absent | Reserved correlation key for a future activity-derived row                                                                    |
| `meta.iuQuantity`  | number \| absent | Reserved IU quantity for a future standalone `usage` row                                                                      |

## 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 info" href="/v2/buyer/billing/tasks/get-billing-info" icon="address-card">
    The payer identity invoices are sent to
  </Card>

  <Card title="Billing overview" href="/v2/buyer/billing/overview" icon="file-invoice-dollar">
    How invoicing and remittance work
  </Card>
</CardGroup>