Dub Commissions API
The Commissions API from Dub — 3 operation(s) for commissions.
OpenAPI Specification
openapi: 3.0.3
info:
title: Dub Analytics Commissions 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: Commissions
paths:
/commissions:
post:
operationId: createCommission
x-speakeasy-name-override: create
summary: Create commission
description: Create one or more commissions (custom, lead or sale) for a partner. Commission creation is processed asynchronously. Use the List Commissions endpoint or webhooks to be notified when the commission is created.
tags:
- Commissions
security:
- token: []
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
properties:
type:
type: string
enum:
- custom
partnerId:
type: string
description: The ID of the partner to create the commission for.
amount:
description: The commission amount in cents.
type: number
date:
description: If not provided, the current date will be used.
nullable: true
type: string
description:
description: The description of the commission.
nullable: true
type: string
maxLength: 190
required:
- type
- partnerId
- amount
- type: object
properties:
type:
type: string
enum:
- lead
partnerId:
type: string
description: The ID of the partner to create the commission for.
customerId:
description: The customer ID to associate the commission with. Useful if the customer was already created in a prior operation and you want to associate the commission with it.
nullable: true
type: string
customer:
description: The full customer object to associate the commission with. Useful for creating the customer on demand.
nullable: true
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).
required:
- externalId
- country
linkId:
description: The partner link ID to associate the commission with. If not provided, default to the link with the most revenue.
nullable: true
type: string
leadEventDate:
description: The date and time of the lead event. If not provided, defaults to the current date and time.
nullable: true
type: string
leadEventName:
default: Sign up
description: The name of the lead event. If not provided, defaults to 'Sign up'.
nullable: true
type: string
required:
- type
- partnerId
- type: object
properties:
type:
type: string
enum:
- sale
partnerId:
type: string
description: The ID of the partner to create the commission for.
customerId:
description: The customer ID to associate the commission with. Useful if the customer was already created in a prior operation and you want to associate the commission with it.
nullable: true
type: string
customer:
description: The full customer object to associate the commission with. Useful for creating the customer on demand.
nullable: true
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).
required:
- externalId
- country
linkId:
description: The partner link ID to associate the commission with. If not provided, default to the link with the most revenue.
nullable: true
type: string
importStripeInvoices:
default: false
description: When `true`, import all unimported paid Stripe invoices for the customer and create a commission for each. When `false`, create a single manual sale event using `saleAmount`.
nullable: true
type: boolean
saleAmount:
description: Required when `importStripeInvoices` is `false`. The sale amount in cents for the manual sale event. Ignored when importing from Stripe.
nullable: true
type: number
saleEventDate:
description: Only used when `importStripeInvoices` is `false`. The date of the manual sale event. Defaults to the current date and time if not provided.
nullable: true
type: string
invoiceId:
description: Only used when `importStripeInvoices` is `false`. An optional invoice ID to attach to the generated sale event and commission entry for deduplication.
nullable: true
type: string
productId:
description: Only used when `importStripeInvoices` is `false`. An optional product ID stored on the sale event metadata – will also impact commission earnings calculation (if a `Sale` `Product ID` modifier is set).
nullable: true
type: string
required:
- type
- partnerId
type: object
responses:
'202':
description: The request was accepted and commission creation was queued.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
required:
- success
- message
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'
get:
operationId: listCommissions
x-speakeasy-name-override: list
x-speakeasy-pagination:
type: cursor
inputs:
- name: startingAfter
in: parameters
type: cursor
outputs:
nextCursor: $[-1].id
summary: List all commissions
description: Retrieve a paginated list of commissions for your partner program.
tags:
- Commissions
security:
- token: []
parameters:
- in: query
name: type
schema:
description: 'Filter the list of commissions by type. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `sale`, `sale,lead`, `-click`.'
type: string
enum:
- click
- lead
- sale
- referral
- custom
description: 'Filter the list of commissions by type. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `sale`, `sale,lead`, `-click`.'
- in: query
name: customerId
schema:
description: Filter the list of commissions by the associated customer.
type: string
description: Filter the list of commissions by the associated customer.
- in: query
name: payoutId
schema:
description: Filter the list of commissions by the associated payout.
type: string
description: Filter the list of commissions by the associated payout.
- in: query
name: partnerId
schema:
description: 'Filter the list of commissions by the associated partner. When specified, takes precedence over `tenantId`. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `partner_abc`, `partner_abc,partner_xyz`, `-partner_abc`.'
type: string
description: 'Filter the list of commissions by the associated partner. When specified, takes precedence over `tenantId`. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `partner_abc`, `partner_abc,partner_xyz`, `-partner_abc`.'
- in: query
name: tenantId
schema:
description: Filter the list of commissions by the associated partner's `tenantId` (their unique ID within your database).
type: string
description: Filter the list of commissions by the associated partner's `tenantId` (their unique ID within your database).
- in: query
name: groupId
schema:
description: 'Filter the list of commissions by the associated partner group. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `group_abc`, `group_abc,group_xyz`, `-group_abc`.'
type: string
description: 'Filter the list of commissions by the associated partner group. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `group_abc`, `group_abc,group_xyz`, `-group_abc`.'
- in: query
name: partnerTagId
schema:
description: 'Filter the list of commissions by the associated partner tag. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `ptag_abc`, `ptag_abc,ptag_xyz`, `-ptag_abc`.'
type: string
description: 'Filter the list of commissions by the associated partner tag. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `ptag_abc`, `ptag_abc,ptag_xyz`, `-ptag_abc`.'
- in: query
name: invoiceId
schema:
description: Filter the list of commissions by the associated invoice. Since invoiceId is unique on a per-program basis, this will only return one commission per invoice.
type: string
description: Filter the list of commissions by the associated invoice. Since invoiceId is unique on a per-program basis, this will only return one commission per invoice.
- in: query
name: status
schema:
description: Filter the list of commissions by their corresponding status.
type: string
enum:
- pending
- processed
- paid
- refunded
- duplicate
- fraud
- canceled
description: Filter the list of commissions by their corresponding status.
- in: query
name: sortBy
schema:
default: createdAt
description: The field to sort the list of commissions by.
type: string
enum:
- createdAt
- amount
description: The field to sort the list of commissions by.
- in: query
name: sortOrder
schema:
default: desc
description: The sort order for the list of commissions.
type: string
enum:
- asc
- desc
description: The sort order for the list of commissions.
- in: query
name: interval
schema:
default: all
description: The interval to retrieve commissions for.
type: string
enum:
- 24h
- 7d
- 30d
- 90d
- 1y
- mtd
- qtd
- ytd
- all
description: The interval to retrieve commissions for.
- in: query
name: start
schema:
description: The start date of the date range to filter the commissions by.
type: string
description: The start date of the date range to filter the commissions by.
- in: query
name: end
schema:
description: The end date of the date range to filter the commissions by.
type: string
description: The end date of the date range to filter the commissions by.
- in: query
name: timezone
schema:
type: string
- in: query
name: endingBefore
schema:
description: If specified, the query only searches for results before this cursor. Mutually exclusive with `startingAfter`.
example: cm_1KAP4CGN2Z5TPYYQ1W4JEYD56
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: cm_1KAP4CGN2Z5TPYYQ1W4JEYD56
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 commissions.
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The commission's unique ID on Dub.
example: cm_1JVR7XRCSR0EDBAF39FZ4PMYE
type:
type: string
enum:
- click
- lead
- sale
- referral
- custom
amount:
type: number
earnings:
type: number
currency:
type: string
status:
type: string
enum:
- pending
- processed
- paid
- refunded
- duplicate
- fraud
- canceled
invoiceId:
nullable: true
type: string
description:
nullable: true
type: string
quantity:
type: number
userId:
description: The user who created the manual commission.
nullable: true
type: string
createdAt:
type: string
updatedAt:
type: string
partner:
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
payoutsEnabledAt:
nullable: true
description: The date when the partner enabled payouts.
type: string
country:
nullable: true
description: The partner's country (required for tax purposes).
type: string
groupId:
description: The partner's group ID on Dub.
nullable: true
type: string
required:
- id
- name
- email
- image
- payoutsEnabledAt
- country
additionalProperties: false
customer:
nullable: true
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
required:
- id
- externalId
- createdAt
additionalProperties: false
required:
- id
- amount
- earnings
- currency
- status
- invoiceId
- description
- quantity
- createdAt
- updatedAt
- partner
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'
/commissions/{id}:
patch:
operationId: updateCommission
x-speakeasy-name-override: update
summary: Update a commission
description: Update an existing commission amount. This is useful for handling refunds (partial or full) or fraudulent sales.
tags:
- Commissions
security:
- token: []
parameters:
- in: path
name: id
schema:
type: string
description: The commission's unique ID on Dub.
example: cm_1JVR7XRCSR0EDBAF39FZ4PMYE
required: true
description: The commission's unique ID on Dub.
requestBody:
content:
application/json:
schema:
type: object
properties:
earnings:
description: The new earnings amount for the commission. Paid commissions cannot be updated. If provided, will override the earnings calculated based on the sale amount and currency.
type: number
minimum: 0
saleAmount:
description: The new absolute amount for the sale. Paid commissions cannot be updated.
type: number
minimum: 0
modifySaleAmount:
description: 'Modify the current sale amount: use positive values to increase the amount, negative values to decrease it. Takes precedence over `saleAmount`. Paid commissions cannot be updated.'
type: number
currency:
description: The currency of the sale amount to update. Accepts ISO 4217 currency codes.
default: usd
type: string
status:
description: Useful for marking a commission as pending, refunded, duplicate, canceled, or fraudulent. Takes precedence over `saleAmount` and `modifySaleAmount`. When a commission is marked as pending, refunded, duplicate, canceled, or fraudulent, it will be omitted from the payout, and the payout amount will be recalculated accordingly. Paid commissions cannot be updated.
type: string
enum:
- pending
- refunded
- duplicate
- canceled
- fraud
amount:
description: Deprecated. Use `saleAmount` instead.
deprecated: true
type: number
minimum: 0
modifyAmount:
description: Deprecated. Use `modifySaleAmount` instead.
deprecated: true
type: number
responses:
'200':
description: The updated commission.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The commission's unique ID on Dub.
example: cm_1JVR7XRCSR0EDBAF39FZ4PMYE
type:
type: string
enum:
- click
- lead
- sale
- referral
- custom
amount:
type: number
earnings:
type: number
currency:
type: string
status:
type: string
enum:
- pending
- processed
- paid
- refunded
- duplicate
- fraud
- canceled
invoiceId:
nullable: true
type: string
description:
nullable: true
type: string
quantity:
type: number
userId:
description: The user who created the manual commission.
nullable: true
type: string
createdAt:
type: string
updatedAt:
type: string
partner:
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
payoutsEnabledAt:
nullable: true
description: The date when the partner enabled payouts.
type: string
country:
nullable: true
description: The partner's country (required for tax purposes).
type: string
groupId:
description: The partner's group ID on Dub.
nullable: true
type: string
required:
- id
- name
- email
- image
- payoutsEnabledAt
- country
additionalProperties: false
customer:
nullable: true
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:
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dub/refs/heads/main/openapi/dub-commissions-api-openapi.yml