Getting Started
Core Architecture
Link Engine
Analytics & Attribution
Partners & Affiliates
Third-Party Integrations
Identity & Security
Automation & Messaging
Developer Tools
The following files were used as context for generating this wiki page:
The execution flow tracing from POST down to DubApiError governs the processing of large background commission exports triggered via QStash. When an export cron request hits the API route, it verifies signatures, parses input payloads, retrieves batches of commissions with optional metadata filters, and generates downloadable CSV reports. If validation failures or invalid query cursors occur during this pipeline, errors are caught, logged, and structured into standard API error responses using DubApiError.
Sources: apps/web/app/(ee)/api/cron/export/commissions/route.ts:22-114
The execution begins at the POST route handler for commission export cron jobs. It reads the incoming request body, validates the QStash signature, and parses the payload using a Zod schema to extract filters, programId, columns, and userId. It verifies the existence of the target user and program in the database before initiating batch processing.
Sources: apps/web/app/(ee)/api/cron/export/commissions/route.ts:23-67
To handle large export datasets without memory exhaustion, the router invokes the fetchCommissionsBatch async generator. This function iterates through paginated database queries by requesting fixed-size batches (defaulting to 1,000 records per page) until all matching records have been retrieved.
Sources: apps/web/app/(ee)/api/cron/export/commissions/fetch-commissions-batch.ts:12-34
Inside the batch generator, getCommissions executes the underlying database queries via Prisma. It processes filtering parameters such as partner IDs, statuses, date ranges, and pagination cursors. It also validates pagination cursor IDs to guarantee that provided cursors belong to the correct program.
Sources: apps/web/lib/api/commissions/get-commissions.ts:35-97
When commission queries include metadata filtering expressions, parseCommissionMetadataQuery validates and parses the raw query string. It normalizes quotes, verifies that logical operators (AND/OR) are not improperly mixed, checks condition limits, and splits the expression into distinct filter segments.
Sources: apps/web/lib/api/commissions/metadata-filters.ts:109-170
Each individual segment of the metadata query is passed to parseCondition. This function uses regular expressions to isolate the metadata key, operator, and raw value, ensuring keys adhere to valid identifier rules and that empty or malformed conditions are rejected.
Sources: apps/web/lib/api/commissions/metadata-filters.ts:34-83
The mapOperator helper translates raw operator tokens (such as =, :, or !=) into internal CommissionMetadataFilterOp representations (equals or notEquals). If an unsupported operator is supplied, it throws a structured API error.
Sources: apps/web/lib/api/commissions/metadata-filters.ts:19-32
When validation failures occur—such as invalid metadata operators, keys containing forbidden characters, or invalid pagination cursors—the application throws a DubApiError instance. The top-level POST catch block captures this error, logs it via Axiom, and converts it into a standardized JSON error response with appropriate HTTP status codes.
Sources: apps/web/lib/api/errors.ts:44-61, apps/web/lib/api/errors.ts:106-131
Sources: apps/web/app/(ee)/api/cron/export/commissions/route.ts:75-79, apps/web/app/(ee)/api/cron/export/commissions/fetch-commissions-batch.ts:19-33, apps/web/lib/api/commissions/get-commissions.ts:58-96, apps/web/lib/api/commissions/metadata-filters.ts:19-168, apps/web/lib/api/errors.ts:44-61
Sources: apps/web/app/(ee)/api/cron/export/commissions/route.ts:23-79, apps/web/lib/api/commissions/get-commissions.ts:58-208, apps/web/lib/api/commissions/metadata-filters.ts:19-168, apps/web/lib/api/errors.ts:44-61
DubApiError is caught at the root API handler, logged to Axiom, and returned with precise HTTP status mapping.