> ## Documentation Index > Fetch the complete documentation index at: https://dub-stripe-first-time-order-setting.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml post /commissions openapi: 3.0.3 info: title: Dub 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 security: [] paths: /commissions: post: tags: - Commissions summary: Create commission description: >- 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. operationId: createCommission 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 earnings amount in cents. Use a negative amount to create a clawback. type: number date: description: If not provided, the current date will be used. nullable: true type: string description: description: >- 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). 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 date: description: >- The date and time of the lead event. If not provided, defaults to the current date and time. nullable: true type: string lead: description: The lead event object to associate the commission with. nullable: true type: object properties: eventName: description: >- The name of the lead event to track. If not provided, defaults to 'Sign up'. nullable: true type: string minLength: 1 maxLength: 255 example: Sign up metadata: description: >- Additional metadata to be stored with the lead event. Max 10,000 characters. default: null nullable: true type: object additionalProperties: {} leadEventDate: description: >- Deprecated: Use `date` instead. The date and time of the lead event. If not provided, defaults to the current date and time. deprecated: true nullable: true type: string leadEventName: default: Sign up description: >- Deprecated: Use `lead.eventName` instead. The name of the lead event. If not provided, defaults to 'Sign up'. deprecated: true 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 `sale.amount` (or deprecated `saleAmount`). nullable: true type: boolean date: 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 sale: description: The sale event object to associate the commission with. nullable: true type: object properties: amount: description: >- 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 nullable: true type: number currency: description: >- 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 type: string eventName: default: Purchase description: >- The name of the sale event. Recommended format: `Invoice paid` or `Subscription created`. example: Invoice paid type: string maxLength: 255 paymentProcessor: default: custom description: The payment processor via which the sale was made. type: string enum: - stripe - shopify - polar - paddle - apple - revenuecat - dub - custom invoiceId: default: null description: >- 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. nullable: true type: string metadata: description: >- Additional metadata to be stored with the sale event. Max 10,000 characters when stringified. default: null nullable: true type: object additionalProperties: {} saleEventDate: description: 'Deprecated: Use `date` instead.' deprecated: true nullable: true type: string saleAmount: description: 'Deprecated: Use `sale.amount` instead.' deprecated: true nullable: true type: number invoiceId: description: 'Deprecated: Use `sale.invoiceId` instead.' deprecated: true nullable: true type: string productId: description: 'Deprecated: Use `sale.metadata.productId` instead.' deprecated: true 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' security: - token: [] x-codeSamples: - lang: php label: createCommission source: |- declare(strict_types=1); require 'vendor/autoload.php'; use Dub; use Dub\Models\Operations; $sdk = Dub\Dub::builder() ->setSecurity( 'DUB_API_KEY' ) ->build(); $request = new Operations\RequestBody2( type: Operations\CreateCommissionRequestBodyType::Lead, partnerId: '', lead: new Operations\Lead( eventName: 'Sign up', ), ); $response = $sdk->commissions->create( request: $request ); if ($response->object !== null) { // handle response } - lang: go label: createCommission source: "package main\n\nimport(\n\t\"context\"\n\tdubgo \"github.com/dubinc/dub-go\"\n\t\"github.com/dubinc/dub-go/models/operations\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := dubgo.New(\n dubgo.WithSecurity(\"DUB_API_KEY\"),\n )\n\n res, err := s.Commissions.Create(ctx, dubgo.Pointer(operations.CreateCreateCommissionRequestBodyRequestBody2(\n operations.RequestBody2{\n Type: operations.CreateCommissionRequestBodyTypeLead,\n PartnerID: \"\",\n Lead: &operations.Lead{\n EventName: dubgo.Pointer(\"Sign up\"),\n },\n },\n )))\n if err != nil {\n log.Fatal(err)\n }\n if res != nil {\n // handle response\n }\n}" - lang: ruby label: createCommission source: |- require 'dub' Models = ::OpenApiSDK::Models s = ::OpenApiSDK::Dub.new( security: Models::Shared::Security.new( token: 'DUB_API_KEY' ) ) req = Models::Operations::RequestBody2.new( type: Models::Operations::CreateCommissionRequestBodyType::LEAD, partner_id: '', lead: Models::Operations::Lead.new( event_name: 'Sign up' ), lead_event_name: 'Sign up' ) res = s.commissions.create(request: req) unless res.nil? # handle response end - lang: typescript label: createCommission source: |- import { Dub } from "dub"; const dub = new Dub({ token: "DUB_API_KEY", }); async function run() { const result = await dub.commissions.create(); console.log(result); } run(); - lang: python label: createCommission source: |- 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": "", "lead_event_name": "Sign up", }) # Handle response print(res) components: responses: '400': description: >- The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). content: application/json: schema: x-speakeasy-name-override: BadRequest type: object properties: error: type: object properties: code: type: string enum: - bad_request description: A short code indicating the error code returned. example: bad_request message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://dub.co/docs/api-reference/errors#bad-request required: - code - message required: - error '401': description: >- Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. content: application/json: schema: x-speakeasy-name-override: Unauthorized type: object properties: error: type: object properties: code: type: string enum: - unauthorized description: A short code indicating the error code returned. example: unauthorized message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://dub.co/docs/api-reference/errors#unauthorized required: - code - message required: - error '403': description: >- The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. content: application/json: schema: x-speakeasy-name-override: Forbidden type: object properties: error: type: object properties: code: type: string enum: - forbidden description: A short code indicating the error code returned. example: forbidden message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://dub.co/docs/api-reference/errors#forbidden required: - code - message required: - error '404': description: The server cannot find the requested resource. content: application/json: schema: x-speakeasy-name-override: NotFound type: object properties: error: type: object properties: code: type: string enum: - not_found description: A short code indicating the error code returned. example: not_found message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://dub.co/docs/api-reference/errors#not-found required: - code - message required: - error '409': description: >- This response is sent when a request conflicts with the current state of the server. content: application/json: schema: x-speakeasy-name-override: Conflict type: object properties: error: type: object properties: code: type: string enum: - conflict description: A short code indicating the error code returned. example: conflict message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://dub.co/docs/api-reference/errors#conflict required: - code - message required: - error '410': description: >- This response is sent when the requested content has been permanently deleted from server, with no forwarding address. content: application/json: schema: x-speakeasy-name-override: InviteExpired type: object properties: error: type: object properties: code: type: string enum: - invite_expired description: A short code indicating the error code returned. example: invite_expired message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: https://dub.co/docs/api-reference/errors#invite-expired required: - code - message required: - error '422': description: >- The request was well-formed but was unable to be followed due to semantic errors. content: application/json: schema: x-speakeasy-name-override: UnprocessableEntity type: object properties: error: type: object properties: code: type: string enum: - unprocessable_entity description: A short code indicating the error code returned. example: unprocessable_entity message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: >- https://dub.co/docs/api-reference/errors#unprocessable-entity required: - code - message required: - error '429': description: >- The user has sent too many requests in a given amount of time ("rate limiting") content: application/json: schema: x-speakeasy-name-override: RateLimitExceeded type: object properties: error: type: object properties: code: type: string enum: - rate_limit_exceeded description: A short code indicating the error code returned. example: rate_limit_exceeded message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: >- https://dub.co/docs/api-reference/errors#rate-limit_exceeded required: - code - message required: - error '500': description: The server has encountered a situation it does not know how to handle. content: application/json: schema: x-speakeasy-name-override: InternalServerError type: object properties: error: type: object properties: code: type: string enum: - internal_server_error description: A short code indicating the error code returned. example: internal_server_error message: x-speakeasy-error-message: true type: string description: A human readable explanation of what went wrong. example: The requested resource was not found. doc_url: type: string description: >- A link to our documentation with more details about this error code example: >- https://dub.co/docs/api-reference/errors#internal-server_error required: - code - message required: - error securitySchemes: token: type: http description: Default authentication mechanism scheme: bearer x-speakeasy-example: DUB_API_KEY ````