Enterprise: the API, webhooks and MCP server are live for schools on the Enterprise plan. The owner allows every key and AI connection. Ask about Enterprise

On this page

List payments
List invoices
The payment or invoice object

API Reference / Payments & Invoices

Payments & Invoices

Read-only owner-verified root payment/invoice records. Amounts are normalized to currency minor units. These routes expose no card details or actions that move money.

3,000requests per UTC hour

10requests a second, in bursts

429when over, with Retry-After and X-RateLimit-Remaining

Per key or agent connection, on the Enterprise plan.

GET/v1/payments

List payments

Returns owner-verified order records. Optional status accepts an exact source status, unpaid or all; no family_id filter is applied.

Access: payments:read · MCP: list_payments

Headers

AuthorizationstringRequired
Bearer <token>: an API key or an agent OAuth access token. App subscription routes require a dedicated app key.
Swum-Versiondate
Pins the response shape. Default: 2026-10-25.

Query parameters

updated_sincedate-time
Effective update time after an ISO 8601 timestamp with an explicit time zone. Follow every page, including the legacy-record suffix.
limitinteger
1–200; default 50. Minimum 1. Maximum 200. Default: 50.
cursorstring
Opaque next_cursor from the previous page. Keep the same filters.
statusstring
Exact source status, unpaid or all.

Pagination

Keep calling with cursor=next_cursor until next_cursor is null. A filtered page may be short or empty while a next cursor remains.

Request

curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/payments" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": [
    {
      "id": "order_example",
      "family_id": "family_example",
      "status": "paid",
      "amount_minor": 2500,
      "currency": "usd",
      "created_at": "2026-10-25T14:00:00.000Z",
      "due_at": null,
      "updated_at": null
    }
  ],
  "next_cursor": null
}

GET/v1/invoices

List invoices

Returns unpaid invoice states by default, including pending, failed and partial. Successful, paid, completed, canceled, void/voided and refunded states are excluded. status=all returns all records; an exact source status can also be requested.

Access: payments:read

Query parameters

updated_sincedate-time
Effective update time after an ISO 8601 timestamp with an explicit time zone. Follow every page, including the legacy-record suffix.
limitinteger
1–200; default 50. Minimum 1. Maximum 200. Default: 50.
cursorstring
Opaque next_cursor from the previous page. Keep the same filters.
statusstring
Defaults to unpaid; use all or an exact source status. Default: "unpaid".

Pagination

Keep calling with cursor=next_cursor until next_cursor is null. A filtered page may be short or empty while a next cursor remains.

Request

curl "${SWUM_API_BASE:-https://api.swum.ai}/v1/invoices" \
  -H "Authorization: Bearer ${SWUM_API_KEY}"

200Responseapplication/json

{
  "data": [
    {
      "id": "invoice_example",
      "family_id": "family_example",
      "status": "open",
      "amount_minor": 2500,
      "currency": "usd",
      "created_at": null,
      "due_at": null,
      "updated_at": null
    }
  ],
  "next_cursor": null
}

The payment or invoice object

idstring
family_idstring | null
statusstring | null
amount_minorinteger
Currency minor units using the backend currency rules: USD 12.34 is 1234; JPY 1234 is 1234.
currencystring
created_attimestamp | null
due_attimestamp | null
updated_attimestamp | null