Update a commission

Update an existing commission amount. This is useful for handling refunds (partial or full) or fraudulent sales.

1 min read

patch/commissions/{id}

Request example

from dub import Dub


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

    res = d_client.commissions.update(request={
        "id": "cm_1JVR7XRCSR0EDBAF39FZ4PMYE",
    })

    # Handle response
    print(res)

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>"
  }
}

patch/commissions/{id}

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Path parameters

idstringrequired#

The commission's unique ID on Dub.

Body

application/json

earningsnumber#

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.

Range: >= 0

saleAmountnumber#

The new absolute amount for the sale. Paid commissions cannot be updated.

Range: >= 0

modifySaleAmountnumber#

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.

currencystring#

The currency of the sale amount to update. Accepts ISO 4217 currency codes.

Default: "usd"

statusenum<string>#

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.

Options:pendingrefundedduplicatecanceledfraud

amountnumberdeprecated#

Deprecated. Use saleAmount instead.

Range: >= 0

modifyAmountnumberdeprecated#

Deprecated. Use modifySaleAmount instead.

Responses

application/json

The updated commission.

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.

Create commission List payouts