Skip to main content

​
Endpoint

​
method
string
POST
​
url
string
https://api.dub.co/track/sale

​
Authentication

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

​
Request Body

​
customerExternalId
string
required
The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.Maximum length: 100 characters
​
amount
number
required
The amount of the sale in cents (for all two-decimal currencies). If the sale is in a zero-decimal currency, pass the full integer value (e.g. 1437 JPY).Must be a non-negative integer.Learn more about currency handling
​
currency
string
default:"usd"
The currency of the sale. Accepts ISO 4217 currency codes. Sales will be automatically converted and stored as USD at the latest exchange rates.Learn more about currency handling
​
eventName
string
default:"Purchase"
The name of the sale event. Recommended format: Invoice paid or Subscription created.Maximum length: 255 charactersExample: Invoice paid
​
paymentProcessor
enum
default:"custom"
The payment processor via which the sale was made.Options: stripe, shopify, polar, paddle, revenuecat, custom
​
invoiceId
string
The invoice ID of the sale. Can be used as an idempotency key – only one sale event can be recorded for a given invoice ID.
​
metadata
object
Additional metadata to be stored with the sale event. Max 10,000 characters when stringified.
​
leadEventName
string
The name of the lead event that occurred before the sale (case-sensitive). This is used to associate the sale event with a particular lead event (instead of the latest lead event for a link-customer combination, which is the default behavior).For direct sale tracking, this field can also be used to specify the lead event name.Example: Cloned template 1481267
​
clickId
string
[For direct sale tracking]: The unique ID of the click that the sale conversion event is attributed to. You can read this value from dub_id cookie.
​
customerName
string
[For direct sale tracking]: The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”).Maximum length: 100 characters
​
customerEmail
string
[For direct sale tracking]: The email address of the customer.Maximum length: 100 characters
​
customerAvatar
string
[For direct sale tracking]: The avatar URL of the customer.

​
Response

​
eventName
string
The name of the sale event
​
customer
object | null
​
id
string
The unique ID of the customer
​
name
string | null
The name of the customer
​
email
string | null
The email of the customer
​
avatar
string | null
The avatar URL of the customer
​
externalId
string | null
The external ID of the customer
​
sale
object | null
​
amount
number
The sale amount in cents
​
currency
string
The currency code (e.g. “usd”)
​
paymentProcessor
string
The payment processor used
​
invoiceId
string | null
The invoice ID if provided
​
metadata
object | null
Additional metadata

​
Examples

curl -X POST https://api.dub.co/track/sale \
  -H "Authorization: Bearer DUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerExternalId": "user_123456",
    "amount": 4999,
    "currency": "usd",
    "eventName": "Invoice paid",
    "paymentProcessor": "stripe",
    "invoiceId": "inv_1234567890"
  }'

​
Response Example

{
  "eventName": "Invoice paid",
  "customer": {
    "id": "cus_xyz123",
    "name": "John Doe",
    "email": "[email protected]",
    "avatar": null,
    "externalId": "user_123456"
  },
  "sale": {
    "amount": 4999,
    "currency": "usd",
    "paymentProcessor": "stripe",
    "invoiceId": "inv_1234567890",
    "metadata": null
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us