list customers.md
List Customers
List customers.
Scopes: customers:read customers:write
OpenAPI
openapi: 3.1.0
info:
title: Polar API
summary: Polar HTTP and Webhooks API
description: Read the docs at https://polar.sh/docs/api-reference
version: 2026-04
servers:
- url: https://api.polar.sh
description: Production environment
x-speakeasy-server-id: production
x-polar-environment: production
- url: https://sandbox-api.polar.sh
description: Sandbox environment
x-speakeasy-server-id: sandbox
x-polar-environment: sandbox
security: []
tags:
- name: public
description: >-
Endpoints shown and documented in the Polar API documentation and
available in our SDKs.
- name: private
description: >-
Endpoints that should appear in the schema only in development to generate
our internal JS SDK.
paths:
/v1/customers/:
get:
tags:
- customers
- public
summary: List Customers
description: |-
List customers.
**Scopes**: `customers:read` `customers:write`
operationId: customers:list
parameters:
- name: organization_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid4
description: The organization ID.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
- type: array
items:
type: string
format: uuid4
description: The organization ID.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
- type: 'null'
title: OrganizationID Filter
description: Filter by organization ID.
description: Filter by organization ID.
- name: email
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by exact email.
title: Email
description: Filter by exact email.
- name: query
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by name, email, or external ID.
title: Query
description: Filter by name, email, or external ID.
- name: active
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: >-
Filter by active customers, i.e. customers with at least one
trialing, active or past_due subscription.
title: Active
description: >-
Filter by active customers, i.e. customers with at least one
trialing, active or past_due subscription.
- name: page
in: query
required: false
schema:
type: integer
exclusiveMinimum: 0
description: Page number, defaults to 1.
default: 1
title: Page
description: Page number, defaults to 1.
- name: limit
in: query
required: false
schema:
type: integer
exclusiveMinimum: 0
description: Size of a page, defaults to 10. Maximum is 100.
default: 10
title: Limit
description: Size of a page, defaults to 10. Maximum is 100.
- name: sorting
in: query
required: false
schema:
anyOf:
- type: array
items:
$ref: '#/components/schemas/CustomerSortProperty'
- type: 'null'
description: >-
Sorting criterion. Several criteria can be used simultaneously and
will be applied in order. Add a minus sign `-` before the criteria
name to sort by descending order.
default:
- '-created_at'
title: Sorting
description: >-
Sorting criterion. Several criteria can be used simultaneously and
will be applied in order. Add a minus sign `-` before the criteria
name to sort by descending order.
- name: metadata
in: query
required: false
style: deepObject
schema:
$ref: '#/components/schemas/MetadataQuery'
description: >-
Filter by metadata key-value pairs. It uses the `deepObject` style,
e.g. `?metadata[key]=value`.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ListResource_Customer_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- oidc:
- customers:read
- customers:write
- pat:
- customers:read
- customers:write
- oat:
- customers:read
- customers:write
x-codeSamples:
- lang: python
source: |
from polar.v2026_04 import Polar
polar = Polar("polar_oat_xxx")
for item in polar.customers.iter_list(
page=1,
limit=10,
sorting=["-created_at"],
):
print(item)
- lang: typescript
source: |
import { createPolar } from "@polar-sh/sdk/2026-04";
const polar = createPolar({
accessToken: "polar_oat_xxx",
});
for await (const item of polar.customers.iterList(
{
"page": 1,
"limit": 10,
"sorting": [
"-created_at"
]
},
)) {
console.log(item);
}
components:
schemas:
CustomerSortProperty:
type: string
enum:
- created_at
- '-created_at'
- email
- '-email'
- name
- '-name'
title: CustomerSortProperty
MetadataQuery:
anyOf:
- type: object
additionalProperties:
anyOf:
- type: string
- type: integer
- type: boolean
- items:
type: string
type: array
- type: array
items:
type: integer
- type: array
items:
type: boolean
- type: 'null'
title: MetadataQuery
ListResource_Customer_:
properties:
items:
items:
$ref: '#/components/schemas/Customer'
type: array
title: Items
pagination:
$ref: '#/components/schemas/Pagination'
type: object
required:
- items
- pagination
title: ListResource[Customer]
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
Customer:
oneOf:
- $ref: '#/components/schemas/CustomerIndividual'
- $ref: '#/components/schemas/CustomerTeam'
discriminator:
propertyName: type
mapping:
individual:
$ref: '#/components/schemas/CustomerIndividual'
team:
$ref: '#/components/schemas/CustomerTeam'
Pagination:
properties:
total_count:
type: integer
title: Total Count
max_page:
type: integer
title: Max Page
type: object
required:
- total_count
- max_page
title: Pagination
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
CustomerIndividual:
properties:
id:
type: string
format: uuid4
title: Id
description: The ID of the customer.
examples:
- 992fae2a-2a17-4b7a-8d9e-e287cf90131b
created_at:
type: string
format: date-time
title: Created At
description: Creation timestamp of the object.
examples:
- '2026-01-01T00:00:00.000000Z'
modified_at:
anyOf:
- type: string
format: date-time
examples:
- '2026-01-01T00:00:00.000000Z'
- type: 'null'
title: Modified At
description: Last modification timestamp of the object.
metadata:
$ref: '#/components/schemas/MetadataOutputType'
external_id:
anyOf:
- type: string
- type: 'null'
title: External Id
description: >-
The ID of the customer in your system. This must be unique within
the organization. Once set, it can't be updated.
examples:
- usr_1337
email:
type: string
title: Email
description: >-
The email address of the customer. This must be unique within the
organization.
examples:
- customer@example.com
email_verified:
type: boolean
title: Email Verified
description: >-
Whether the customer email address is verified. The address is
automatically verified when the customer accesses the customer
portal using their email address.
examples:
- true
type:
type: string
const: individual
title: Type
description: The type of customer.
examples:
- individual
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the customer.
examples:
- John Doe
billing_name:
anyOf:
- type: string
- type: 'null'
title: Billing Name
description: >-
The name that should appear on the customer's invoices. Falls back
to the customer name when not explicitly set.
examples:
- John Doe
billing_address:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
tax_id:
anyOf:
- prefixItems:
- type: string
- $ref: '#/components/schemas/TaxIDFormat'
type: array
maxItems: 2
minItems: 2
examples:
- - '911144442'
- us_ein
- - FR61954506077
- eu_vat
- type: 'null'
title: Tax Id
locale:
anyOf:
- type: string
- type: 'null'
title: Locale
organization_id:
type: string
format: uuid4
title: Organization Id
description: The ID of the organization owning the customer.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
default_payment_method_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Default Payment Method Id
description: >-
The ID of the customer's default payment method, if any. Use the
payment methods endpoint to retrieve its details.
deleted_at:
anyOf:
- type: string
format: date-time
examples:
- '2026-01-01T00:00:00.000000Z'
- type: 'null'
title: Deleted At
description: Timestamp for when the customer was soft deleted.
first_user_event_at:
anyOf:
- type: string
format: date-time
examples:
- '2026-01-01T00:00:00.000000Z'
- type: 'null'
title: First User Event At
description: >-
Timestamp of the first event ingested for this customer. Can predate
`created_at`, and is null if no event was ever ingested.
avatar_url:
anyOf:
- type: string
- type: 'null'
title: Avatar Url
examples:
- https://www.gravatar.com/avatar/xxx?d=404
type: object
required:
- id
- created_at
- modified_at
- metadata
- email
- email_verified
- type
- name
- billing_name
- billing_address
- tax_id
- organization_id
- deleted_at
- first_user_event_at
- avatar_url
title: CustomerIndividual
description: A customer in an organization.
CustomerTeam:
properties:
id:
type: string
format: uuid4
title: Id
description: The ID of the customer.
examples:
- 992fae2a-2a17-4b7a-8d9e-e287cf90131b
created_at:
type: string
format: date-time
title: Created At
description: Creation timestamp of the object.
examples:
- '2026-01-01T00:00:00.000000Z'
modified_at:
anyOf:
- type: string
format: date-time
examples:
- '2026-01-01T00:00:00.000000Z'
- type: 'null'
title: Modified At
description: Last modification timestamp of the object.
metadata:
$ref: '#/components/schemas/MetadataOutputType'
external_id:
anyOf:
- type: string
- type: 'null'
title: External Id
description: >-
The ID of the customer in your system. This must be unique within
the organization. Once set, it can't be updated.
examples:
- usr_1337
email:
anyOf:
- type: string
- type: 'null'
title: Email
description: >-
The email address of the customer. This must be unique within the
organization.
examples:
- customer@example.com
email_verified:
type: boolean
title: Email Verified
description: >-
Whether the customer email address is verified. The address is
automatically verified when the customer accesses the customer
portal using their email address.
examples:
- true
type:
type: string
const: team
title: Type
description: The type of customer. Team customers can have multiple members.
examples:
- team
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the customer.
examples:
- John Doe
billing_name:
anyOf:
- type: string
- type: 'null'
title: Billing Name
description: >-
The name that should appear on the customer's invoices. Falls back
to the customer name when not explicitly set.
examples:
- John Doe
billing_address:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
tax_id:
anyOf:
- prefixItems:
- type: string
- $ref: '#/components/schemas/TaxIDFormat'
type: array
maxItems: 2
minItems: 2
examples:
- - '911144442'
- us_ein
- - FR61954506077
- eu_vat
- type: 'null'
title: Tax Id
locale:
anyOf:
- type: string
- type: 'null'
title: Locale
organization_id:
type: string
format: uuid4
title: Organization Id
description: The ID of the organization owning the customer.
examples:
- 1dbfc517-0bbf-4301-9ba8-555ca42b9737
default_payment_method_id:
anyOf:
- type: string
format: uuid4
- type: 'null'
title: Default Payment Method Id
description: >-
The ID of the customer's default payment method, if any. Use the
payment methods endpoint to retrieve its details.
deleted_at:
anyOf:
- type: string
format: date-time
examples:
- '2026-01-01T00:00:00.000000Z'
- type: 'null'
title: Deleted At
description: Timestamp for when the customer was soft deleted.
first_user_event_at:
anyOf:
- type: string
format: date-time
examples:
- '2026-01-01T00:00:00.000000Z'
- type: 'null'
title: First User Event At
description: >-
Timestamp of the first event ingested for this customer. Can predate
`created_at`, and is null if no event was ever ingested.
avatar_url:
anyOf:
- type: string
- type: 'null'
title: Avatar Url
examples:
- https://www.gravatar.com/avatar/xxx?d=404
type: object
required:
- id
- created_at
- modified_at
- metadata
- email_verified
- type
- name
- billing_name
- billing_address
- tax_id
- organization_id
- deleted_at
- first_user_event_at
- avatar_url
title: CustomerTeam
description: A team customer in an organization.
MetadataOutputType:
additionalProperties:
anyOf:
- type: string
- type: integer
- type: number
- type: boolean
type: object
Address:
properties:
line1:
anyOf:
- type: string
- type: 'null'
title: Line1
line2:
anyOf:
- type: string
- type: 'null'
title: Line2
postal_code:
anyOf:
- type: string
- type: 'null'
title: Postal Code
city:
anyOf:
- type: string
- type: 'null'
title: City
state:
anyOf:
- type: string
- type: 'null'
title: State
country:
type: string
enum:
- AD
- AE
- AF
- AG
- AI
- AL
- AM
- AO
- AQ
- AR
- AS
- AT
- AU
- AW
- AX
- AZ
- BA
- BB
- BD
- BE
- BF
- BG
- BH
- BI
- BJ
- BL
- BM
- BN
- BO
- BQ
- BR
- BS
- BT
- BV
- BW
- BY
- BZ
- CA
- CC
- CD
- CF
- CG
- CH
- CI
- CK
- CL
- CM
- CN
- CO
- CR
- CU
- CV
- CW
- CX
- CY
- CZ
- DE
- DJ
- DK
- DM
- DO
- DZ
- EC
- EE
- EG
- EH
- ER
- ES
- ET
- FI
- FJ
- FK
- FM
- FO
- FR
- GA
- GB
- GD
- GE
- GF
- GG
- GH
- GI
- GL
- GM
- GN
- GP
- GQ
- GR
- GS
- GT
- GU
- GW
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IM
- IN
- IO
- IQ
- IR
- IS
- IT
- JE
- JM
- JO
- JP
- KE
- KG
- KH
- KI
- KM
- KN
- KP
- KR
- KW
- KY
- KZ
- LA
- LB
- LC
- LI
- LK
- LR
- LS
- LT
- LU
- LV
- LY
- MA
- MC
- MD
- ME
- MF
- MG
- MH
- MK
- ML
- MM
- MN
- MO
- MP
- MQ
- MR
- MS
- MT
- MU
- MV
- MW
- MX
- MY
- MZ
- NA
- NC
- NE
- NF
- NG
- NI
- NL
- 'NO'
- NP
- NR
- NU
- NZ
- OM
- PA
- PE
- PF
- PG
- PH
- PK
- PL
- PM
- PN
- PR
- PS
- PT
- PW
- PY
- QA
- RE
- RO
- RS
- RU
- RW
- SA
- SB
- SC
- SD
- SE
- SG
- SH
- SI
- SJ
- SK
- SL
- SM
- SN
- SO
- SR
- SS
- ST
- SV
- SX
- SY
- SZ
- TC
- TD
- TF
- TG
- TH
- TJ
- TK
- TL
- TM
- TN
- TO
- TR
- TT
- TV
- TW
- TZ
- UA
- UG
- UM
- US
- UY
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- YE
- YT
- ZA
- ZM
- ZW
title: CountryAlpha2
examples:
- US
- SE
- FR
x-speakeasy-enums:
- AD
- AE
- AF
- AG
- AI
- AL
- AM
- AO
- AQ
- AR
- AS
- AT
- AU
- AW
- AX
- AZ
- BA
- BB
- BD
- BE
- BF
- BG
- BH
- BI
- BJ
- BL
- BM
- BN
- BO
- BQ
- BR
- BS
- BT
- BV
- BW
- BY
- BZ
- CA
- CC
- CD
- CF
- CG
- CH
- CI
- CK
- CL
- CM
- CN
- CO
- CR
- CU
- CV
- CW
- CX
- CY
- CZ
- DE
- DJ
- DK
- DM
- DO
- DZ
- EC
- EE
- EG
- EH
- ER
- ES
- ET
- FI
- FJ
- FK
- FM
- FO
- FR
- GA
- GB
- GD
- GE
- GF
- GG
- GH
- GI
- GL
- GM
- GN
- GP
- GQ
- GR
- GS
- GT
- GU
- GW
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IM
- IN
- IO
- IQ
- IR
- IS
- IT
- JE
- JM
- JO
- JP
- KE
- KG
- KH
- KI
- KM
- KN
- KP
- KR
- KW
- KY
- KZ
- LA
- LB
- LC
- LI
- LK
- LR
- LS
- LT
- LU
- LV
- LY
- MA
- MC
- MD
- ME
- MF
- MG
- MH
- MK
- ML
- MM
- MN
- MO
- MP
- MQ
- MR
- MS
- MT
- MU
- MV
- MW
- MX
- MY
- MZ
- NA
- NC
- NE
- NF
- NG
- NI
- NL
- 'NO'
- NP
- NR
- NU
- NZ
- OM
- PA
- PE
- PF
- PG
- PH
- PK
- PL
- PM
- PN
- PR
- PS
- PT
- PW
- PY
- QA
- RE
- RO
- RS
- RU
- RW
- SA
- SB
- SC
- SD
- SE
- SG
- SH
- SI
- SJ
- SK
- SL
- SM
- SN
- SO
- SR
- SS
- ST
- SV
- SX
- SY
- SZ
- TC
- TD
- TF
- TG
- TH
- TJ
- TK
- TL
- TM
- TN
- TO
- TR
- TT
- TV
- TW
- TZ
- UA
- UG
- UM
- US
- UY
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- YE
- YT
- ZA
- ZM
- ZW
title: Address
securitySchemes:
oidc:
type: openIdConnect
openIdConnectUrl: /.well-known/openid-configuration
pat:
type: http
description: >-
You can generate a **Personal Access Token** from your
[settings](/content/settings/index.html).
scheme: bearer
oat:
type: http
description: >-
You can generate an **Organization Access Token** from your
organization's settings.
scheme: bearer