Skip to main content

​
Endpoint

​
method
string
GET
​
url
string
https://api.dub.co/customers

​
Authentication

This endpoint requires authentication using a Bearer token. 
Authorization: Bearer DUB_API_KEY

​
Query Parameters

​
email
string
A case-sensitive filter on the list based on the customer’s email field. The value must be a string. Takes precedence over externalId.
​
externalId
string
A case-sensitive filter on the list based on the customer’s externalId field. The value must be a string. Takes precedence over search.
​
search
string
A search query to filter customers by email, externalId, or name. If email or externalId is provided, this will be ignored.
​
country
string
A filter on the list based on the customer’s country field.
​
linkId
string
A filter on the list based on the customer’s linkId field (the referral link ID).
​
programId
string
Program ID to filter by.
​
partnerId
string
Partner ID to filter by.
​
includeExpandedFields
boolean
Whether to include expanded fields on the customer (link, partner, discount).
​
sortBy
enum
default:"createdAt"
The field to sort the customers by.Options: createdAt, saleAmount, firstSaleAt, subscriptionCanceledAt
​
sortOrder
enum
default:"desc"
The sort order.Options: asc, desc
​
page
number
default:"1"
The page number for pagination.
​
pageSize
number
default:"50"
The number of items per page. Maximum: 100

​
Response

Returns an array of customer objects.
​
id
string
The unique ID of the customer
​
name
string
Name of the customer
​
email
string | null
Email of the customer
​
avatar
string | null
Avatar URL of the customer
​
externalId
string
Unique identifier for the customer in the client’s app
​
stripeCustomerId
string | null
The customer’s Stripe customer ID
​
country
string | null
Country of the customer
​
sales
number | null
Total number of sales for the customer
​
saleAmount
number | null
Total amount of sales for the customer
​
createdAt
string
The date the customer was created
​
firstSaleAt
string | null
The date the customer made their first sale
​
subscriptionCanceledAt
string | null
The date the customer canceled their subscription

​
Examples

curl -X GET https://api.dub.co/customers \
  -H "Authorization: Bearer DUB_API_KEY"

​
Response Example

[
  {
    "id": "cus_xyz123",
    "name": "John Doe",
    "email": "john@example.com",
    "avatar": "https://example.com/avatar.jpg",
    "externalId": "user_123456",
    "stripeCustomerId": "cus_stripe123",
    "country": "US",
    "sales": 3,
    "saleAmount": 14997,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "firstSaleAt": "2024-01-20T14:22:00.000Z",
    "subscriptionCanceledAt": null
  },
  {
    "id": "cus_abc456",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "avatar": null,
    "externalId": "user_789012",
    "stripeCustomerId": null,
    "country": "CA",
    "sales": 1,
    "saleAmount": 2999,
    "createdAt": "2024-01-16T08:15:00.000Z",
    "firstSaleAt": "2024-01-18T11:30:00.000Z",
    "subscriptionCanceledAt": null
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us