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. Each row carries its owning project, plan and subscriber, so a payment can be attributed without a follow-up lookup. 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": "8b0c4a15-e792-4360-95d8-1f47c0b3e926",
      "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
      "project_name": "Beautiful Mouths",
      "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
      "plan_name": "Monthly",
      "subscriber_id": "6f9b2e37-c184-4a05-8d72-30e16bc9f458",
      "subscriber_name": "Ada Lovelace",
      "status": "successful",
      "amount": "29.00",
      "currency": "USD",
      "provider": "stripe",
      "provider_label": "Stripe",
      "method_id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63",
      "calculated_fee": "1.16",
      "billing_reason": "subscription_cycle",
      "external_payment_id": "pi_3Nxy...",
      "occurred_at": "2026-04-22T10:05:00Z"
    }
  ],
  "meta": {
    "next_cursor": "MjAyNi0wNC...",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13"
  }
}

Example prompts

"Show me the last 100 successful transactions in project 7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13."

"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