Dub Customers API
The Customers API from Dub — 2 operation(s) for customers.
OpenAPI Specification
openapi: 3.0.3
info:
title: Dub Analytics Customers API
description: Dub is the modern link attribution platform for short links, conversion tracking, and affiliate programs.
version: 0.0.1
contact:
name: Dub Support
email: support@dub.co
url: https://dub.co/support
license:
name: AGPL-3.0 license
url: https://github.com/dubinc/dub/blob/main/LICENSE.md
servers:
- url: https://api.dub.co
description: Production API
tags:
- name: Customers
paths:
/customers:
get:
operationId: getCustomers
x-speakeasy-name-override: list
x-speakeasy-pagination:
type: cursor
inputs:
- name: startingAfter
in: parameters
type: cursor
outputs:
nextCursor: $[-1].id
summary: List all customers
description: Retrieve a paginated list of customers for the authenticated workspace.
tags:
- Customers
security:
- token: []
parameters:
- in: query
name: email
schema:
description: A case-sensitive filter on the list based on the customer's `email` field. The value must be a string. Takes precedence over `externalId`.
type: string
description: A case-sensitive filter on the list based on the customer's `email` field. The value must be a string. Takes precedence over `externalId`.
- in: query
name: externalId
schema:
description: A case-sensitive filter on the list based on the customer's `externalId` field. The value must be a string. Takes precedence over `search`.
type: string
description: A case-sensitive filter on the list based on the customer's `externalId` field. The value must be a string. Takes precedence over `search`.
- in: query
name: search
schema:
description: A search query to filter customers by email, externalId, or name. If `email` or `externalId` is provided, this will be ignored.
type: string
description: A search query to filter customers by email, externalId, or name. If `email` or `externalId` is provided, this will be ignored.
- in: query
name: country
schema:
description: A filter on the list based on the customer's `country` field.
type: string
description: A filter on the list based on the customer's `country` field.
- in: query
name: linkId
schema:
description: A filter on the list based on the customer's `linkId` field (the referral link ID).
type: string
description: A filter on the list based on the customer's `linkId` field (the referral link ID).
- in: query
name: programId
schema:
description: Program ID to filter by.
type: string
description: Program ID to filter by.
- in: query
name: partnerId
schema:
description: Partner ID to filter by.
type: string
description: Partner ID to filter by.
- in: query
name: includeExpandedFields
schema:
description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`).
type: boolean
description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`).
- in: query
name: sortBy
schema:
default: createdAt
description: The field to sort the customers by. The default is `createdAt`.
type: string
enum:
- createdAt
- saleAmount
- firstSaleAt
- subscriptionCanceledAt
description: The field to sort the customers by. The default is `createdAt`.
- in: query
name: sortOrder
schema:
default: desc
description: The sort order. The default is `desc`.
type: string
enum:
- asc
- desc
description: The sort order. The default is `desc`.
- in: query
name: endingBefore
schema:
description: If specified, the query only searches for results before this cursor. Mutually exclusive with `startingAfter`.
example: cus_1KAP4CDPBSVMMBMH9XX3YZZ0Z
type: string
description: If specified, the query only searches for results before this cursor. Mutually exclusive with `startingAfter`.
- in: query
name: startingAfter
schema:
description: If specified, the query only searches for results after this cursor. Mutually exclusive with `endingBefore`.
example: cus_1KAP4CDPBSVMMBMH9XX3YZZ0Z
type: string
description: If specified, the query only searches for results after this cursor. Mutually exclusive with `endingBefore`.
- in: query
name: page
schema:
description: DEPRECATED. Use `startingAfter` instead.
example: 1
deprecated: true
type: number
minimum: 0
exclusiveMinimum: true
description: DEPRECATED. Use `startingAfter` instead.
- in: query
name: pageSize
schema:
default: 100
description: The number of items per page.
example: 50
type: number
minimum: 0
exclusiveMinimum: true
maximum: 100
description: The number of items per page.
responses:
'200':
description: The list of customers.
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: 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:
description: Name of the customer.
nullable: true
type: string
email:
description: Email of the customer.
nullable: true
type: string
avatar:
description: Avatar URL of the customer.
nullable: true
type: string
externalId:
type: string
description: Unique identifier for the customer in the client's app.
stripeCustomerId:
description: The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.
nullable: true
type: string
country:
description: Country of the customer.
nullable: true
type: string
sales:
description: Total number of sales for the customer.
nullable: true
type: number
saleAmount:
description: Total amount of sales for the customer.
nullable: true
type: number
createdAt:
description: The date the customer was created (usually the signup date or trial start date).
type: string
firstSaleAt:
description: The date the customer made their first sale. Useful for calculating the time to first sale and LTV.
nullable: true
type: string
subscriptionCanceledAt:
description: The date the customer canceled their subscription. Useful for calculating LTV and churn rate.
nullable: true
type: string
link:
nullable: true
type: object
properties:
id:
type: string
description: The unique ID of the short link.
domain:
type: string
description: 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).
key:
type: string
description: The short link slug. If not provided, a random 7-character slug will be generated.
shortLink:
type: string
format: uri
description: The full URL of the short link, including the https protocol (e.g. `https://dub.sh/try`).
url:
type: string
format: uri
description: The destination URL of the short link.
programId:
nullable: true
description: The ID of the program the short link is associated with.
type: string
required:
- id
- domain
- key
- shortLink
- url
- programId
additionalProperties: false
programId:
nullable: true
type: string
partner:
nullable: true
type: object
properties:
id:
type: string
description: The partner's unique ID on Dub.
name:
type: string
maxLength: 190
description: The partner's full legal name.
email:
nullable: true
description: The partner's email address. Should be a unique value across Dub.
type: string
maxLength: 190
image:
nullable: true
description: The partner's avatar image.
type: string
required:
- id
- name
- email
- image
additionalProperties: false
discount:
nullable: true
type: object
properties:
id:
type: string
amount:
type: number
type:
type: string
enum:
- percentage
- flat
maxDuration:
nullable: true
type: number
couponId:
nullable: true
type: string
couponTestId:
nullable: true
type: string
description:
nullable: true
type: string
partnersCount:
nullable: true
type: number
required:
- id
- amount
- type
- maxDuration
- couponId
- couponTestId
additionalProperties: false
required:
- id
- externalId
- createdAt
additionalProperties: false
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
/customers/{id}:
get:
operationId: getCustomer
x-speakeasy-name-override: get
summary: Retrieve a customer
description: Retrieve a customer by ID for the authenticated workspace. To retrieve a customer by external ID, prefix the ID with `ext_`.
tags:
- Customers
security:
- token: []
parameters:
- in: path
name: id
schema:
type: string
description: 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`).
required: true
description: 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`).
- in: query
name: includeExpandedFields
schema:
description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`).
type: boolean
description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`).
responses:
'200':
description: The customer object.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: 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:
description: Name of the customer.
nullable: true
type: string
email:
description: Email of the customer.
nullable: true
type: string
avatar:
description: Avatar URL of the customer.
nullable: true
type: string
externalId:
type: string
description: Unique identifier for the customer in the client's app.
stripeCustomerId:
description: The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.
nullable: true
type: string
country:
description: Country of the customer.
nullable: true
type: string
sales:
description: Total number of sales for the customer.
nullable: true
type: number
saleAmount:
description: Total amount of sales for the customer.
nullable: true
type: number
createdAt:
description: The date the customer was created (usually the signup date or trial start date).
type: string
firstSaleAt:
description: The date the customer made their first sale. Useful for calculating the time to first sale and LTV.
nullable: true
type: string
subscriptionCanceledAt:
description: The date the customer canceled their subscription. Useful for calculating LTV and churn rate.
nullable: true
type: string
link:
nullable: true
type: object
properties:
id:
type: string
description: The unique ID of the short link.
domain:
type: string
description: 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).
key:
type: string
description: The short link slug. If not provided, a random 7-character slug will be generated.
shortLink:
type: string
format: uri
description: The full URL of the short link, including the https protocol (e.g. `https://dub.sh/try`).
url:
type: string
format: uri
description: The destination URL of the short link.
programId:
nullable: true
description: The ID of the program the short link is associated with.
type: string
required:
- id
- domain
- key
- shortLink
- url
- programId
additionalProperties: false
programId:
nullable: true
type: string
partner:
nullable: true
type: object
properties:
id:
type: string
description: The partner's unique ID on Dub.
name:
type: string
maxLength: 190
description: The partner's full legal name.
email:
nullable: true
description: The partner's email address. Should be a unique value across Dub.
type: string
maxLength: 190
image:
nullable: true
description: The partner's avatar image.
type: string
required:
- id
- name
- email
- image
additionalProperties: false
discount:
nullable: true
type: object
properties:
id:
type: string
amount:
type: number
type:
type: string
enum:
- percentage
- flat
maxDuration:
nullable: true
type: number
couponId:
nullable: true
type: string
couponTestId:
nullable: true
type: string
description:
nullable: true
type: string
partnersCount:
nullable: true
type: number
required:
- id
- amount
- type
- maxDuration
- couponId
- couponTestId
additionalProperties: false
required:
- id
- externalId
- createdAt
additionalProperties: false
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
patch:
operationId: updateCustomer
x-speakeasy-name-override: update
x-speakeasy-max-method-params: 2
summary: Update a customer
description: Update a customer for the authenticated workspace.
tags:
- Customers
security:
- token: []
parameters:
- in: path
name: id
schema:
type: string
description: 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`).
required: true
description: 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`).
- in: query
name: includeExpandedFields
schema:
description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`).
type: boolean
description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`).
requestBody:
content:
application/json:
schema:
type: object
properties:
email:
description: The customer's email address.
nullable: true
type: string
format: email
pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
name:
description: The customer's name. If not provided, the email address will be used, and if email is not provided, a random name will be generated.
nullable: true
type: string
avatar:
description: The customer's avatar URL. If not provided, a random avatar will be generated.
nullable: true
type: string
format: uri
externalId:
type: string
description: The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.
stripeCustomerId:
description: The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.
nullable: true
type: string
country:
type: string
description: The customer's country in ISO 3166-1 alpha-2 format. Updating this field will only affect the customer's country in Dub's system (and has no effect on existing conversion events).
responses:
'200':
description: The customer was updated.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: 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:
description: Name of the customer.
nullable: true
type: string
email:
description: Email of the customer.
nullable: true
type: string
avatar:
description: Avatar URL of the customer.
nullable: true
type: string
externalId:
type: string
description: Unique identifier for the customer in the client's app.
stripeCustomerId:
description: The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.
nullable: true
type: string
country:
description: Country of the customer.
nullable: true
type: string
sales:
description: Total number of sales for the customer.
nullable: true
type: number
saleAmount:
description: Total amount of sales for the customer.
nullable: true
type: number
createdAt:
description: The date the customer was created (usually the signup date or trial start date).
type: string
firstSaleAt:
description: The date the customer made their first sale. Useful for calculating the time to first sale and LTV.
nullable: true
type: string
subscriptionCanceledAt:
description: The date the customer canceled their subscription. Useful for calculating LTV and churn rate.
nullable: true
type: string
link:
nullable: true
type: object
properties:
id:
type: string
description: The unique ID of the short link.
domain:
type: string
description: 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).
key:
type: string
description: The short link slug. If not provided, a random 7-character slug will be generated.
shortLink:
type: string
format: uri
description: The full URL of the short link, including the https protocol (e.g. `https://dub.sh/try`).
url:
type: string
format: uri
description: The destination URL of the short link.
programId:
nullable: true
description: The ID of the program the short link is associated with.
type: string
required:
- id
- domain
- key
- shortLink
- url
- programId
additionalProperties: false
programId:
nullable: true
type: string
partner:
nullable: true
type: object
properties:
id:
type: string
description: The partner's unique ID on Dub.
name:
type: string
maxLength: 190
description: The partner's full legal name.
email:
nullable: true
description: The partner's email address. Should be a unique value across Dub.
type: string
maxLength: 190
image:
nullable: true
description: The partner's avatar image.
type: string
required:
- id
- name
- email
- image
additionalProperties: false
discount:
nullable: true
type: object
properties:
id:
type: string
amount:
type: number
type:
type: string
enum:
- percentage
- flat
maxDuration:
nullable: true
type: number
couponId:
nullable: true
type: string
couponTestId:
nullable: true
type: string
description:
nullable: true
type: string
partnersCount:
nullable: true
type: number
required:
- id
- amount
- type
- maxDuration
- couponId
- couponTestId
additionalProperties: false
required:
- id
- externalId
- createdAt
additionalProperties: false
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
delete:
operationId: deleteCustomer
x-speakeasy-name-override: delete
x-speakeasy-max-method-params: 1
summary: Delete a customer
description: Delete a customer from a workspace.
tags:
- Customers
security:
- token: []
parameters:
- in: path
name: id
schema:
type: string
description: 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`).
required: true
description: 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`).
responses:
'200':
description: The customer was deleted.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: 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`).
required:
- id
additionalProperties: false
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/c
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dub/refs/heads/main/openapi/dub-customers-api-openapi.yml