openapi: 3.0.3 info: title: Dub Analytics Customers 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: Customers paths: /customers: get: operationId: getCustomers x-speakeasy-name-override: list x-speakeasy-pagination: type: cursor inputs: - name: startingAfter in: parameters type: cursor outputs: nextCursor: $[-1].id summary: List all customers description: Retrieve a paginated list of customers for the authenticated workspace. tags: - Customers security: - token: [] parameters: - in: query name: email schema: description: A case-sensitive filter on the list based on the customer's `email` field. The value must be a string. Takes precedence over `externalId`. type: string description: A case-sensitive filter on the list based on the customer's `email` field. The value must be a string. Takes precedence over `externalId`. - in: query name: externalId schema: description: A case-sensitive filter on the list based on the customer's `externalId` field. The value must be a string. Takes precedence over `search`. type: string description: A case-sensitive filter on the list based on the customer's `externalId` field. The value must be a string. Takes precedence over `search`. - in: query name: search schema: description: A search query to filter customers by email, externalId, or name. If `email` or `externalId` is provided, this will be ignored. type: string description: A search query to filter customers by email, externalId, or name. If `email` or `externalId` is provided, this will be ignored. - in: query name: country schema: description: A filter on the list based on the customer's `country` field. type: string description: A filter on the list based on the customer's `country` field. - in: query name: linkId schema: description: A filter on the list based on the customer's `linkId` field (the referral link ID). type: string description: A filter on the list based on the customer's `linkId` field (the referral link ID). - in: query name: programId schema: description: Program ID to filter by. type: string description: Program ID to filter by. - in: query name: partnerId schema: description: Partner ID to filter by. type: string description: Partner ID to filter by. - in: query name: includeExpandedFields schema: description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`). type: boolean description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`). - in: query name: sortBy schema: default: createdAt description: The field to sort the customers by. The default is `createdAt`. type: string enum: - createdAt - saleAmount - firstSaleAt - subscriptionCanceledAt description: The field to sort the customers by. The default is `createdAt`. - in: query name: sortOrder schema: default: desc description: The sort order. The default is `desc`. type: string enum: - asc - desc description: The sort order. The default is `desc`. - in: query name: endingBefore schema: description: If specified, the query only searches for results before this cursor. Mutually exclusive with `startingAfter`. example: cus_1KAP4CDPBSVMMBMH9XX3YZZ0Z 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: cus_1KAP4CDPBSVMMBMH9XX3YZZ0Z 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 minimum: 0 exclusiveMinimum: true description: DEPRECATED. Use `startingAfter` instead. - in: query name: pageSize schema: default: 100 description: The number of items per page. example: 50 type: number minimum: 0 exclusiveMinimum: true maximum: 100 description: The number of items per page. responses: '200': description: The list of customers. content: application/json: schema: type: array items: type: object 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. nullable: true type: string email: description: Email of the customer. nullable: true type: string avatar: description: Avatar URL of the customer. nullable: true type: string 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. nullable: true type: string country: description: Country of the customer. nullable: true type: string sales: description: Total number of sales for the customer. nullable: true type: number saleAmount: description: Total amount of sales for the customer. nullable: true type: number 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. nullable: true type: string subscriptionCanceledAt: description: The date the customer canceled their subscription. Useful for calculating LTV and churn rate. nullable: true type: string link: nullable: true type: object properties: id: type: string description: The unique ID of the short link. domain: type: string description: The domain of the short link. If not provided, the primary domain for the workspace will be used (or `dub.sh` if the workspace has no domains). key: type: string description: The short link slug. If not provided, a random 7-character slug will be generated. shortLink: type: string format: uri description: The full URL of the short link, including the https protocol (e.g. `https://dub.sh/try`). url: type: string format: uri description: The destination URL of the short link. programId: nullable: true description: The ID of the program the short link is associated with. type: string required: - id - domain - key - shortLink - url - programId additionalProperties: false programId: nullable: true type: string partner: nullable: true 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: nullable: true description: The partner's email address. Should be a unique value across Dub. type: string maxLength: 190 image: nullable: true description: The partner's avatar image. type: string required: - id - name - email - image additionalProperties: false discount: nullable: true type: object properties: id: type: string amount: type: number type: type: string enum: - percentage - flat maxDuration: nullable: true type: number couponId: nullable: true type: string couponTestId: nullable: true type: string description: nullable: true type: string partnersCount: nullable: true type: number required: - id - amount - type - maxDuration - couponId - couponTestId additionalProperties: false required: - id - externalId - createdAt 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' /customers/{id}: get: operationId: getCustomer x-speakeasy-name-override: get summary: Retrieve a customer description: Retrieve a customer by ID for the authenticated workspace. To retrieve a customer by external ID, prefix the ID with `ext_`. tags: - Customers security: - token: [] parameters: - in: path name: id schema: 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`). required: true 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`). - in: query name: includeExpandedFields schema: description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`). type: boolean description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`). responses: '200': description: The customer object. content: application/json: schema: type: object 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. nullable: true type: string email: description: Email of the customer. nullable: true type: string avatar: description: Avatar URL of the customer. nullable: true type: string 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. nullable: true type: string country: description: Country of the customer. nullable: true type: string sales: description: Total number of sales for the customer. nullable: true type: number saleAmount: description: Total amount of sales for the customer. nullable: true type: number 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. nullable: true type: string subscriptionCanceledAt: description: The date the customer canceled their subscription. Useful for calculating LTV and churn rate. nullable: true type: string link: nullable: true type: object properties: id: type: string description: The unique ID of the short link. domain: type: string description: The domain of the short link. If not provided, the primary domain for the workspace will be used (or `dub.sh` if the workspace has no domains). key: type: string description: The short link slug. If not provided, a random 7-character slug will be generated. shortLink: type: string format: uri description: The full URL of the short link, including the https protocol (e.g. `https://dub.sh/try`). url: type: string format: uri description: The destination URL of the short link. programId: nullable: true description: The ID of the program the short link is associated with. type: string required: - id - domain - key - shortLink - url - programId additionalProperties: false programId: nullable: true type: string partner: nullable: true 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: nullable: true description: The partner's email address. Should be a unique value across Dub. type: string maxLength: 190 image: nullable: true description: The partner's avatar image. type: string required: - id - name - email - image additionalProperties: false discount: nullable: true type: object properties: id: type: string amount: type: number type: type: string enum: - percentage - flat maxDuration: nullable: true type: number couponId: nullable: true type: string couponTestId: nullable: true type: string description: nullable: true type: string partnersCount: nullable: true type: number required: - id - amount - type - maxDuration - couponId - couponTestId additionalProperties: false required: - id - externalId - createdAt 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' patch: operationId: updateCustomer x-speakeasy-name-override: update x-speakeasy-max-method-params: 2 summary: Update a customer description: Update a customer for the authenticated workspace. tags: - Customers security: - token: [] parameters: - in: path name: id schema: 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`). required: true 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`). - in: query name: includeExpandedFields schema: description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`). type: boolean description: Whether to include expanded fields on the customer (`link`, `partner`, `discount`). requestBody: content: application/json: schema: 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). responses: '200': description: The customer was updated. content: application/json: schema: type: object 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. nullable: true type: string email: description: Email of the customer. nullable: true type: string avatar: description: Avatar URL of the customer. nullable: true type: string 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. nullable: true type: string country: description: Country of the customer. nullable: true type: string sales: description: Total number of sales for the customer. nullable: true type: number saleAmount: description: Total amount of sales for the customer. nullable: true type: number 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. nullable: true type: string subscriptionCanceledAt: description: The date the customer canceled their subscription. Useful for calculating LTV and churn rate. nullable: true type: string link: nullable: true type: object properties: id: type: string description: The unique ID of the short link. domain: type: string description: The domain of the short link. If not provided, the primary domain for the workspace will be used (or `dub.sh` if the workspace has no domains). key: type: string description: The short link slug. If not provided, a random 7-character slug will be generated. shortLink: type: string format: uri description: The full URL of the short link, including the https protocol (e.g. `https://dub.sh/try`). url: type: string format: uri description: The destination URL of the short link. programId: nullable: true description: The ID of the program the short link is associated with. type: string required: - id - domain - key - shortLink - url - programId additionalProperties: false programId: nullable: true type: string partner: nullable: true 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: nullable: true description: The partner's email address. Should be a unique value across Dub. type: string maxLength: 190 image: nullable: true description: The partner's avatar image. type: string required: - id - name - email - image additionalProperties: false discount: nullable: true type: object properties: id: type: string amount: type: number type: type: string enum: - percentage - flat maxDuration: nullable: true type: number couponId: nullable: true type: string couponTestId: nullable: true type: string description: nullable: true type: string partnersCount: nullable: true type: number required: - id - amount - type - maxDuration - couponId - couponTestId additionalProperties: false required: - id - externalId - createdAt 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' delete: operationId: deleteCustomer x-speakeasy-name-override: delete x-speakeasy-max-method-params: 1 summary: Delete a customer description: Delete a customer from a workspace. tags: - Customers security: - token: [] parameters: - in: path name: id schema: 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`). required: true 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`). responses: '200': description: The customer was deleted. content: application/json: schema: type: object 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`). required: - id 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' components: responses: '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 '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 '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 '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 '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 '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 '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 securitySchemes: token: type: http description: Default authentication mechanism scheme: bearer x-speakeasy-example: DUB_API_KEY