Skip to main content

​
Endpoint

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

​
Authentication

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

​
Path Parameters

​
id
string
required
The unique ID of the customer. You may use either:
  • The customer’s id on Dub (obtained via /customers endpoint)
  • Their externalId (unique ID within your system, prefixed with ext_, e.g. ext_user_123456)

​
Query Parameters

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

​
Request Body

All fields are optional. Only include the fields you want to update.
​
email
string
The customer’s email address.
​
name
string
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.
​
avatar
string
The customer’s avatar URL. If not provided, a random avatar will be generated.
​
externalId
string
The customer’s unique identifier in your database. This is useful for associating subsequent conversion events from Dub’s API to your internal systems.
​
stripeCustomerId
string
The customer’s Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.
​
country
string
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).

​
Response

Returns the updated customer object.
​
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 PATCH https://api.dub.co/customers/cus_xyz123 \
  -H "Authorization: Bearer DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "[email protected]",
    "country": "US"
  }'

​
Response Example

{
  "id": "cus_xyz123",
  "name": "John Smith",
  "email": "[email protected]",
  "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
}

Build docs developers (and LLMs) love

Get started for freeTalk to us