The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.
TypeScript clickhousemysqlnextjsopen-sourceplanetscaleprismatailwindcsstinybirdtypescriptupstashvercel
Add manual referring partner attribution with commission backfill
Kiran K24c9a3f69dbf
diff --git a/apps/web/app/(ee)/api/cron/commissions/referrals/backfill/route.ts b/apps/web/app/(ee)/api/cron/commissions/referrals/backfill/route.tsnew file mode 100644index 0000000000..de8eccaf1d--- /dev/null+++ b/apps/web/app/(ee)/api/cron/commissions/referrals/backfill/route.ts@@ -0,0 +1,134 @@+import { enqueueBatchJobs } from "@/lib/cron/enqueue-batch-jobs";+import { withCron } from "@/lib/cron/with-cron";+import { referralRewardConfigSchema } from "@/lib/zod/schemas/rewards";+import { prisma } from "@dub/prisma";+import { CommissionType } from "@dub/prisma/client";+import { APP_DOMAIN_WITH_NGROK, chunk } from "@dub/utils";+import * as z from "zod/v4";+import { logAndRespond } from "../../../utils";++export const dynamic = "force-dynamic";++const inputSchema = z.object({+ programId: z.string(),+ partnerId: z.string(),+});++// POST /api/cron/commissions/referrals/backfill+export const POST = withCron(async ({ rawBody }) => {+ const { programId, partnerId } = inputSchema.parse(JSON.parse(rawBody));++ const applicationEvent = await prisma.programApplicationEvent.findUnique({+ where: {+ programId_partnerId: {+ programId,+ partnerId,+ },+ },+ select: {+ referredByPartnerId: true,+ },+ });++ if (!applicationEvent) {+ return logAndRespond(+ `Application event not found for partner ${partnerId} in program ${programId}. Skipping...`,+ );+ }++ const { referredByPartnerId } = applicationEvent;++ if (!referredByPartnerId) {+ return logAndRespond(+ `Application event for partner ${partnerId} in program ${programId} has no referred by partner. Skipping...`,+ );+ }++ const referrerEnrollment = await prisma.programEnrollment.findUnique({+ where: {+ partnerId_programId: {+ partnerId: referredByPartnerId,+ programId,+ },+ },+ select: {+ referralReward: true,+ },+ });++ if (!referrerEnrollment) {+ return logAndRespond(+ `Referrer program enrollment not found for partner ${referredByPartnerId} in program ${programId}. Skipping...`,+ );+ }++ const { referralReward } = referrerEnrollment;++ if (!referralReward) {+ return logAndRespond(+ `Referrer has no referral reward. Skipping past commission backfill.`,+ );+ }++ const { trigger } = referralRewardConfigSchema.parse(referralReward.config);++ if (["commissionThreshold", "partnerApproved"].includes(trigger)) {+ await enqueueBatchJobs([+ {+ queueName: "create-referral-commissions",+ url: `${APP_DOMAIN_WITH_NGROK}/api/cron/commissions/referrals/create`,+ body: {+ programId,+ partnerId,+ },+ },+ ]);++ return logAndRespond(+ `Enqueued 1 referral commission job for partner ${partnerId}.`,+ );+ }++ if (["saleRecorded", "commissionEarned"].includes(trigger)) {+ const commissions = await prisma.commission.findMany({+ where: {+ programId,+ partnerId,+ type: CommissionType.sale,+ status: {+ in: ["pending", "processed", "paid"],+ },+ },+ select: {+ id: true,+ },+ });++ if (commissions.length === 0) {+ return logAndRespond(+ `No eligible sale commissions found for partner ${partnerId}.`,+ );+ }++ for (const commissionChunk of chunk(commissions, 50)) {+ await enqueueBatchJobs(+ commissionChunk.map((commission) => ({+ queueName: "create-referral-commissions",+ url: `${APP_DOMAIN_WITH_NGROK}/api/cron/commissions/referrals/create`,+ deduplicationId: `create-referral-commissions-${commission.id}`,+ body: {+ sourceCommissionId: commission.id,+ },+ })),+ );+ }++ return logAndRespond(+ `Enqueued ${commissions.length} referral commission jobs for partner ${partnerId}.`,+ );+ }++ return logAndRespond(+ `Referral reward trigger "${trigger}" does not support past event backfill. Skipping...`,+ );+});diff --git a/apps/web/lib/partner-referrals/attribute-referring-partner.ts b/apps/web/lib/partner-referrals/attribute-referring-partner.tsnew file mode 100644index 0000000000..71b3a76d1b--- /dev/null+++ b/apps/web/lib/partner-referrals/attribute-referring-partner.ts@@ -0,0 +1,149 @@+"use server";++import { DubApiError } from "@/lib/api/errors";+import { getDefaultProgramIdOrThrow } from "@/lib/api/programs/get-default-program-id-or-throw";+import { getProgramEnrollmentOrThrow } from "@/lib/api/programs/get-program-enrollment-or-throw";+import { prisma } from "@dub/prisma";+import { APP_DOMAIN_WITH_NGROK } from "@dub/utils";+import { subHours, subMinutes } from "date-fns";+import { authActionClient } from "../actions/safe-action";+import { throwIfNoPermission } from "../actions/throw-if-no-permission";+import { createId } from "../api/create-id";+import { qstash } from "../cron";+import { attributeReferringPartnerSchema } from "./schemas";++export const attributeReferringPartnerAction = authActionClient+ .inputSchema(attributeReferringPartnerSchema)+ .action(async ({ parsedInput, ctx }) => {+ const { workspace } = ctx;+ const { partnerId, referredByPartnerId, createCommissionsForPastEvents } =+ parsedInput;++ throwIfNoPermission({+ role: workspace.role,+ requiredRoles: ["owner", "member"],+ });++ if (referredByPartnerId === partnerId) {+ throw new DubApiError({+ code: "bad_request",+ message: "A partner cannot refer themselves.",+ });+ }++ const programId = getDefaultProgramIdOrThrow(workspace);++ const [programEnrollment, referringProgramEnrollment] = await Promise.all([+ getProgramEnrollmentOrThrow({+ partnerId,+ programId,+ include: {+ applicationEvent: {+ select: {+ referredByPartnerId: true,+ },+ },+ application: {+ select: {+ createdAt: true,+ },+ },+ },+ }),++ // Check the referring partner is enrolled in the program+ getProgramEnrollmentOrThrow({+ partnerId: referredByPartnerId,+ programId,+ include: {+ applicationEvent: {+ select: {+ referredByPartnerId: true,+ },+ },+ partner: {+ select: {+ country: true,+ },+ },+ referralReward: true,+ },+ }),+ ]);++ if (programEnrollment.status !== "approved") {+ throw new DubApiError({+ code: "bad_request",+ message:+ "Only approved partners can be attributed a referring partner.",+ });+ }++ if (referringProgramEnrollment.status !== "approved") {+ throw new DubApiError({+ code: "bad_request",+ message: "The referring partner is not approved.",+ });+ }++ if (programEnrollment.applicationEvent?.referredByPartnerId) {+ throw new DubApiError({+ code: "bad_request",+ message: "This partner already has a referring partner.",+ });+ }++ if (+ referringProgramEnrollment.applicationEvent?.referredByPartnerId ===+ partnerId+ ) {+ throw new DubApiError({+ code: "bad_request",+ message:+ "This referral relationship is not allowed because it would create a referral loop.",+ });+ }++ // Attribute the referring partner to the application+ const baseDate =+ programEnrollment.application?.createdAt ?? programEnrollment.createdAt;++ await prisma.programApplicationEvent.upsert({+ where: {+ programId_partnerId: {+ programId,+ partnerId,+ },+ referredByPartnerId: null,+ },+ update: {+ referredByPartnerId,+ },+ create: {+ id: createId({ prefix: "pga_evt_" }),+ programId,+ partnerId,+ referredByPartnerId,+ referralSource: "manual",+ country: referringProgramEnrollment.partner.country,+ visitedAt: subHours(baseDate, 1),+ startedAt: baseDate,+ submittedAt: subMinutes(baseDate, 1),+ approvedAt: programEnrollment.createdAt,+ },+ });++ if (+ createCommissionsForPastEvents &&+ referringProgramEnrollment.referralReward+ ) {+ await qstash.publishJSON({+ url: `${APP_DOMAIN_WITH_NGROK}/api/cron/commissions/referrals/backfill`,+ body: {+ programId,+ partnerId,+ referredByPartnerId,+ },+ });+ }+ });diff --git a/apps/web/lib/partner-referrals/components/attribute-referring-partner-modal.tsx b/apps/web/lib/partner-referrals/components/attribute-referring-partner-modal.tsxnew file mode 100644index 0000000000..4503171e21--- /dev/null+++ b/apps/web/lib/partner-referrals/components/attribute-referring-partner-modal.tsx@@ -0,0 +1,182 @@+"use client";++import { mutatePrefix } from "@/lib/swr/mutate";+import useGroup from "@/lib/swr/use-group";+import useWorkspace from "@/lib/swr/use-workspace";+import { EnrolledPartnerProps } from "@/lib/types";+import { DEFAULT_PARTNER_GROUP } from "@/lib/zod/schemas/groups";+import { PartnerAvatar } from "@/ui/partners/partner-avatar";+import { PartnerSelector } from "@/ui/partners/partner-selector";+import { Markdown } from "@/ui/shared/markdown";+import { Button, Modal, Switch } from "@dub/ui";+import { useAction } from "next-safe-action/hooks";+import {+ Dispatch,+ SetStateAction,+ useCallback,+ useMemo,+ useState,+} from "react";+import { toast } from "sonner";+import { attributeReferringPartnerAction } from "../attribute-referring-partner";++function AttributeReferringPartnerModal({+ showModal,+ setShowModal,+ partner,+}: {+ showModal: boolean;+ setShowModal: Dispatch<SetStateAction<boolean>>;+ partner: Pick<+ EnrolledPartnerProps,+ "id" | "name" | "email" | "image" | "groupId"+ >;+}) {+ const { id: workspaceId } = useWorkspace();+ const [referredByPartnerId, setReferredByPartnerId] = useState<string | null>(+ null,+ );+ const [createCommissionsForPastEvents, setCreateCommissionsForPastEvents] =+ useState(false);++ const { group } = useGroup({+ groupIdOrSlug: partner.groupId || DEFAULT_PARTNER_GROUP.slug,+ });++ const showCommissionToggle = group?.referralReward?.type === "percentage";++ const { executeAsync, isPending } = useAction(+ attributeReferringPartnerAction,+ {+ onSuccess: async () => {+ await mutatePrefix("/api/partners");+ toast.success("Referring partner attributed successfully!");+ setShowModal(false);+ },+ onError({ error }) {+ toast.error(error.serverError);+ },+ },+ );++ const onSubmit = useCallback(async () => {+ if (!workspaceId || !referredByPartnerId) return;++ await executeAsync({+ workspaceId,+ partnerId: partner.id,+ referredByPartnerId,+ createCommissionsForPastEvents,+ });+ }, [+ executeAsync,+ workspaceId,+ partner.id,+ referredByPartnerId,+ createCommissionsForPastEvents,+ ]);++ return (+ <Modal showModal={showModal} setShowModal={setShowModal}>+ <div className="border-b border-neutral-200 p-4 sm:p-6">+ <h3 className="text-lg font-medium leading-none">+ Attribute referring partner+ </h3>+ </div>++ <div className="flex flex-col gap-6 bg-neutral-50 p-4 sm:p-6">+ <Markdown className="text-sm font-normal leading-5 text-neutral-600">+ Attribute this partner to the partner who referred them and generate+ eligible referral rewards. [Learn+ more](https://dub.co/help/article/referring-partners)+ </Markdown>++ <div className="rounded-lg border border-neutral-200 bg-neutral-100 p-3">+ <div className="flex items-center gap-4">+ <PartnerAvatar partner={partner} className="size-10 bg-white" />+ <div className="flex min-w-0 flex-col">+ <h4 className="truncate text-sm font-medium text-neutral-900">+ {partner.name}+ </h4>+ <p className="truncate text-xs text-neutral-500">+ {partner.email}+ </p>+ </div>+ </div>+ </div>++ <div>+ <label className="block text-sm font-medium text-neutral-900">+ Referring partner+ </label>+ <div className="mt-1.5">+ <PartnerSelector+ selectedPartnerId={referredByPartnerId}+ setSelectedPartnerId={setReferredByPartnerId}+ />+ </div>+ </div>++ {showCommissionToggle && (+ <div className="flex items-center gap-3">+ <Switch+ checked={createCommissionsForPastEvents}+ fn={setCreateCommissionsForPastEvents}+ />++ <span className="text-sm font-medium text-neutral-800">+ Create commissions for eligible past events+ </span>+ </div>+ )}+ </div>++ <div className="border-border-subtle flex items-center justify-end gap-2 border-t px-4 py-4">+ <Button+ onClick={() => setShowModal(false)}+ variant="secondary"+ text="Cancel"+ className="h-8 w-fit px-3"+ disabled={isPending}+ />+ <Button+ onClick={onSubmit}+ variant="primary"+ text="Attribute partner"+ disabled={!referredByPartnerId}+ loading={isPending}+ className="h-8 w-fit px-3"+ />+ </div>+ </Modal>+ );+}++export function useAttributeReferringPartnerModal({+ partner,+}: {+ partner: Pick<+ EnrolledPartnerProps,+ "id" | "name" | "email" | "image" | "groupId"+ >;+}) {+ const [showModal, setShowModal] = useState(false);++ const AttributeReferringPartnerModalCallback = useCallback(() => {+ return (+ <AttributeReferringPartnerModal+ showModal={showModal}+ setShowModal={setShowModal}+ partner={partner}+ />+ );+ }, [showModal, setShowModal, partner]);++ return useMemo(+ () => ({+ setShowAttributeReferringPartnerModal: setShowModal,+ AttributeReferringPartnerModal: AttributeReferringPartnerModalCallback,+ }),+ [setShowModal, AttributeReferringPartnerModalCallback],+ );+}diff --git a/apps/web/lib/partner-referrals/hooks/use-partner-referral.ts b/apps/web/lib/partner-referrals/hooks/use-partner-referral.tsindex 439113b43e..d117d774d0 100644--- a/apps/web/lib/partner-referrals/hooks/use-partner-referral.ts+++ b/apps/web/lib/partner-referrals/hooks/use-partner-referral.ts@@ -15,6 +15,9 @@ export function usePartnerReferral({? `/api/partners/${partnerId}/referral?workspaceId=${workspaceId}`: null,fetcher,+ {+ keepPreviousData: true,+ },);return {diff --git a/apps/web/lib/partner-referrals/schemas.ts b/apps/web/lib/partner-referrals/schemas.tsindex 4deb5ca72e..9caf7a01c7 100644--- a/apps/web/lib/partner-referrals/schemas.ts+++ b/apps/web/lib/partner-referrals/schemas.ts@@ -73,3 +73,10 @@ export const networkReferralsTimeseriesSchema = z.object({partners: z.number().int().nonnegative(),earnings: z.number().int(),});++export const attributeReferringPartnerSchema = z.object({+ workspaceId: z.string(),+ partnerId: z.string(),+ referredByPartnerId: z.string(),+ createCommissionsForPastEvents: z.boolean().default(false),+});diff --git a/apps/web/ui/partners/partner-info-cards.tsx b/apps/web/ui/partners/partner-info-cards.tsxindex c98a173860..f22020b1bf 100644--- a/apps/web/ui/partners/partner-info-cards.tsx+++ b/apps/web/ui/partners/partner-info-cards.tsx@@ -1,3 +1,4 @@+import { useAttributeReferringPartnerModal } from "@/lib/partner-referrals/components/attribute-referring-partner-modal";import { usePartnerReferral } from "@/lib/partner-referrals/hooks/use-partner-referral";import useGroup from "@/lib/swr/use-group";import useWorkspace from "@/lib/swr/use-workspace";@@ -126,10 +127,6 @@ export function PartnerInfoCards({fetcher,);- const { referral } = usePartnerReferral({- partnerId: partner?.id,- });-let basicFields: BasicField[] = [{id: "country",@@ -198,29 +195,11 @@ export function PartnerInfoCards({: []),// Referred by- ...(referral && referral.referredBy- ? [- {- id: "referredBy",- icon: <UserArrowRight className="size-3.5 shrink-0" />,- text: (- <span className="flex min-w-0 items-center gap-1">- Referred by- <Link- href={`/${workspaceSlug}/program/partners/${referral.referredBy.id}`}- className="inline-flex min-w-0 max-w-full cursor-alias items-center gap-1 rounded decoration-dotted underline-offset-2 hover:underline"- >- <PartnerAvatar- partner={referral.referredBy}- className="size-3.5"- />- <span className="truncate">{referral.referredBy.name}</span>- </Link>- </span>- ),- },- ]- : []),+ {+ id: "referredBy",+ icon: <UserArrowRight className="size-3.5 shrink-0" />,+ text: <ReferredByPartner partner={partner} />,+ },]);}@@ -514,3 +493,68 @@ function TagsList({ partner }: { partner: EnrolledPartnerExtendedProps }) {</div>);}++function ReferredByPartner({+ partner,+}: {+ partner: Pick<+ EnrolledPartnerExtendedProps,+ "id" | "name" | "image" | "email" | "groupId"+ >;+}) {+ const { slug } = useWorkspace();++ const { referral, loading } = usePartnerReferral({+ partnerId: partner?.id,+ });++ const {+ AttributeReferringPartnerModal,+ setShowAttributeReferringPartnerModal,+ } = useAttributeReferringPartnerModal({ partner });++ if (loading) {+ return (+ <span className="flex min-w-0 items-center gap-1">+ <div className="h-4 w-24 animate-pulse rounded bg-neutral-200" />+ </span>+ );+ }++ // Has a referring partner+ if (referral && referral.referredBy) {+ return (+ <span className="flex min-w-0 items-center gap-1">+ Referred by+ <Link+ href={`/${slug}/program/partners/${referral.referredBy.id}`}+ className="inline-flex min-w-0 max-w-full cursor-alias items-center gap-1 rounded decoration-dotted underline-offset-2 hover:underline"+ >+ <PartnerAvatar partner={referral.referredBy} className="size-3.5" />+ <span className="truncate">{referral.referredBy.name}</span>+ </Link>+ </span>+ );+ }++ // No referring partner+ if (+ !referral?.referredBy &&+ "status" in partner &&+ partner.status === "approved"+ ) {+ return (+ <>+ <AttributeReferringPartnerModal />+ <button+ type="button"+ onClick={() => setShowAttributeReferringPartnerModal(true)}+ aria-label="Attribute referring partner"+ className="bg-bg-inverted/5 text-content-default hover:bg-bg-inverted/10 inline-flex h-6 min-h-6 min-w-0 select-none items-center whitespace-nowrap rounded-md px-1.5 py-0.5 text-xs font-medium"+ >+ Attribute referring partner+ </button>+ </>+ );+ }+}