Get invoice activity

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.

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.

Request

curl

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

{
  "rows": []
}

An issued fee invoice looks like:

{
  "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
`rows[].creditNotes`	array \| absent	Credit notes issued against this invoice, newest first. Absent when the invoice has none. See Credit notes
`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

Credit notes

An issued invoice is never edited. When Apostra refunds a platform fee charge to your card, the correction is a separate, numbered credit note against the invoice that carried the charge, and it appears in that invoice’s row under creditNotes. The invoice’s own amountMinor stays as billed; the credit note reduces what it cost.

{
  "rows": [
    {
      "status": "paid",
      "ref": "FEE-000001",
      "label": "Platform fees — 2026-09",
      "kind": "fees",
      "currency": "EUR",
      "amountMinor": 5000,
      "invoiceRef": "FEE-000001",
      "creditNotes": [
        {
          "ref": "CN-000001",
          "label": "Credit note CN-000001 — Charged for usage from before your plan started",
          "currency": "EUR",
          "amountMinor": 5000,
          "reason": "Charged for usage from before your plan started",
          "issuedAt": "2026-10-27T10:00:00.000Z"
        }
      ]
    }
  ]
}

Field	Type	Notes
`rows[].creditNotes[].ref`	string	The credit note number, such as `CN-000001`. Numbers are sequential and never reused
`rows[].creditNotes[].label`	string	The number and the reason, as shown on Plan & Billing
`rows[].creditNotes[].currency`	string	ISO 4217 currency, the same as the invoice
`rows[].creditNotes[].amountMinor`	integer	Amount credited, in minor units. Positive
`rows[].creditNotes[].reason`	string	Why the credit was issued, in plain words
`rows[].creditNotes[].issuedAt`	string	When the credit note was issued (ISO 8601)

On Payment & invoices in Plan & Billing, each credit note is a line directly under its invoice, with the amount shown as a negative.

Errors

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

See Errors for the full error contract.

Get billing info

The payer identity invoices are sent to

Billing overview

How invoicing and remittance work

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Get invoice activity

Request

Parameters

From an agent (MCP)

Response

Credit notes

Errors

Get billing info

Billing overview

​Request

​Parameters

​From an agent (MCP)

​Response

​Credit notes

​Errors

​Related

Get billing info

Billing overview

Request

Parameters

From an agent (MCP)

Response

Credit notes

Errors

Related