Payouts API

Purpose and Scope

The Payouts API is the partner-program reporting surface for retrieving payout records. In Dub terminology, a payout is the operational container that moves accrued partner commissions from a program toward a partner payout method. The public API documentation describes the endpoint as a paginated listing endpoint for partner programs, while the repository source shows that the OpenAPI path family registers a single GET /payouts operation through payoutsPaths. This page explains that API surface and connects it to the payout notification templates that communicate processed and failed payout outcomes to users.

Sources: apps/web/lib/openapi/payouts/index.ts, packages/email/src/templates/partner-payout-processed.tsx, packages/email/src/templates/partner-payout-failed.tsx

Payouts sit at the boundary between API reporting and operational lifecycle messaging. The listing endpoint helps a program or integration inspect payout state, filter by partner identity, and build dashboards or reconciliation jobs. The email templates show what happens after payout state changes matter to humans: partners are told when a payout is processed and what to expect next, while program owners are told when a partner payout failed and what remediation is required. Treat the API and emails as two sides of the same resource lifecycle rather than unrelated features.

Relevant Source Files

• apps/web/lib/openapi/payouts/index.ts - Registers the Payouts OpenAPI path object and maps GET /payouts to the listPayouts operation.
• packages/email/src/templates/partner-payout-processed.tsx - Defines the partner-facing email sent when a payout is processed, including payout amount, period dates, payout method-specific messaging, minimum withdrawal handling, and stablecoin fee messaging.
• packages/email/src/templates/partner-payout-failed.tsx - Defines the program-facing email sent when a partner payout fails, including amount, method, failure reason, optional failure fee, card metadata, and links for remediation.

API Components

The repository entry point for this API family is intentionally small. payoutsPaths is exported as a ZodOpenApiPathsObject, and its only visible route key is /payouts with a get handler assigned to listPayouts. That shape matters because Dub’s API reference is assembled from modular path objects: each resource family contributes one or more OpenAPI path definitions, and the payout module contributes the payout listing route. For consumers, the important public contract is that payout reads are grouped under the Payouts API family and exposed through a single list operation rather than through create or mutation operations in this module.

Sources: apps/web/lib/openapi/payouts/index.ts

The official API reference names the operation listPayouts and describes it as retrieving a paginated list of payouts for a partner program. It also documents filters for payout status, partner ID, and tenant ID. partnerId is the direct Dub partner identifier, while tenantId is described as the partner’s unique ID inside the caller’s own database; when both are relevant, the public docs state that partnerId takes precedence over tenantId. This distinction is important for integrations that mirror partner records locally and need predictable reconciliation semantics.

Compact API Reference

Use the listing endpoint when the caller needs read-side visibility into payout state. Examples include a program dashboard that displays all pending or processed payouts, a reconciliation script that compares Dub payout records to external accounting data, or a partner-support workflow that looks up payouts for a known partner. The source snippet does not show mutation paths in this family, so do not infer create, update, approve, or retry operations from payoutsPaths; those workflows may exist elsewhere, but this OpenAPI module only establishes the listing surface.

Payout Status and Filtering Model

The public payout status vocabulary is lifecycle-oriented. pending represents payout value that has not yet moved forward, processing and processed describe intermediate operational states, sent and completed represent later delivery states, and failed or canceled describe exception outcomes. The email templates reinforce that payout status is not just an API label. A processed payout can remain in an account under minimum-withdrawal rules, and a failed payout can revert value back to pending so the payout must be confirmed again. API consumers should therefore display status as actionable state, not merely as historical metadata.

Sources: packages/email/src/templates/partner-payout-processed.tsx, packages/email/src/templates/partner-payout-failed.tsx

Filtering by partnerId or tenantId is especially useful for embedded partner-program experiences. If your application stores its own partner IDs, tenantId lets you query with that external identifier. If you already know the Dub partner ID, use partnerId for the more direct filter and to match the documented precedence behavior. Status filters should be used for queues: pending payouts for follow-up, processed payouts for partner visibility, failed payouts for remediation, and completed or sent payouts for historical reporting.

Operational Notifications

PartnerPayoutProcessed is the partner-facing processed payout template. Its props include email, a program object with name and optional logo, and a payout object with id, amount, optional periodStart, optional periodEnd, and a method typed as PartnerPayoutMethod | null. The component formats the amount with currencyFormatter, formats payout period dates in UTC with formatDate, and chooses a status message based on payout method and withdrawal thresholds. This template is a useful source-level signal for how Dub explains processed payout state to partners.

Sources: packages/email/src/templates/partner-payout-processed.tsx

The processed template has several method-specific branches. For PayPal, it tells the partner that the payout is on its way to their PayPal account and that PayPal will send completion email. For stablecoin payouts, it applies STABLECOIN_PAYOUT_FEE_RATE and explains that the net amount will be transferred to a connected crypto wallet, typically within minutes. For below-minimum payouts, it explains that the payout remains in processed status, points to the partner payouts page, mentions an immediate withdrawal option, and describes an automatic withdrawal after up to 90 days with a below-minimum withdrawal fee.

PartnerPayoutFailed is program-facing and focuses on remediation. Its props include a workspace slug, program name, payout amount in cents, payment method of card or direct_debit, optional failure reason, optional failure fee, optional card last four digits, and recipient email. The email states that a recent partner payout failed, that the payouts have reverted back to Pending, and that they must be confirmed again. When available, it includes the failure reason and fee details, then links the operator to billing settings and the pending payouts tab.

Sources: packages/email/src/templates/partner-payout-failed.tsx

System-to-Code Mapping

The payout listing module belongs to the OpenAPI layer: it does not render UI or send email; it declares that the public API includes GET /payouts. The processed and failed templates belong to the email package: they do not define the API route, but they encode operational expectations around payout state changes. Together they give implementers a fuller contract. The API tells you how to retrieve payout records, and the templates show which state transitions trigger communication, what amounts and methods are significant, and what users are expected to do next.

Sources: apps/web/lib/openapi/payouts/index.ts, packages/email/src/templates/partner-payout-processed.tsx, packages/email/src/templates/partner-payout-failed.tsx

A practical integration should therefore combine API polling or dashboard reads with notification-aware UX. For example, when displaying processed stablecoin payouts, the UI should account for fees and final transfer expectations. When displaying processed payouts below the minimum withdrawal amount, it should avoid implying that funds have already been delivered. When displaying failed payouts to program operators, it should make the retry path clear and explain that affected payouts returned to pending. These behaviors are grounded in the messages Dub itself sends for the same lifecycle moments.

Implementation Guidance

When building against the Payouts API, begin with the list operation and decide which filters match your workflow. A partner-facing portal typically filters by partnerId or tenantId and presents the partner’s own payout history. A program-operations dashboard typically filters by status, because payout work often happens in queues. A finance or reconciliation job may page through all payouts for a reporting period and then group by status or partner. The source-backed OpenAPI module confirms the route family and method; the public documentation provides the filter vocabulary.

// Conceptual client-side call shape based on the public API contract.
await fetch('https://api.dub.co/payouts?status=processed&partnerId=pn_...', {
  headers: {
    Authorization: `Bearer ${process.env.DUB_API_KEY}`,
  },
});

Be careful with amount handling. The failed payout template explicitly documents the payout amount and failure fee as cents in its prop type comments, and the processed template passes numeric amounts through Dub’s currency formatter. If your integration stores amounts, keep the smallest currency unit until final display, and let formatting happen at the presentation boundary. Also preserve failure metadata where available. failureReason, failureFee, and cardLast4 are optional, so your UI and logging should handle absent values without hiding the main action: update payment details and retry pending payouts.

Next Steps

Use this page when you need to understand the payout read API and the operational messages around processed or failed payouts. For adjacent implementation work, read the Commissions API documentation to understand how commissions become payout value, the Partner Programs and Bounties pages for the program context, and the Email Package page if you need to modify notification templates. If you are documenting or extending the API surface, keep the OpenAPI module focused on the public route contract and keep lifecycle-specific user guidance consistent with the email templates.

Sources: apps/web/lib/openapi/payouts/index.ts, packages/email/src/templates/partner-payout-processed.tsx, packages/email/src/templates/partner-payout-failed.tsx