/api/v1/billing/historyGet billing transaction history for the authenticated user.
Get billing transaction history for the authenticated user.
freeSince v1.2.1
Why use this
Wallet transaction history for the authenticated user — every credit (subscription refill, one-time grant, manual adjustment, refund) related to billing events, ordered by `created_at DESC` (most recent first). NOT to be confused with the per-call token-debit ledger (that's `/api/v1/account/transactions`); this endpoint is specifically for billing-related credit events. Returns Stripe-shaped records (`amount_usd`, `stripe_invoice_id`) when the transaction was tied to a charge. The right endpoint for the customer-dashboard 'Billing History' table and for support workflows ('was the customer's $29 charge applied?'). EXEMPT (`cost: 0`) — account self-serve.
Common use case
Displaying a transaction history table in the user's wallet page.
Wallet transaction history for the authenticated user — every credit (refill, grant, manual adjustment) and every debit related to subscription billing. NOT to be confused with token-debit ledger transactions; that is GET /api/v1/account/transactions. Returns Stripe-shaped records when applicable. Cost: 0 (account self-serve, not billed).
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| limit | query | optional | 20 | — | Maximum transactions to return per page (capped at 100 server-side). Most callers want 20-50 for typical 'last N transactions' display; for full-history exports use cursor pagination via `offset`. | 20 |
| offset | query | optional | 0 | — | Zero-based pagination offset (NUMBER of transactions to skip from the top). Increment by `limit` to walk pages: `offset=0` page 1, `offset=20` page 2 (when `limit=20`). | 0 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| transactions | array | no | Array of wallet transaction rows, sorted by `created_at DESC` (most recent first). Empty array on accounts with no billing history (free tier accounts that have never upgraded). Includes both Stripe-tied charges and admin-grant credits. |
| transactions[].id | string | no | Internal wallet-transaction ID in `wtx_XXXXXX` format (e.g. `wtx_abc123`). Stable across re-runs. Use as deduplication key when caching transaction history client-side. |
| transactions[].created_at | string | no | ISO-8601 UTC timestamp the transaction was recorded. For Stripe-tied transactions this is the Stripe webhook arrival time (typically within seconds of the actual charge). Use for chronological display. |
| transactions[].type | string | no | Transaction type — one of `subscription_refill` (monthly Stripe charge → 200K-token grant), `one_time_grant` (free-tier signup grant or promotional credit), `manual_adjustment` (admin-applied credit/debit), `refund` (Stripe refund). Use to dispatch UI badges and reconciliation logic. |
| transactions[].amount_usd | number | yes | USD amount charged or refunded via Stripe (positive for charges, negative for refunds). Null for non-Stripe events like `one_time_grant` and `manual_adjustment` (these are tokens-only, no money movement). |
| transactions[].tokens_credited | integer | yes | Tokens added to (or subtracted from) the balance as a result of this transaction. Null when the transaction was admin-recorded but did not move tokens (rare). For paid-plan refills typically 200000; for free-plan signup grants 2000. |
| transactions[].stripe_invoice_id | string | yes | Linked Stripe invoice ID in `in_XXXXX` format. Present for `subscription_refill` and `refund` transactions; null for `one_time_grant` and `manual_adjustment`. Pass to Stripe Customer Portal for receipt download. |
| transactions[].description | string | no | Human-readable description for UI display (e.g. `"Monthly paid plan refill"`, `"Free-tier signup grant"`, `"Admin credit — support ticket #4521"`). Casing follows brand guidelines. |
Sample response
·
- "transactions":
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl "https://api.finradar.ai/api/v1/billing/history" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).