list_transactions

Keyset-paginated transaction listing for one project with date, status, provider, plan, and currency filters. Reverse-chronological.

Purpose

Row-level transaction listing scoped to a single project. Filters by date range (explicit from / to or period preset), payment status, provider, plan, and currency. Reverse-chronological by occurred_at with opaque keyset pagination via meta.next_cursor. No raw webhook payloads are returned.

Required ability

project-subscription:view-any

Input schema

{
  "type": "object",
  "required": ["project_id"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "UUID of the project whose transactions to list."
    },
    "period": {
      "type": "string",
      "description": "Period preset — 7d, 14d, 30d, 60d, 90d, mtd, qtd, ytd, 1y, all. Defaults to 30d."
    },
    "from": {
      "type": "string",
      "description": "Explicit start date (ISO YYYY-MM-DD). Overrides period when paired with 'to'."
    },
    "to": {
      "type": "string",
      "description": "Explicit end date (ISO YYYY-MM-DD). Overrides period when paired with 'from'."
    },
    "statuses": {
      "type": "array",
      "description": "Optional payment-status allow-list. Values: successful, pending, failed, refunded."
    },
    "provider_ids": {
      "type": "array",
      "description": "Optional payment-method (provider) UUID allow-list."
    },
    "plan_ids": {
      "type": "array",
      "description": "Optional plan-UUID allow-list applied to the parent subscription."
    },
    "currency_ids": {
      "type": "array",
      "description": "Optional currency UUID allow-list."
    },
    "cursor": {
      "type": "string",
      "description": "Opaque keyset cursor returned in a prior meta.next_cursor. Pass to continue pagination."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Maximum rows to return (1..200, default 50)."
    }
  }
}

Output shape

{
  "data": [
    {
      "id": "pay_01HX...",
      "subscription_id": "sub_01HX...",
      "status": "successful",
      "amount": "29.00",
      "occurred_at": "2026-04-22T10:05:00Z"
    }
  ],
  "meta": {
    "next_cursor": "MjAyNi0wNC...",
    "project_id": "prj_01HX..."
  }
}

Example prompts

"Show me the last 100 successful transactions in project prj_01HX...."

"List refunds issued between 2026-01-01 and 2026-03-31."

Failure modes

VALIDATION_FAILED — missing project_id.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-subscription:view-any.

list_recent_payments — simpler, no date-range filters.
get_transaction_breakdown — aggregate view of the same data.
get_earnings_report