> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cartevo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List Customer Cards

> Retrieve every card belonging to a single customer.

## Overview

`GET /customers/{id}/cards` returns all cards owned by the specified customer. Use it instead of [`GET /cards`](/api-reference/endpoint/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

| Name            | Required | Description             |
| --------------- | -------- | ----------------------- |
| `Authorization` | Yes      | `Bearer <access_token>` |

### Path parameters

| Name | Type   | Description         |
| ---- | ------ | ------------------- |
| `id` | string | Customer ID (UUID). |

### Query parameters

| Name   | Type    | Default | Description                                                                                                                             |
| ------ | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `sync` | boolean | `false` | When `true`, refreshes each card's balance and status from the provider before returning (slower). Omit for the cached database values. |

## Response

### 200 — Success

```json theme={null}
{
  "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

| Status | Trigger                                                        |
| ------ | -------------------------------------------------------------- |
| `404`  | The customer has no cards, or does not belong to your company. |

## Code examples

```bash cURL theme={null}
curl "https://api.cartevo.co/api/v1/customers/8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b/cards" \
  -H "Authorization: Bearer $TOKEN"
```

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

## Related

* [`GET /cards`](/api-reference/endpoint/get-cards) — list all cards in your company.
* [`GET /cards/{id}`](/api-reference/endpoint/get-card-by-id) — full details for one card.
* [`GET /customers/{id}/transactions`](/api-reference/endpoint/get-customer-transactions) — all card transactions for the customer.


## OpenAPI

````yaml GET /customers/{id}/cards
openapi: 3.1.0
info:
  title: Cartevo API
  description: Essential endpoints for wallets, transactions, customers and conversion.
  version: 1.0.0
servers:
  - url: https://api.cartevo.co/api/v1
security:
  - bearerAuth: []
paths:
  /customers/{id}/cards:
    get:
      summary: Customer cards
      description: Retrieves all cards belonging to a specific customer.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Customer ID.
        - name: sync
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            When `true`, refreshes each card's balance and status from the
            provider before returning. Slower; omit for the cached database
            values.
      responses:
        '200':
          description: The customer's cards.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/StandardResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Card'
        '404':
          description: Customer has no cards, or does not belong to your company.
components:
  schemas:
    StandardResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        statusCode:
          type: integer
          example: 200
        message:
          type: string
          example: Data retrieved successfully
    Card:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 91b3c6d6-111b-44da-9f81-16f019bebe8c
        customer_id:
          type: string
          format: uuid
          example: 4d4dad81-7899-4612-a9f6-133ce56a4507
        status:
          type: string
          example: ACTIVE
        balance:
          type: number
          example: 5
        masked_pan:
          type: string
          example: '**** **** **** 5407'
        currency:
          type: string
          example: USD
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        is_active:
          type: boolean
          example: true
        is_virtual:
          type: boolean
          example: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````