---
title: "List card transactions"
method: GET
path: "/v1/card_transactions"
tags: ["Card transaction"]
---

# List card transactions

`GET /v1/card_transactions`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/card_transactions`
- Auth: HTTP bearer

Returns a paginated list of card transactions — every authorization, capture, refund, fee, and adjustment that touched any of the company's vendor cards.

The endpoint excludes the internal `StripeAuthorization` rows (those are partial pre-auths that get superseded by a final `CardTransaction`). The result is scoped per-caller across every company the caller has permission in (via `policy_scope`); the `company-id` header is **not** consulted, and omitting it still returns `200` with the caller's full permitted scope. To restrict results to one company, filter explicitly with the `company_id` query parameter.

## When you'll use this endpoint

- Show the "transactions feed" in your dashboard.
- Build per-user / per-card / per-merchant spend reports.
- Audit pending vs. approved transactions ahead of month-end close.
- Reconcile each row with its legacy `Invoice` (when set via `invoice_id`). Note: `invoice_id` points to the internal `Invoice` UUID — it is **not** a `FiscalInvoice` / SII DTE id. To match a transaction against a SII DTE you have to cross the merchant + amount + date against `GET /v1/fiscal_invoices`.

## Response structure

Each row exposes:

| Field | Description |
| --- | --- |
| `id` | Vendor-prefixed string (base64 encoded for some vendors). |
| `vendor_card_id` | The `VendorCard.id` that incurred the transaction. |
| `user_id` | Firebase user id of the cardholder. |
| `company_id` | UUID of the company. |
| `amount_cents` / `currency` | Transaction amount in the merchant's currency. |
| `target_amount_cents` / `target_currency` | Settled amount in the company's accounting currency. |
| `amount_in_clp` | Amount converted to CLP at settlement time (Chile-specific reporting). |
| `amount_in_limit_currency` | Amount converted to the card's `limit_currency`. |
| `exchange_rate` | FX rate applied at settlement. |
| `status` | Lifecycle (see enum). |
| `kind` | Transaction kind (`purchase`, `refund`, `fee`, `adjustment`, etc.). |
| `merchant` (`merchant_name`, `cleaned_merchant_name`, `merchant_image_url`, `merchant_id`) | Merchant info. |
| `description` | Free-form description from the vendor or the cardholder. |
| `comments` | Internal notes (e.g. "client meeting Q1 review"). |
| `transaction_labels` | Tags applied by the company. |
| `invoice_id` | Legacy `Invoice` UUID (internal billing record kept for backwards compatibility). **Not** a `FiscalInvoice` / SII DTE id — fiscal invoices use the composite `<rut>-<document_type>-<number>` format and are exposed via `GET /v1/fiscal_invoices`. |
| `superseding_transaction_id` | When a pending transaction is replaced by the final one, the new id. |
| `superseding_reason` | Why it was superseded. |
| `completed_at` / `settled_at` / `created_at` | Lifecycle timestamps. |
| `target_amount_formatted`, `amount_formatted` | UI-ready strings. |
| `card` | Embedded vendor-card summary. |

## Common queries

```bash
# Most recent transactions of a single card, excluding superseded rows
GET /v1/card_transactions?\
  vendor_card_id=Q2FyZDoxMDIwNjQ5Mw==&\
  status={"$ne":"superseded"}&\
  _order=desc&_field=created_at&_start=0&_end=25

# Approved transactions in the last 30 days, by status
GET /v1/card_transactions?\
  status=approved&\
  created_at={"$gte":"2026-04-01T00:00:00Z"}&\
  _order=desc&_field=created_at

# Pending transactions of a specific user (declines and pre-auths)
GET /v1/card_transactions?\
  user_id=<firebase_uid>&\
  status=pending

# Search by merchant name (regex)
GET /v1/card_transactions?\
  merchant_name={"$regex":"AWS"}

# By kind — purchases/refunds only, excluding fees
GET /v1/card_transactions?\
  kind={"$in":["purchase","refund"]}

# USD-denominated transactions that haven't been linked to a legacy `Invoice` yet
GET /v1/card_transactions?\
  currency={"$ne":"CLP"}&\
  invoice_id=null
```

All operators in [Filters](https://docs.cardda.com/docs/filters) are supported on the columns listed below.

## Query parameters

- `vendor_card_id` string
- `id` string
- `company_id` string, uuid
- `user_id` string
- `status` 'pending' | 'approved' | 'declined' | 'reversed' | 'settled' | 'superseded' | 'disputed' | 'refunded'
- `kind` 'purchase' | 'refund' | 'fee' | 'adjustment' | 'reversal' | 'allocation' | 'allocation_release' | 'fx_fee'
- `type` 'PomeloTransaction' | 'PlhTransaction' | 'StripeTransaction' | 'BrexTransaction' | 'MercuryTransaction' | 'DivvyTransaction' | 'MeshTransaction' | 'AptoTransaction' | 'IncreaseTransaction'
- `currency` string
- `target_currency` string
- `amount_cents` string
- `merchant_name` string
- `cleaned_merchant_name` string
- `merchant_id` string, uuid
- `description` string
- `invoice_id` union
  - string, uuid
  - 'null'
- `created_at` string
- `completed_at` string
- `settled_at` string
- `$or` string

## Parameters

- `#/paths/~1v1~1merchants/get/parameters/0` (unresolved $ref)
- `#/paths/~1v1~1merchants/get/parameters/2` (unresolved $ref)
- `#/paths/~1v1~1merchants/get/parameters/3` (unresolved $ref)
- `#/paths/~1v1~1merchants/get/parameters/4` (unresolved $ref)
- `#/paths/~1v1~1merchants/get/parameters/5` (unresolved $ref)

## Response `200`

Paginated list of card transactions. Headers include `X-Total-Count`
and `Content-Range` for offset pagination — see [Pagination](https://docs.cardda.com/docs/pagination).

- Transaction[]
  - `id` string: Vendor-prefixed transaction id (often base64-encoded; not a UUID).
  - `user_id` string: Firebase user id of the cardholder.
  - `vendor_card_id` string: Id of the `VendorCard` that incurred the transaction (vendor-prefixed string, not a UUID).
  - `description` string
  - `merchant_name` string
  - `cleaned_merchant_name` string, nullable: Cardda-normalized merchant name (e.g. 'AMZN MKTP US' → 'Amazon').
  - `merchant_image_url` string, nullable
  - `merchant_id` string, uuid, nullable
  - `status` 'pending' | 'approved' | 'declined' | 'reversed' | 'settled' | 'superseded' | 'disputed' | 'refunded': Lifecycle status of the transaction.
  - `kind` 'purchase' | 'refund' | 'fee' | 'adjustment' | 'reversal' | 'allocation' | 'allocation_release' | 'fx_fee': What sort of monetary movement the row represents.
  - `type` string: STI subclass — the issuing vendor that produced the transaction.
  - `amount_cents` integer: Transaction amount in the merchant currency, in minor units (e.g. cents). **Spends are negative** (`purchase`, `fee`, `fx_fee`, `allocation`); **refunds/reversals/`allocation_release` are positive**.
  - `amount_in_clp` integer: Amount of the transaction in CLP at settlement time. Follows the same sign convention as `amount_cents` (spends negative, refunds positive).
  - `amount_in_limit_currency` integer, nullable: Amount converted to the card's `limit_currency`.
  - `currency` string: Merchant currency in upper-case ISO-4217 (e.g. `USD`, `CLP`).
  - `exchange_rate` string
  - `migrated` boolean, nullable
  - `invoice_id` string, uuid, nullable: UUID of a legacy `Invoice` row (internal billing record kept for backwards compatibility). **Not** a `FiscalInvoice` / SII DTE id — fiscal invoice ids use the composite `<rut>-<document_type>-<number>` string format and are exposed via `GET /v1/fiscal_invoices`, not via this field.
  - `status_reason` string, nullable: Reason of the current transaction status
  - `commission_id` string, uuid, nullable: UUID of the linked commission row, when the transaction accrued a Cardda commission (computed field).
  - `target_amount_cents` integer: Settled amount in the company's accounting currency, in minor units. Follows the same sign convention as `amount_cents` (spends negative, refunds positive).
  - `target_currency` string: Currency the company sees the transaction in (the user's preferred accounting currency), in upper-case ISO-4217.
  - `amount_formatted` string, nullable: UI-ready formatted amount including currency.
  - `target_amount_formatted` string, nullable: UI-ready formatted settled amount including currency.
  - `comments` string, nullable: Free-form internal notes attached by the company.
  - `transaction_labels` object[]: Tags applied to the transaction by the company.
    - `id` string, uuid
    - `label` string
    - `color` string
  - `superseding_transaction_id` string, nullable: When a pending transaction is replaced by the final one, the new id.
  - `superseding_reason` string, nullable: Why the transaction was superseded.
  - `completed_at` string, date-time, nullable: When the transaction was captured/cleared.
  - `settled_at` string, date-time, nullable: When the transaction reached final settlement.
  - `company_id` string, uuid
  - `card` VendorCard
    - `id` string: Card id. Cardda card ids are vendor-prefixed base64-encoded strings (e.g. `Q2FyZDoxMDIwNjQ5Mw==`), not UUIDs.
    - `user_id` string: Firebase user id of the cardholder (not a UUID).
    - `company_id` string, uuid
    - `type` 'AptoCard' | 'BrexCard' | 'Cards::Increase::Card' | 'Cards::Plh::Card' | 'DivvyCard' | 'Issuing::Relay::Card' | 'Issuing::Slash::Card' | 'MercuryCard' | 'MeshCard' | 'PomeloCard' | 'StripeCard': Single Table Inheritance discriminator (issuing vendor / STI sub-class). A persisted column, so it always serializes into the row for **every** caller.
    - `name` string
    - `spending_control_strategy` 'allocation_based' | 'limit_based': How the card limits spend, and therefore which update fields act on it. - `allocation_based` (prepaid): the card spends the funds allocated to it (`allocated_amount`). Configured with `allocated_amount_preference_cents` and the `allocation_*` / `recurring_allocation_amount_cents` fields. - `limit_based`: the card is capped at `limit_amount` per `limit_interval`. Configured with `limit_amount_preference_cents` and `limit_interval_preference`.
    - `last4` string
    - `status` 'active' | 'inactive' | 'pending' | 'canceled'
    - `status_preference` string
    - `migrated` boolean
    - `usage` integer, nullable
    - `limit_amount` MoneyAmount, nullable: Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
      - `amount` string: Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
      - `formatted` string: Human-readable formatted amount including currency symbol.
      - `cents` string: Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
      - `currency_iso` string: ISO 4217 currency code.
    - `limit_interval` 'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time' | 'per_authorization': Current spending limit interval.
    - `limit_amount_preference` MoneyAmount, nullable: Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
      - `amount` string: Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
      - `formatted` string: Human-readable formatted amount including currency symbol.
      - `cents` string: Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
      - `currency_iso` string: ISO 4217 currency code.
    - `limit_interval_preference` 'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time' | 'per_authorization', nullable: Requested spending limit interval.
    - `allocated_amount` MoneyAmount, nullable: Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
      - `amount` string: Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
      - `formatted` string: Human-readable formatted amount including currency symbol.
      - `cents` string: Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
      - `currency_iso` string: ISO 4217 currency code.
    - `allocated_amount_preference` MoneyAmount, nullable: Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
      - `amount` string: Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
      - `formatted` string: Human-readable formatted amount including currency symbol.
      - `cents` string: Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
      - `currency_iso` string: ISO 4217 currency code.
    - `allocation_interval_preference` 'per_transaction' | 'daily' | 'weekly' | 'monthly' | 'yearly', nullable: When the recurring allocation is applied. `daily`, `weekly`, `monthly` and `yearly` reload the card at the start of each period; `per_transaction` reloads it back to `recurring_allocation_amount_cents` after each purchase. Only acts on `allocation_based` cards.
    - `allocation_priority_preference` 'low' | 'mid' | 'high' | 'max', nullable: Priority level for fund allocation across multiple cards.
    - `recurring_allocation_amount_cents` integer, nullable: Recurring allocation amount, in the **minor unit of the card's `limit_currency`** — for a CLP card that is the whole peso (`50000` is $50.000, not $500), for a USD card the cent. See [Amounts and currency](https://docs.cardda.com/docs/amounts-and-currency).
    - `remaining_balance` string, nullable: Actual amount the card can spend right now, as a decimal string in the card's currency (not cents). This is the minimum between the user's spending limit and the company's available balance.
    - `spent` integer
    - `company_expendable_balance_in_limit_currency` string, nullable: Company funds this card can still draw, expressed in the card's `limit_currency`, as a decimal string (a BigDecimal serialized to JSON, not a number). **Show-only** — returned by `GET /v1/vendor_cards/{id}` only, and only when the caller can read the company balance (`policy(company).balance?`). Absent from the list endpoint.
    - `spent_in_interval_with_limit_currency` number, float: Amount spent in the current limit interval, converted to the card's `limit_currency`. Always a number (defaults to `0.0`); never `null`. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
    - `vendor_max_spending_limits` unknown
    - `vendor_max_allocation` MoneyAmount, nullable: Monetary amount. All numeric fields are serialized as strings to preserve precision (BigDecimal).
      - `amount` string: Amount in the main currency unit (e.g., '3000.0' for 3,000 CLP, '176.0' for 176 USD).
      - `formatted` string: Human-readable formatted amount including currency symbol.
      - `cents` string: Amount in the currency's smallest subunit. For CLP (no subunits) this equals the main amount; for USD this is 100× the main amount.
      - `currency_iso` string: ISO 4217 currency code.
    - `non_sensitive_information` object, nullable: Non-sensitive cardholder/configuration attributes (`user_name`, `user_identifier`, `country`, `address`, `postal_code`, `restricted_merchants`, `phone`). Empty object when unavailable. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
    - `last_allocation_transaction_status` string, nullable: Status of the most recent allocation transaction on this card. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
    - `last_allocation_transaction_created_at` string, date-time, nullable: Creation timestamp of the most recent allocation transaction. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
    - `allocation_priority_stats` object, nullable: Total recurring allocation (cents) per priority group across the company's active cards (e.g. `{ "low": 5000000, "mid": 3000000 }`), or `null` for card types that don't compute it. **Show-only** — returned by `GET /v1/vendor_cards/{id}` only.
    - `preference_restricted_spendable` string, nullable: Amount the card can still spend before hitting its configured spending limit, as a decimal string in the card's currency (not cents). Calculated as the spending limit minus amount already spent in the current interval. Unlike `remaining_balance`, this does not consider the company's available funds.
    - `spent_in_interval` number, float
    - `spent_in_vendor_interval` number, float
    - `fees_in_vendor_interval` number, float
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `merchant` Merchant: A merchant (payee) resolved from card transactions. The company's scope is the set of merchants referenced by its ledger transactions.
    - `id` string, uuid
    - `name` string: Normalized merchant name.
    - `image_url` string, nullable: Logo / image URL for the merchant.
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401`: Unauthorized — missing or invalid bearer token, or the caller is not permitted to list card transactions (Pundit authorization failure). Returned with an empty body. Note: the `company-id` header is not required for this endpoint.

---

[API](https://skmtc.dev/cardda/apis/cards-api.md) - [All operations](https://skmtc.dev/cardda/apis/cards-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/cards-api/revisions/c57a213e5752?raw)