List vendor cards
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: $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
# 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=<firebase_uid>&\
_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=<firebase_uid>&\
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=="]}
Request
- Base URLhttps://api.cardda.com
- URLhttps://api.cardda.com/v1/vendor_cards
- AuthHTTP bearer
Query parameters
Filter by card id. Cardda card ids are base64-encoded vendor identifiers. Use id={"$in":["...", "..."]} for batch lookups.
Firebase user id of the cardholder.
Lifecycle status of the card. The most common production query is $or=[{"status":"active"},{"status":"inactive"},{"status":"pending"}] to exclude canceled cards from a dashboard.
Free-form label assigned by the company (e.g. "Sales — María Pérez"). Most clients combine this with last4 via $or for cardholder lookup.
Last four digits of the PAN. Accepts a plain 4-digit string for exact match (e.g. 4242) or a JSON-encoded operator object for prefix / regex search (e.g. {"$regex":"^42"}). No length constraint is set on the schema so both forms validate against codegen clients.
Whether the card has a physical companion. true for plastic, false for virtual-only.
How the card limits spend.
- limit_based — capped at limit_amount per limit_interval (daily / weekly / monthly / etc.).
- allocation_based — funded with allocated_amount; declines when funds run out (no per-interval limit).
ISO-4217 code of the limit currency.
Issuing vendor (STI sub-class). Useful when filtering by issuing partner — most companies will only see one or two values here.
Creation timestamp. Accepts comparators ($gte, $lt) and $in via a JSON-encoded operator object, or a single ISO-8601 date-time string. Schema is type: string (no format) so both forms validate.
Logical OR across sub-conditions. Used by the dashboard to paint "all-non-closed" feeds: $or=[{"status":"active"},{"status":"inactive"},{"status":"pending"}].
Parameters
Response
Paginated list of vendor cards. Headers include X-Total-Count and Content-Range for offset pagination — see Pagination.
Example response
[
{
"id": "Q2FyZDoxMDIwNjQ5Mw==",
"user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2",
"type": "PomeloCard",
"name": "AWS",
"spending_control_strategy": "allocation_based",
"last4": "4163",
"status_preference": "inactive",
"migrated": true,
"limit_amount": {
"amount": "3000.0",
"formatted": "$3.000 CLP",
"cents": "3000.0",
"currency_iso": "CLP"
},
"limit_interval": "daily",
"limit_amount_preference": {
"amount": "3000.0",
"formatted": "$3.000 CLP",
"cents": "3000.0",
"currency_iso": "CLP"
},
"allocated_amount": {
"amount": "3000.0",
"formatted": "$3.000 CLP",
"cents": "3000.0",
"currency_iso": "CLP"
},
"allocated_amount_preference": {
"amount": "3000.0",
"formatted": "$3.000 CLP",
"cents": "3000.0",
"currency_iso": "CLP"
},
"recurring_allocation_amount_cents": 50000,
"remaining_balance": "2000.0",
"spent": 472025,
"company_expendable_balance_in_limit_currency": "3200000.0",
"spent_in_interval_with_limit_currency": 472025,
"vendor_max_allocation": {
"amount": "3000.0",
"formatted": "$3.000 CLP",
"cents": "3000.0",
"currency_iso": "CLP"
},
"preference_restricted_spendable": "2000.0",
"spent_in_interval": 472025,
"spent_in_vendor_interval": 472025
}
]Changes
No recorded changes to this operation across all 1 revision of this API.