--- title: "List vendor cards" method: GET path: "/v1/vendor_cards" tags: ["Vendor card"] --- # List vendor cards `GET /v1/vendor_cards` ## Request - Base URL: `https://api.cardda.com` - URL: `https://api.cardda.com/v1/vendor_cards` - Auth: HTTP bearer Returns a paginated list of vendor cards (corporate cards issued by Cardda). Each row in the response represents a single physical or virtual card and exposes its current status, spending limits, balance, and the user it is assigned to. The result is scoped per-caller across every company the caller has permission in (via `policy_scope`), **not** by the `company-id` header — the header is not consulted for this endpoint, and omitting it still returns `200` with the caller's full permitted scope across companies. To narrow the results, filter explicitly; `user_id` is a **cardholder** filter (it returns only cards assigned to that user), not a per-company restriction. - **Admins** see every card in their permitted scope. - **Company members** with the `vendor_cards_manage` permission see every card of the companies they manage. - Regular users see only cards assigned to them (`user_id` matches their Firebase user id). The `type` field (issuing vendor / STI sub-class) is returned to **every** caller: it is the model's Single Table Inheritance discriminator column, so it always serializes into the row (the controller's `methods.push(:type) if admin?` is a no-op — `type` is already a column, not a computed method). ## Response structure Each item is a `VendorCard` plus the following computed fields: | Field | Description | | --- | --- | | `spent` | Amount spent in the current spending interval, as an integer in the minor unit of the transactions' currency (whole pesos for CLP). Sign-flipped from the negative `amount_cents` of the spends. | | `remaining_balance` | Funds still available on the card, as a decimal string in the card currency (not cents). | | `preference_restricted_spendable` | Spendable amount taking active preferences into account. | | `spent_in_vendor_interval` | Amount spent in the vendor's billing interval. | | `fees_in_vendor_interval` | Fees accrued in the vendor's billing interval. | | `limit_amount` | Hard spending limit (`limit_based` strategy). | | `limit_amount_preference` | Pending limit change (waiting to be pushed to the vendor). | | `allocated_amount` | Funds currently loaded onto the card (`allocation_based` strategy). | | `allocated_amount_preference` | Pending allocation change. | ## Filtering grammar Every column documented below accepts the MongoDB-style operators described in [Filters](https://docs.cardda.com/docs/filters): `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$ne`, `$regex`, `$or`. Combine them on a single field (`created_at={"$gte":"2026-01-01T00:00:00Z","$lt":"2026-02-01T00:00:00Z"}`) or across fields (`status=active&user_id=...`). ## Common queries ```bash # Active + inactive + pending cards of a specific user (the dashboard's default) GET /v1/vendor_cards?\ $or=[{"status":"active"},{"status":"inactive"},{"status":"pending"}]&\ user_id=&\ _order=desc&_field=created_at&_start=0&_end=25 # Search by name OR last4 (cardholder lookup) GET /v1/vendor_cards?\ $or=[{"name":{"$regex":"maria"}},{"last4":{"$regex":"^4242"}}]&\ _start=0&_end=50 # Cards assigned to a specific person, with allocation-based control GET /v1/vendor_cards?\ user_id=&\ spending_control_strategy=allocation_based # Cards by id (batch lookup, e.g. to refresh a dashboard view) GET /v1/vendor_cards?id={"$in":["Q2FyZDoxMDIwNjQ5Mw==","Q2FyZDoxMDIwNjQ5NA=="]} ``` ## Query parameters - `id` string - `user_id` string - `status` 'pending' | 'active' | 'inactive' | 'canceled' - `name` string - `last4` string - `physical` boolean - `spending_control_strategy` 'limit_based' | 'allocation_based' - `limit_currency` 'CLP' | 'USD' | 'MXN' | 'PEN' | 'BRL' | 'EUR' - `type` 'PomeloCard' | 'PlhCard' | 'StripeCard' | 'BrexCard' | 'MercuryCard' | 'DivvyCard' | 'MeshCard' | 'AptoCard' | 'IncreaseCard' - `created_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 vendor cards. Headers include `X-Total-Count` and `Content-Range` for offset pagination — see [Pagination](https://docs.cardda.com/docs/pagination). - 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 ## Other responses - `401`: Unauthorized — missing or invalid bearer token, or the caller is not permitted to list vendor cards (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)