> ## 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 Transactions

> Retrieve all card-related transactions for a single customer across every card they hold.

## Overview

`GET /customers/{id}/transactions` returns the union of card transactions across **every card** owned by the specified customer — fundings, withdrawals, merchant authorizations, settlements, refunds, and cross-border charges. The response is paginated.

To filter to a single card, use [`GET /cards/{id}/transactions`](/api-reference/endpoint/get-card-transactions) instead.

## When to use it

* Render a customer's full activity timeline.
* Compute a customer's total spend across all their cards.
* Audit a customer for unusual activity.

## 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                 |
| ------- | ------- | ------- | --------------------------- |
| `page`  | integer | `1`     | 1-indexed page number.      |
| `limit` | integer | `10`    | Items per page (max \~100). |

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "12 items retrieved successfully",
  "data": [
    {
      "id": "txn_3f8a9b2c4d6e7f8a9b0c1d2e",
      "category": "CARD",
      "type": "AUTHORIZATION",
      "status": "SUCCESS",
      "amount": 12.5,
      "currency": "USD",
      "description": "Amazon.com - Seattle, US",
      "created_at": "2026-05-09T09:42:11.123Z",
      "card": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "masked_pan": "**** **** **** 1111",
        "brand": "VISA"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 12,
    "totalPages": 2
  }
}
```

The per-transaction shape matches [`GET /cards/{id}/transactions`](/api-reference/endpoint/get-card-transactions) — see that page for a full field reference. The only difference is the `customer` block is not included (you already know which customer you queried).

### Error responses

| Status | Trigger                                                |
| ------ | ------------------------------------------------------ |
| `404`  | Customer does not exist or belongs to another company. |

## Code examples

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

## Related

* [`GET /cards/{id}/transactions`](/api-reference/endpoint/get-card-transactions) — same data filtered to a single card.
* [Webhooks → Transaction events](/api-reference/endpoint/webhook#transaction-events) — receive new transactions in real time.


## OpenAPI

````yaml GET /customers/{id}/transactions
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}/transactions:
    get:
      summary: Customer transactions
      description: Retrieves a list of all transactions for a specific customer.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          schema:
            type: integer
            example: 1
        - name: limit
          in: query
          schema:
            type: integer
            example: 20
      responses:
        '200':
          description: A list of transactions for the specified customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCardTransactionsResponse'
        '404':
          description: Customer not found.
components:
  schemas:
    ListCardTransactionsResponse:
      allOf:
        - $ref: '#/components/schemas/StandardResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/CardTransaction'
            pagination:
              $ref: '#/components/schemas/Pagination'
    StandardResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        statusCode:
          type: integer
          example: 200
        message:
          type: string
          example: Data retrieved successfully
    CardTransaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 7d1cdfa3-9904-4a17-bce5-092554170c0e
        category:
          type: string
          example: CARD
        type:
          type: string
          example: FUND
        amount:
          type: number
          example: 50
        status:
          type: string
          example: SUCCESS
        description:
          type: string
          example: 'Card funding: **** **** **** 5407'
        created_at:
          type: string
          format: date-time
        card:
          $ref: '#/components/schemas/CardDetails'
        customer:
          $ref: '#/components/schemas/CustomerSummary'
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 15
        totalPages:
          type: integer
          example: 1
    CardDetails:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 91b3c6d6-111b-44da-9f81-16f019bebe8c
        status:
          type: string
          example: ACTIVE
        balance:
          type: number
          example: 0.45
        currency:
          type: string
          example: USD
        number:
          type: string
          description: Encrypted card number
          example: >-
            tkAlsp_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YWx1ZSI6IjUzNjAyNTI0ODM0NjU0MDciLCJpYXQiOjE3NjExNDg5NzR9.7sNid1b1pxmkpseiCR45E8Xj9hdmenZDovBcjVatBF0
        masked_pan:
          type: string
          example: '**** **** **** 5407'
        cvv:
          type: string
          description: Encrypted CVV
          example: >-
            tkAlsp_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YWx1ZSI6Ijg1NyIsImlhdCI6MTc2MTE0ODk3NH0.K7YHl0nzZTsScjUma_G5fyxYZFNnK-2SczstVtdMK1A
        expiry_month:
          type: integer
          example: 10
        expiry_year:
          type: integer
          example: 28
        is_virtual:
          type: boolean
          example: true
        is_physical:
          type: boolean
          example: false
        created_at:
          type: string
          format: date-time
    CustomerSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 4d4dad81-7899-4612-a9f6-133ce56a4507
        email:
          type: string
          format: email
          example: customer@example.com
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````