Skip to content

armgit / dub

Public Imported from GitHub
0

The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
index 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>
+ </>
+ );
+ }
+}