List all customers

Retrieve a paginated list of customers for the authenticated workspace.

1 min read

get/customers

Request example

from dub import Dub


with Dub(
    token="DUB_API_KEY",
) as d_client:

    res = d_client.customers.list(request={
        "ending_before": "cus_1KAP4CDPBSVMMBMH9XX3YZZ0Z",
        "starting_after": "cus_1KAP4CDPBSVMMBMH9XX3YZZ0Z",
        "page": 1,
        "page_size": 50,
    })

    while res is not None:
        # Handle items

        res = res.next()

Response

[
  {
    "id": "<string>",
    "name": "<string>",
    "email": "<string>",
    "avatar": "<string>",
    "externalId": "<string>",
    "stripeCustomerId": "<string>",
    "country": "<string>",
    "sales": 1,
    "saleAmount": 1,
    "createdAt": "<string>",
    "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": 1,
      "type": "percentage",
      "maxDuration": 1,
      "couponId": "<string>",
      "couponTestId": "<string>",
      "description": "<string>",
      "partnersCount": 1
    }
  }
]

get/customers

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Query parameters

emailstring#

A case-sensitive filter on the list based on the customer's email field. The value must be a string. Takes precedence over externalId.

externalIdstring#

A case-sensitive filter on the list based on the customer's externalId field. The value must be a string. Takes precedence over search.

searchstring#

A search query to filter customers by email, externalId, or name. If email or externalId is provided, this will be ignored.

countrystring#

A filter on the list based on the customer's country field.

linkIdstring#

A filter on the list based on the customer's linkId field (the referral link ID).

programIdstring#

Program ID to filter by.

partnerIdstring#

Partner ID to filter by.

includeExpandedFieldsboolean#

Whether to include expanded fields on the customer (link, partner, discount).

sortByenum<string>#

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

Default: "createdAt"

Options:createdAtsaleAmountfirstSaleAtsubscriptionCanceledAt

sortOrderenum<string>#

The sort order. The default is desc.

Default: "desc"

Options:ascdesc

endingBeforestring#

If specified, the query only searches for results before this cursor. Mutually exclusive with startingAfter.

startingAfterstring#

If specified, the query only searches for results after this cursor. Mutually exclusive with endingBefore.

pageintegerdeprecated#

DEPRECATED. Use startingAfter instead.

Range: true < x <= 9007199254740991

pageSizeinteger#

The number of items per page.

Default: 100

Range: true < x <= 100

Responses

application/json

The list of customers.

idstringrequired#

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).

namestring#

Name of the customer.

emailstring#

Email of the customer.

avatarstring#

Avatar URL of the customer.

externalIdstringrequired#

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

stripeCustomerIdstring#

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

countrystring#

Country of the customer.

salesnumber#

Total number of sales for the customer.

saleAmountnumber#

Total amount of sales for the customer.

createdAtstringrequired#

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

firstSaleAtstring#

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

subscriptionCanceledAtstring#

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

linkobject#

Show child attributes

idstringrequired#

The unique ID of the short link.

domainstringrequired#

The domain of the short link. If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains).

keystringrequired#

The short link slug. If not provided, a random 7-character slug will be generated.

shortLinkstringrequired#

The full URL of the short link, including the https protocol (e.g. https://dub.sh/try).

urlstringrequired#

The destination URL of the short link.

programIdstringrequired#

The ID of the program the short link is associated with.

programIdstring#

partnerobject#

Show child attributes

idstringrequired#

The partner's unique ID on Dub.

namestringrequired#

The partner's full legal name.

Length: max 190

emailstringrequired#

The partner's email address. Should be a unique value across Dub.

Length: max 190

imagestringrequired#

The partner's avatar image.

discountobject#

Show child attributes

idstringrequired#

amountnumberrequired#

typeenum<string>required#

Options:percentageflat

maxDurationnumberrequired#

couponIdstringrequired#

couponTestIdstringrequired#

descriptionstring#

partnersCountnumber#

Retrieve customer Update customer