Skip to main content
GET
/
customers
/
{id}
/
cards
Customer cards
curl --request GET \
  --url https://api.cartevo.co/api/v1/customers/{id}/cards \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": [
    {
      "id": "91b3c6d6-111b-44da-9f81-16f019bebe8c",
      "customer_id": "4d4dad81-7899-4612-a9f6-133ce56a4507",
      "status": "ACTIVE",
      "balance": 5,
      "masked_pan": "**** **** **** 5407",
      "currency": "USD",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "is_active": true,
      "is_virtual": true
    }
  ]
}

​
Overview

GET /customers/{id}/cards returns all cards owned by the specified customer. Use it instead of GET /cards (which lists every card in your company) when you only want one customer’s cards — there is no customer_id filter on the company-wide list.

​
When to use it

  • Show a customer’s cards on their profile.
  • Check how many cards a customer holds before issuing another.

​
Prerequisites

  • The customer must belong to your company.

​
Request

​
Headers

NameRequiredDescription
AuthorizationYesBearer <access_token>

​
Path parameters

NameTypeDescription
idstringCustomer ID (UUID).

​
Query parameters

NameTypeDefaultDescription
syncbooleanfalseWhen true, refreshes each card’s balance and status from the provider before returning (slower). Omit for the cached database values.

​
Response

​
200 — Success

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
      "status": "ACTIVE",
      "balance": 100.0,
      "masked_number": "4111********1111",
      "brand": "VISA",
      "currency": "USD",
      "created_at": "2026-05-09T10:15:00.000Z"
    }
  ]
}
data is an array of the customer’s cards. An empty list is returned as 404 (no cards found for the customer).

​
Error responses

StatusTrigger
404The customer has no cards, or does not belong to your company.

​
Code examples

cURL
curl "https://api.cartevo.co/api/v1/customers/8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b/cards" \
  -H "Authorization: Bearer $TOKEN"
cURL (with provider sync)
curl "https://api.cartevo.co/api/v1/customers/8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b/cards?sync=true" \
  -H "Authorization: Bearer $TOKEN"

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string<uuid>
required

Customer ID.

Query Parameters

​
sync
boolean

When true, refreshes each card's balance and status from the provider before returning. Slower; omit for the cached database values.

Response

The customer's cards.

​
success
boolean
Example:

true

​
statusCode
integer
Example:

200

​
message
string
Example:

"Data retrieved successfully"

​
data
object[]