Create commission

Create one or more commissions (custom, lead or sale) for a partner. Custom commissions accept a negative amount to create a clawback. Commission creation is processed asynchronously – use the GET /commissions endpoint or webhooks to be notified when the commission is created.

1 min read

post/commissions

Request example

from dub import Dub
from dub.models import operations


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

    res = d_client.commissions.create(request={
        "type": operations.CreateCommissionRequestBodyType.LEAD,
        "partner_id": "<id>",
        "lead_event_name": "Sign up",
    })

    # Handle response
    print(res)

Response

{
  "success": true,
  "message": "<string>"
}

post/commissions

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Body

application/json

One of

typeenum<string>required#

Options:custom

partnerIdstringrequired#

The ID of the partner to create the commission for.

amountnumberrequired#

The commission earnings amount in cents. Use a negative amount to create a clawback.

datestring#

If not provided, the current date will be used.

descriptionstring#

The description of the commission. Required for clawbacks (negative amount). May be a known clawback reason (order_canceled, fraud, terms_violation, tracking_error, payment_failed, ineligible_partner, duplicate_commission) or an arbitrary string (max 190 characters).

Length: max 190

typeenum<string>required#

Options:lead

partnerIdstringrequired#

The ID of the partner to create the commission for.

customerIdstring#

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.

customerobject#

The full customer object to associate the commission with. Useful for creating the customer on demand.

Show child attributes

emailstring#

The customer's email address.

Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

namestring#

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.

avatarstring#

The customer's avatar URL. If not provided, a random avatar will be generated.

externalIdstringrequired#

The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.

stripeCustomerIdstring#

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

countrystringrequired#

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

linkIdstring#

The partner link ID to associate the commission with. If not provided, default to the link with the most revenue.

datestring#

The date and time of the lead event. If not provided, defaults to the current date and time.

leadobject#

The lead event object to associate the commission with.

Show child attributes

eventNamestring#

The name of the lead event to track. If not provided, defaults to 'Sign up'.

Length: 1–255

metadataobject#

Additional metadata to be stored with the lead event. Max 10,000 characters.

Default: null

Show child attributes

{key}any#

leadEventDatestringdeprecated#

Deprecated: Use date instead. The date and time of the lead event. If not provided, defaults to the current date and time.

leadEventNamestringdeprecated#

Deprecated: Use lead.eventName instead. The name of the lead event. If not provided, defaults to 'Sign up'.

Default: "Sign up"

typeenum<string>required#

Options:sale

partnerIdstringrequired#

The ID of the partner to create the commission for.

customerIdstring#

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.

customerobject#

The full customer object to associate the commission with. Useful for creating the customer on demand.

Show child attributes

emailstring#

The customer's email address.

Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

namestring#

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.

avatarstring#

The customer's avatar URL. If not provided, a random avatar will be generated.

externalIdstringrequired#

The customer's unique identifier your database. This is useful for associating subsequent conversion events from Dub's API to your internal systems.

stripeCustomerIdstring#

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

countrystringrequired#

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

linkIdstring#

The partner link ID to associate the commission with. If neither linkId nor discountCode is provided, default to the link with the most revenue.

discountCodestring#

The partner discount code to resolve the associated link. Use this when the link ID is unknown. Cannot be provided together with linkId.

Length: min 1

importStripeInvoicesboolean#

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 sale.amount (or deprecated saleAmount).

Default: false

datestring#

Only used when importStripeInvoices is false. The date of the manual sale event. Defaults to the current date and time if not provided.

saleobject#

The sale event object to associate the commission with.

Show child attributes

amountnumber#

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. 1580 JPY). Learn more: https://d.to/currency

currencystring#

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: https://d.to/currency

Default: "usd"

eventNamestring#

The name of the sale event. Recommended format: Invoice paid or Subscription created.

Default: "Purchase"

Length: max 255

paymentProcessorenum<string>#

The payment processor via which the sale was made.

Default: "custom"

Options:stripeshopifypolarpaddleapplerevenuecatlemonsqueezydubcustom

invoiceIdstring#

The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID.

Default: null

metadataobject#

Additional metadata to be stored with the sale event. Max 10,000 characters when stringified.

Default: null

Show child attributes

{key}any#

saleEventDatestringdeprecated#

Deprecated: Use date instead.

saleAmountnumberdeprecated#

Deprecated: Use sale.amount instead.

invoiceIdstringdeprecated#

Deprecated: Use sale.invoiceId instead.

productIdstringdeprecated#

Deprecated: Use sale.metadata.productId instead.

Responses

application/json

The request was accepted and commission creation was queued.

successbooleanrequired#

messagestringrequired#

List commissions Update commission