List all customers

Retrieve a list of customers for the authenticated workspace.

GET /customers

Ruby

Ruby

require 'dub'

Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Dub.new(
      security: Models::Shared::Security.new(
        token: 'DUB_API_KEY',
      ),
    )

req = Models::Operations::GetCustomersRequest.new(
  page_size: 50.0,
)

res = s.customers.list(request: req)

unless res.nil?
  # handle response
end

200

[
  {
    "id": "<string>",
    "name": "<string>",
    "externalId": "<string>",
    "createdAt": "<string>",
    "email": "<string>",
    "avatar": "<string>",
    "stripeCustomerId": "<string>",
    "country": "<string>",
    "sales": 123,
    "saleAmount": 123,
    "firstSaleAt": "<string>",
    "subscriptionCanceledAt": "<string>",
    "link": {
      "id": "<string>",
      "domain": "<string>",
      "key": "<string>",
      "shortLink": "<string>",
      "url": "<string>",
      "programId": "<string>"
    },
    "programId": "<string>",
    "partner": {
      "id": "<string>",
      "name": "<string>",
      "email": "<string>",
      "image": "<string>"
    },
    "discount": {
      "id": "<string>",
      "amount": 123,
      "type": "percentage",
      "maxDuration": 123,
      "couponId": "<string>",
      "couponTestId": "<string>",
      "description": "<string>",
      "partnersCount": 123
    }
  }
]

Authorizations

Authorization · string · header · required

Default authentication mechanism

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<string> · default: createdAt

The field to sort the customers by. The default is createdAt.

Available options: createdAt, saleAmount, firstSaleAt, subscriptionCanceledAt

sortOrder · enum<string> · default: desc

The sort order. The default is desc.

Available options: asc, desc

page · number · default: 1

The page number for pagination.

Required range: x > 0

Example:

1

pageSize · number · default: 100

The number of items per page.

Required range: 0 < x <= 100

Example:

50

Response

200

application/json

The list of customers.

id · string · required

The unique ID of the customer. You may use either the customer's id on Dub (obtained via /customers endpoint) or their externalId (unique ID within your system, prefixed with ext_, e.g. ext_123).

name · string · required

Name of the customer.

externalId · string · required

Unique identifier for the customer in the client's app.

createdAt · string · required

The date the customer was created (usually the signup date or trial start date).

email · string | null

Email of the customer.

avatar · string | null

Avatar URL of the customer.

stripeCustomerId · string | null

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

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.

firstSaleAt · string | null

The date the customer made their first sale. Useful for calculating the time to first sale and LTV.

subscriptionCanceledAt · string | null

The date the customer canceled their subscription. Useful for calculating LTV and churn rate.

link · object

Show child attributes

programId · string | null

partner · object

Show child attributes

discount · object

Show child attributes