Dub Commissions API

openapi: 3.2.0
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.
                    type:
                    - string
                    - 'null'
                  description:
                    description: The description of the commission.
                    type:
                    - string
                    - 'null'
                    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.
                    type:
                    - string
                    - 'null'
                  customer:
                    description: The full customer object to associate the commission with. Useful for creating the customer on demand.
                    type:
                    - object
                    - 'null'
                    properties:
                      email:
                        description: The customer's email address.
                        type:
                        - string
                        - 'null'
                        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.
                        type:
                        - string
                        - 'null'
                      avatar:
                        description: The customer's avatar URL. If not provided, a random avatar will be generated.
                        type:
                        - string
                        - 'null'
                        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.
                        type:
                        - string
                        - 'null'
                      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.
                    type:
                    - string
                    - 'null'
                  leadEventDate:
                    description: The date and time of the lead event. If not provided, defaults to the current date and time.
                    type:
                    - string
                    - 'null'
                  leadEventName:
                    default: Sign up
                    description: The name of the lead event. If not provided, defaults to 'Sign up'.
                    type:
                    - string
                    - 'null'
                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.
                    type:
                    - string
                    - 'null'
                  customer:
                    description: The full customer object to associate the commission with. Useful for creating the customer on demand.
                    type:
                    - object
                    - 'null'
                    properties:
                      email:
                        description: The customer's email address.
                        type:
                        - string
                        - 'null'
                        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.
                        type:
                        - string
                        - 'null'
                      avatar:
                        description: The customer's avatar URL. If not provided, a random avatar will be generated.
                        type:
                        - string
                        - 'null'
                        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.
                        type:
                        - string
                        - 'null'
                      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.
                    type:
                    - string
                    - 'null'
                  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`.
                    type:
                    - boolean
                    - 'null'
                  saleAmount:
                    description: Required when `importStripeInvoices` is `false`. The sale amount in cents for the manual sale event. Ignored when importing from Stripe.
                    type:
                    - number
                    - 'null'
                  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.
                    type:
                    - string
                    - 'null'
                  invoiceId:
                    description: Only used when `importStripeInvoices` is `false`. An optional invoice ID to attach to the generated sale event and commission entry for deduplication.
                    type:
                    - string
                    - 'null'
                  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).
                    type:
                    - string
                    - 'null'
                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
          exclusiveMinimum: 0
        description: DEPRECATED. Use `startingAfter` instead.
      - in: query
        name: pageSize
        schema:
          default: 100
          description: The number of items per page.
          example: 50
          type: number
          maximum: 100
          exclusiveMinimum: 0
        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:
                      type:
                      - string
                      - 'null'
                    description:
                      type:
                      - string
                      - 'null'
                    quantity:
                      type: number
                    userId:
                      description: The user who created the manual commission.
                      type:
                      - string
                      - 'null'
                    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:
                          description: The partner's email address. Should be a unique value across Dub.
                          type:
                          - string
                          - 'null'
                          maxLength: 190
                        image:
                          description: The partner's avatar image.
                          type:
                          - string
                          - 'null'
                        payoutsEnabledAt:
                          description: The date when the partner enabled payouts.
                          type:
                          - string
                          - 'null'
                        country:
                          description: The partner's country (required for tax purposes).
                          type:
                          - string
                          - 'null'
                        groupId:
                          description: The partner's group ID on Dub.
                          type:
                          - string
                          - 'null'
                      required:
                      - id
                      - name
                      - email
                      - image
                      - payoutsEnabledAt
                      - country
                      additionalProperties: false
                    customer:
                      type:
                      - object
                      - 'null'
                      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.
                          type:
                          - string
                          - 'null'
                        email:
                          description: Email of the customer.
                          type:
                          - string
                          - 'null'
                        avatar:
                          description: Avatar URL of the customer.
                          type:
                          - string
                          - 'null'
                        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.
                          type:
                          - string
                          - 'null'
                        country:
                          description: Country of the customer.
                          type:
                          - string
                          - 'null'
                        sales:
                          description: Total number of sales for the customer.
                          type:
                          - number
                          - 'null'
                        saleAmount:
                          description: Total amount of sales for the customer.
                          type:
                          - number
                          - 'null'
                        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.
                          type:
                          - string
                          - 'null'
                        subscriptionCanceledAt:
                          description: The date the customer canceled their subscription. Useful for calculating LTV and churn rate.
                          type:
                          - string
                          - 'null'
                      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:
                    type:
                    - string
                    - 'null'
                  description:
                    type:
                    - string
                    - 'null'
                  quantity:
                    type: number
                  userId:
                    description: The user who created the manual commission.
                    type:
                    - string
                    - 'null'
                  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:
                        description: The partner's email address. Should be a unique value across Dub.
                        type:
                        - string
                        - 'null'
                        maxLength: 190
                      image:
                        description: The partner's avatar image.
                        type:
                        - string
                        - 'null'
                      payoutsEnabledAt:
                        description: The date when the partner enabled payouts.
                        type:
                        - string
                        - 'null'
                      country:
                        description: The partner's country (required for tax purposes).
                        type:
                        - string
                        - 'null'
                      groupId:
                        description: The partner's group ID on Dub.
                        type:
                        - string
                        - 'null'
                    required:
                    - id
                    - name
                    - email
                    - image
                    - payoutsEnabledAt
                    - country
                    additionalProperties: false
                  customer:
                    type:
                    - object
               

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dub/refs/heads/main/openapi/dub-commissions-api-openapi.yml