---
title: "List customers"
method: GET
path: "/customers"
tags: ["Customers"]
---

# List customers

`GET /customers`

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/customers`
- Auth: HTTP bearer

Returns a paginated list of customers. Use the query parameters to page through results.

By default, Paddle returns customers that are `active`. Use the `status` query parameter to return customers that are archived.

## Query parameters

- `id` string[]
- `after` string
- `per_page` integer
- `email` string[]
- `order_by` string
- `status` StatusQuery[]
- `search` string

## Headers

- `Skip-Count` string

## Response `200`

The request has succeeded.

- object
  - `data` Customer[], required
    - `id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`.
    - `name` string, required: Full name.
    - `email` string, email, required: Email address for this entity.
    - `marketing_consent` boolean, required: Whether this customer opted into marketing from you. `false` unless customers check the marketing consent box when using Paddle Checkout. Set automatically by Paddle.
    - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle.
    - `custom_data` CustomData, required: Your own structured key-value data.
    - `locale` string, required: Valid IETF BCP 47 short form locale tag. If omitted, defaults to `en`.
    - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
    - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
    - `import_meta` object, nullable, required: Import information for this entity. `null` if this entity is not imported.
      - `external_id` string: Reference or identifier for this entity from the provider where it was imported from.
      - `imported_from` string, required: Name of the platform or provider where this entity was imported from.
  - `meta` PaginatedMeta, required: Information about this response.
    - `request_id` string, required: Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
    - `pagination` Pagination, required: Keys used for working with paginated results.
      - `per_page` integer, required: Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
      - `next` string, uri, required: URL containing the query parameters of the original request, along with the `after` parameter that marks the starting point of the next page. Always returned, even if `has_more` is `false`.
      - `has_more` boolean, required: Whether this response has another page.
      - `estimated_total` integer: Estimated number of entities for this response. For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns `100001` to indicate that more than 100,000 entities match. Returns `-1` when counting is skipped or couldn't be calculated. Use `has_more` and `next` to page through all results rather than relying on `estimated_total` for an exact count.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-07-09** (v1) `e1ac347eb3c5`: 1 info
  - added the new optional `header` request parameter `Skip-Count`
- **2026-02-02** (v1) `9ba8be0f2006`: 13 breaking, 1 warning, 29 info
  - for the `query` request parameter `status`, default value `active` was added
  - the `data/items/email` response property's maxLength was unset from `320` for the response status `200`
  - the `data/items/email` response property's minLength was decreased from `1` to `0` for the response status `200`
  - the `data/items/created_at` response's property type changed from `string` to no type, and format from `date-time` to no format for status `200`
  - …39 more
- **2025-04-25** (v1) `c4b1322e66ca`: 1 breaking
  - the response property `meta/pagination/estimated_total` became optional for the status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/customers/get.md)

---

[API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)