List all commissions

Retrieve a paginated list of commissions for your partner program.

1 min read

get/commissions

Request example

from dub import Dub


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

    res = d_client.commissions.list(request={
        "query": "metadata['key']='value'",
        "ending_before": "cm_1KAP4CGN2Z5TPYYQ1W4JEYD56",
        "starting_after": "cm_1KAP4CGN2Z5TPYYQ1W4JEYD56",
        "page": 1,
        "page_size": 50,
    })

    while res is not None:
        # Handle items

        res = res.next()

Response

[
  {
    "id": "cm_1JVR7XRCSR0EDBAF39FZ4PMYE",
    "type": "click",
    "amount": 1,
    "earnings": 1,
    "currency": "<string>",
    "status": "pending",
    "invoiceId": "<string>",
    "description": "<string>",
    "quantity": 1,
    "userId": "<string>",
    "metadata": {},
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "paidAt": "<string>",
    "partner": {
      "id": "<string>",
      "name": "<string>",
      "email": "<string>",
      "image": "<string>",
      "payoutsEnabledAt": "<string>",
      "country": "<string>",
      "groupId": "<string>"
    },
    "customer": {
      "id": "<string>",
      "name": "<string>",
      "email": "<string>",
      "avatar": "<string>",
      "externalId": "<string>",
      "stripeCustomerId": "<string>",
      "country": "<string>",
      "sales": 1,
      "saleAmount": 1,
      "createdAt": "<string>",
      "firstSaleAt": "<string>",
      "subscriptionCanceledAt": "<string>"
    }
  }
]

get/commissions

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Query parameters

typeenum<string>#

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"

Options:clickleadsalereferralcustom

customerIdstring#

Filter the list of commissions by the associated customer.

payoutIdstring#

Filter the list of commissions by the associated payout.

partnerIdstring#

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"

tenantIdstring#

Filter the list of commissions by the associated partner's tenantId (their unique ID within your database).

groupIdstring#

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"

partnerTagIdstring#

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"

invoiceIdstring#

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.

statusenum<string>#

Filter the list of commissions by their corresponding status.

Options:pendingprocessedpaidrefundedduplicatefraudcanceledhold

sortByenum<string>#

The field to sort the list of commissions by.

Default: "createdAt"

Options:createdAtamount

sortOrderenum<string>#

The sort order for the list of commissions.

Default: "desc"

Options:ascdesc

intervalenum<string>#

The interval to retrieve commissions for.

Default: "all"

Options:24h7d30d90d1ymtdqtdytdall

startstring#

The start date of the date range to filter the commissions by.

endstring#

The end date of the date range to filter the commissions by.

timezonestring#

querystring#

Filter by lead or sale event metadata. Top-level keys only. Compares string values only — numeric and boolean metadata values are not matched.
Examples:

"metadata['key']='value'"
"metadata['key']!='value'"

Length: max 10000

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

idstringrequired#

The commission's unique ID on Dub.

typeenum<string>required#

The type of commission. Can be click, lead, sale, referral, or custom.

Options:clickleadsalereferralcustom

amountnumberrequired#

The associated event amount in cents. For sale commissions, this is the sale amount.

earningsnumberrequired#

The amount earned by the partner, in cents.

currencystringrequired#

The currency of the commission, as an ISO 4217 currency code.

statusenum<string>required#

The current status of the commission.

Options:pendingprocessedpaidrefundedduplicatefraudcanceledhold

invoiceIdstringrequired#

The associated invoice ID. Only set for sale commissions.

descriptionstringrequired#

An optional description of the commission.

quantitynumberrequired#

The event quantity. Used for click and lead commissions; typically 1 for sale and custom commissions.

userIdstring#

The user who created the manual commission.

metadataobjectrequired#

User-provided metadata from the associated lead or sale event (lead.metadata / sale.metadata).

Show child attributes

{key}any#

createdAtstringrequired#

The date and time when the commission was created.

updatedAtstringrequired#

The date and time when the commission was last updated.

paidAtstringrequired#

The date the commission was paid out to the partner. Null if not paid yet.

partnerobjectrequired#

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.

payoutsEnabledAtstringrequired#

The date when the partner enabled payouts.

countrystringrequired#

The partner's country (required for tax purposes).

groupIdstring#

The partner's group ID on Dub.

customerobject#

Show child attributes

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.

Reject submission Create commission