> This page is for Consumer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://citi-demo.ferndocs.com/consumer/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://citi-demo.ferndocs.com/consumer/_mcp/server.

# Transactions

### Overview

The Transactions API returns a customer's account activity — both **posted** and **pending** — enriched with merchant names, logos, and spending categories. Use it to build activity feeds, spending insights, search, and export features.

Transactions are returned newest-first and are fully paginated, so you can retrieve as much history as your experience needs.

---

### What you can do

**Show recent activity** — Display a clean, categorized transaction feed inside your app.

**Power spending insights** — Group transactions by category or merchant to surface trends.

**Enable search and export** — Let customers find a specific charge or download activity for their records.

---

### List transactions

#### Authenticate

Obtain an access token with the `accounts:read` scope.

#### Request transactions

Call the endpoint with an `accountRef` and an optional date range. Use `limit` and `cursor` to page through results.

#### Render the feed

Combine `PENDING` and `POSTED` transactions, and use the category and merchant fields to enrich each row.

```json
{
  "accountRef": "acct_884201",
  "transactions": [
    {
      "id": "txn_5f9c22",
      "status": "PENDING",
      "amount": -42.18,
      "currency": "USD",
      "description": "BLUE BOTTLE COFFEE",
      "merchant": { "name": "Blue Bottle Coffee", "category": "Dining" },
      "date": "2026-04-23"
    },
    {
      "id": "txn_5f9b04",
      "status": "POSTED",
      "amount": 2500.00,
      "currency": "USD",
      "description": "PAYROLL DIRECT DEP",
      "merchant": { "name": "Acme Corp", "category": "Income" },
      "date": "2026-04-22"
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjI1fQ"
}
```

> **Info**
>
> Pending transactions can change or disappear before they post. Always key your UI on the transaction `id` and refresh status rather than assuming a pending charge is final.

---

### Filtering

| Parameter          | Description                                           |
| ------------------ | ----------------------------------------------------- |
| `from` / `to`      | Restrict to a date range (up to 24 months of history) |
| `category`         | Filter by spending category, e.g. `Dining`            |
| `status`           | `PENDING`, `POSTED`, or both                          |
| `limit` / `cursor` | Control pagination                                    |

---

### Security requirements

Requests require an OAuth 2.0 access token with the `accounts:read` scope. See the [Authentication guide](/consumer/api-docs/get-started/authentication).