Run an affiliate program
Set the program terms, give partners referral codes, turn their orders into commissions and review payouts in the admin console.
The affiliate module gives partners referral codes, turns their referred orders into commissions, and records your decision on each payout request. You review payouts by hand. The module does not move money.
Before you begin
- A project that runs locally. See Quick start. The
affiliatemodule is part of the base repository;pnpm db:bootstrap-super-adminwrites theaffiliates.readandaffiliates.writepermissions and the default program. - An admin account with
affiliates.readto open the pages andaffiliates.writeto submit any form. - The partner's user ID, the last part of their
/admin/users/<id>URL.
The console has no sidebar entry. Open /admin/affiliates directly (/zh/admin/affiliates for the Chinese console).
Grant affiliate access
Assign the Commerce Manager role
Go to Overview → Users (/admin/users/dashboard), open the user's details and click Roles. Tick Commerce Manager and click Save roles. That role also includes the order, subscription, product, licence and credit permissions.
Or add the permissions to your own role
Go to Operations → Roles (/admin/roles), click Edit on the role and tick affiliates.read and affiliates.write under Permissions (in the Other group). Click Save role.
Set the program terms
The default program pays 20% commission with a 30-day cookie window, a $50.00 minimum payout, in USD.
Open Program settings
Open the Program settings tab (/admin/affiliates/settings). The cards show the current terms.
Fill in Program terms
- Commission rate (%): the share of the order amount paid as commission, for example
20. It cannot exceed 100%. - Cookie window (days): from 1 to 365. A conversion counts only within this many days of the referral being created.
- Minimum payout: the smallest payout request accepted, for example
50.00. - Currency: a three-letter ISO 4217 code such as
USD. - Status: Active, or Paused to stop recording conversions and accepting payout requests.
Save
Click Save program settings. The page shows Program settings saved and audit log recorded.
New terms apply to later conversions and payout requests. Commissions already recorded keep their amount.
Create referral codes
Open Create referral
On Overview or Referrals, find the Create referral form.
Fill it in
- Affiliate user: the partner's user ID.
- Referral code: the code the partner shares. It is stored in upper case with spaces replaced by hyphens, so
partner acmebecomesPARTNER-ACME. - Referred email: optional.
Click Create referral. A code that already exists is kept as it was, without an error.
Record a conversion
Checkout does not attribute orders to referral codes on its own, so you record each partner order.
Confirm the order is paid
Check the order in Commerce → Orders (/admin/orders).
Fill in Record conversion
On Commissions or Overview, enter the Referral code, the Order ID and the Order amount cents (29000 for $290.00). Click Record conversion.
The commission is the order amount times the program rate, rounded down, and starts as pending.
To attribute orders automatically instead, call the service from your settlement code after the provider webhook confirms the order:
import { recordConversion } from "@/server/services/affiliate-operations.service";
await recordConversion({
referralCode: "PARTNER-ACME",
orderId: order.id,
orderAmountCents: order.amountCents,
});Review a payout
Payout requests appear on Withdrawals. No page creates them. Your own server code creates them.
Find the payout ID
Copy it from the Payout column on Withdrawals.
Decide
Go to Review, enter the Payout ID and a Review note, then click Approve payout or Reject payout. The decision is saved with you as reviewer.
Pay the partner
Send the money through your own payment channel. The module only records the decision.
Verify
- Create a referral with your own user ID and the code
TEST-PARTNER. - Record a conversion for
TEST-PARTNERwith Order amount cents30000. - With the default 20% rate, Commissions lists a pending $60.00 commission, the referral on Referrals shows as converted, and Security → Audit (
/admin/audit) records both actions.
In the repository, run pnpm validate:affiliate.
Troubleshooting
"Affiliate program is not configured" or the pages say "No affiliate records yet"
No program exists yet. Run pnpm db:seed-baseline to create the default program. Running it again keeps your settings.
"Referral code is not active"
No referral has that code. Codes are compared after trimming, upper-casing and replacing spaces with hyphens, so check the code on Referrals.
"Affiliate program is paused; …"
Status on Program settings is Paused. Set it to Active and save.
"Conversion is outside the N-day attribution window for this referral."
The referral was created more than Cookie window (days) ago. Use a newer referral, or raise the cookie window.
"Payout amount is below the program minimum of N cents."
Request at least Minimum payout, or lower the minimum on Program settings.