Affiliate Program Add-on Guide for Larapen

Let other people sell for you. Partners get a referral link, a library of ready-made banners and a dashboard of their own; every sale their link brings in credits a commission you decide the size of, holds it until the refund window has passed, and pays it out when they ask.

Use Cases

• Partner programme. Bloggers, reviewers and consultants send you customers and take a cut of each sale.
• Customer referrals. Existing customers share their link with colleagues and earn credit towards their own bill.
• Course and training resellers. Trainers promote your courses and are paid per enrollment, at a different rate from your shop.
• Offline and in-person referrals. A partner hands out a discount code; the sale is credited to them even though no link was ever clicked.
• Campaign-specific rates. One product pays 30% for a launch month while everything else stays at the standard rate.

Requirements

• Larapen CMS v1.0.0 or later
• PHP 8.3+
• MySQL 8.0+
• User accounts enabled on the front end, an affiliate signs in to see their dashboard

Installation

Step 1: Upload the Add-on

In the admin panel, go to Admin → Extensions → Add-ons and click the Upload Add-on button. Select the add-on’s ZIP file: the system extracts it automatically and the add-on appears in the installed add-ons list.

Step 2: Activate the Add-on

Find Affiliate & Referral in the list and click Activate. Its database tables and permissions are set up automatically, and the programme pages start answering straight away.

Step 3: Set Your Terms

Go to Admin → Affiliates → Settings and set the commission you pay, the tracking window, the hold period and the minimum payout. See Quick Start.

Purchase Code (License Key)

Affiliate & Referral is sold as a separate product, so it has its own purchase code (license key), distinct from the purchase code of the main application and from the one of every other add-on. You are asked for it when you activate Affiliate & Referral in Admin panel → Add-ons.

Our products are sold on three platforms. The way you receive a purchase code depends on where you bought the product.

Platform / Marketplace	How you get the purchase code	Where to find it again
bedigit.com Store In-site purchase (Shop)	Generated automatically when the order is paid, then sent by email, either in its own license email, or inside the order confirmation email.	My Account → My Licenses on bedigit.com
Gumroad	Created as soon as Gumroad notifies us of the sale, then sent in a separate email, in addition to the Gumroad receipt.	The license email, your Gumroad Library, and My Account → My Licenses on bedigit.com
Envato Market CodeCanyon	Issued by Envato, not by us, and never sent by email: you download it yourself from your Envato account.	Envato account → Downloads → License certificate & purchase code

1. bedigit.com Store (in-site purchase)

• As soon as the order’s payment status becomes Paid, a license key is generated automatically for every licensed item in the order (one key per purchased unit: buying 3 units gives 3 distinct keys).
• It is emailed to the address used on the order, either in a dedicated license email or inside the order confirmation email. Check your inbox and your spam / junk folder.
• The key stays available in your account under My Account → My Licenses. Keys are masked in the list; open the license detail page to reveal and copy the full key, see the domains it is activated on, and deactivate a domain to free an activation slot.
• The matching invoice is under My Account → My Orders.

2. Gumroad

• A Gumroad purchase produces two separate emails: the Gumroad receipt (sent by Gumroad, giving access to the files) and a license key email (sent by bedigit.com) that contains your purchase code.
• The license key email is generated as soon as Gumroad notifies us of the sale, so it normally arrives within seconds of the payment. Here too, check your inbox and your spam / junk folder.
• When the Gumroad product uses Gumroad’s own license-key feature, the same key also appears in your Gumroad receipt and under Library in your Gumroad account.

3. Envato Market (CodeCanyon)

• Envato issues the purchase code itself. We never send it by email, because we do not receive it.
• Get it from your Envato account: Downloads → find the item → License certificate & purchase code (the text or PDF version both contain it).
• It looks like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Quick Start

Five minutes from activation to a live programme.

1. Set what you pay. Admin → Affiliates → Settings → Commissions. Pick a percentage of the sale or a fixed amount, and set the hold period (30 days is a sensible default: it covers most refund windows).
2. Set how long a click lasts. Settings → Tracking. Thirty days means a visitor who follows a link today still earns their referrer a commission if they buy three weeks from now.
3. Set the payout floor. Settings → Payouts. Partners cannot ask to be paid below it, which keeps you from processing a string of tiny transfers.
4. Write your terms. Settings → Programme → Programme terms. They appear on the public terms page and are linked from the application form, which applicants must tick to accept.
5. Add a banner or two. Admin → Affiliates → Banners. Optional, but partners promote you far more readily when the material is ready to paste.
6. Link the programme. Add /affiliates to a menu (see Adding It to a Menu) so people can find it.

Affiliates

An affiliate is one of your users with a referral code attached. One user, one affiliate account.

Applications

A signed-in visitor applies from /affiliates/apply. The form asks for their website (optional), how they plan to promote you, how they want to be paid, and requires them to accept your terms.

What happens next depends on one setting:

• Approve applications automatically: off (the default): the application is filed as Pending review, administrators are notified, and nothing is tracked for that person until you approve them.
• Approve applications automatically: on: the applicant is earning the moment they submit the form. Right for a customer referral scheme, risky for an open partner programme.

You can also add a partner by hand from Affiliates → Add an affiliate, which is how you onboard someone you agreed terms with offline.

To stop accepting newcomers while keeping the programme running for existing partners, turn Accept new applications off. The programme pages stay up and commissions keep accruing; only the application form is closed.

Statuses

Status	What it means	Do links earn?
Pending review	Applied, waiting on you.	No
Approved	Live. The only status that earns.	Yes
Rejected	Turned down. The reason you give is shown to them and sent by email.	No
Suspended	Paused, usually while you look into something.	No

Referral Codes

Every affiliate gets a short code: eight characters, with the ambiguous ones (0/O, 1/I) left out, because these codes get read out loud and printed. You can replace a code with something memorable when you create or edit the affiliate: letters and digits only.

Issue a new code on the affiliate’s page revokes the old one immediately. Any link already shared with it stops earning, so use it only when a code has leaked.

How Referrals Are Tracked

Links & Short Links

An affiliate has two forms of the same link:

• The short link: https://your-site.example/r/THEIRCODE. Short enough for a business card or a video description.
• A tracked link to any page: any URL on your site with ?ref=THEIRCODE on the end. Their dashboard builds these for them: they paste a path, it hands back the full link.

Both record the click and set the same cookie, so it makes no difference which one a partner uses. The short link can also carry a destination: /r/THEIRCODE?to=/shop lands the visitor in your shop. Only paths of your own site are followed: anything pointing elsewhere goes to the home page instead.

The Tracking Window

A click is remembered for as long as you set under Settings → Tracking → Tracking window (30 days by default). Inside that window, any sale the visitor makes pays a commission. Outside it, nothing is credited.

The window is kept in two places: a cookie in the visitor’s browser, and, as soon as they sign in, on their account. The second one matters: a payment confirmed by a payment provider minutes later arrives without any browser or cookie attached, and the account record is what lets that sale still find its referrer.

Attribution Model

When a visitor follows links from two different partners, one of them has to win:

• Last click wins (the default): the most recent link takes the sale. The usual choice, and the one partners expect.
• First click wins: whoever introduced the visitor keeps them for the whole window, whatever happens afterwards. Fairer to the partner who did the discovery work.

Coupon Codes

Link a discount code to an affiliate from their page, under Linked coupon codes. Any sale made with that code is credited to them even when no referral link was ever followed, which is how a partner who works offline, on a podcast or on a printed flyer gets paid.

Create the discount code itself where you normally would; this screen only records who owns it. A referral link always takes priority: the coupon is consulted only when no click can be found.

Self-Referrals

An affiliate is never paid for their own purchase. It is checked on the click and again on the sale, so neither signing in later nor using their own coupon gets around it.

Commissions

Where Sales Come From

The programme does not sell anything itself: it listens to the add-ons that do. Each of these is optional, and one that is not installed simply never reports anything.

Source	What counts as a sale
Shop	An order that turns paid: products, pre-paid service plans and update-access renewals alike.
Courses	An enrollment that is paid for.
Wallet top-ups	A credit pack that is bought.
Stock media	A media purchase that is paid.
Invoices	An invoice marked paid. Invoices generated automatically from another source are skipped, so the same sale is never paid twice.

Commission Rules

Admin → Affiliates → Commission Rules. Without a single rule, every sale pays the programme default. Add rules to pay differently on part of your catalogue, for one source, or for one partner.

Rules are checked from the most specific to the most general, and the first match wins:

1. One affiliate: a rate agreed with one partner by name.
2. One product: a launch rate on a single item.
3. One category: everything in a section of your catalogue.
4. One source: all course enrollments, or all top-ups.
5. Everything: your house rate.

Two rules of the same kind are separated by Priority: highest first. A rule can also carry a minimum sale amount, below which it is skipped and the next rule down applies.

Volume Tiers

Admin → Affiliates → Volume Tiers. Optional. A tier raises a partner’s rate automatically once their lifetime referred sales pass a threshold: 12% from $2,500, 15% from $10,000, and so on.

A partner is always placed in the highest tier they have reached, and their dashboard shows how far they are from the next one. Tiers are only consulted when no commission rule and no per-affiliate rate apply.

The Hold Period

A new commission is On hold. It stays that way for the number of days you set under Settings → Commissions → Hold period, which should cover the window in which a buyer can still ask for their money back.

Once the hold has run out, a nightly task moves it to Approved: that is, payable. To review every commission by hand instead, turn Approve automatically after the hold off; they then wait for you on the Commissions screen.

Impatient? Release cleared commissions on that screen approves everything whose hold has already passed, without waiting for the nightly run.

Refunds & Reversals

When a sale leaves the paid state (refunded, cancelled or charged back) its commission is reversed and comes off the partner’s balance. That is what the hold period is for: in the normal case, the money was never payable in the first place.

A commission that has already been paid out is never clawed back automatically. The money has left, and what to do about it is a decision for a person, not a rule.

You can also reverse or reject a commission by hand from the Commissions screen, with a reason.

Payouts

How the Balance Works

Three numbers, and they mean different things:

• On hold: earned, still inside the refund window. Not payable yet.
• Available: approved commissions, minus anything a pending payout request already covers. This is what a partner can ask for right now.
• Paid to date: what has actually been handed over.

Requesting a payout reserves the amount immediately, so a partner cannot request the same commissions twice while the first request is being processed.

Payout Methods

Method	How it settles
Wallet credits	Credits are added to the partner’s wallet through the wallet ledger the moment you mark the payout paid. Needs the wallet add-on; set how many credits one unit of your currency buys under Settings → Payouts.
Bank transfer	You move the money yourself, then record it here with its reference.
PayPal	Same: you send it, then record it.

Turn off any method you do not offer and partners will not see it. The details a partner gives (bank account, PayPal address) are stored encrypted, and a copy is frozen onto each payout request, so changing them later cannot rewrite the record of a payout you already made.

Settling a Payout

1. The request arrives at Admin → Affiliates → Payouts and administrators are notified.
2. Optionally mark it Approved while you get the transfer ready, useful when several people share the work.
3. Pay it, then click Mark as paid and record the transaction reference so the partner can match it against their own records.

Marking it paid stamps the commissions it covers as Paid, ties them to the payout, updates the partner’s totals and emails them. A wallet payout does its crediting at that same moment.

Export CSV gives you the current selection as a spreadsheet (names, amounts, methods and payout details), which is what you feed to a bank’s batch transfer form.

Banners & Links

Admin → Affiliates → Banners. Anything you publish here appears in every approved partner’s dashboard, already carrying their own referral code. Three kinds:

• Banner image: pick an image and give its size. Partners copy a ready-made snippet with the image wrapped in their tracked link.
• HTML snippet: write the markup yourself; {link} is replaced with the partner’s link. Right for a styled button or a small promo block.
• Text link: just the tracked URL, plus a suggested wording for a newsletter or a signature.

Lands on decides where the banner sends the visitor, as a path (/shop, for example). Leave it empty for your home page. Titles and descriptions are translatable, so a partner sees them in their own language.

The Affiliate Area

Signed-in partners get four pages of their own, linked from the account menu:

Page	What is on it
/affiliates/dashboard	Balances, their link and the link builder, clicks and conversion rate, their tier and how far the next one is, and their latest commissions.
/affiliates/conversions	Every commission, filterable by status, showing the sale behind it and when a held one clears.
/affiliates/creatives	The banner library, each snippet ready to copy.
/affiliates/payouts	Payout history, the request form, and where to change how they want to be paid.

The public pages are /affiliates (what the programme pays and how to join) and /affiliates/terms. Those two are indexable; every personal page is not.

Adding It to a Menu

Go to Admin → Appearance → Menus, open the menu you want (your footer is the usual home for a partner programme), and add an item of type Custom URL pointing at /affiliates.

The affiliate’s own dashboard needs no menu work: Affiliate account is added to the signed-in account dropdown automatically while the add-on is active.

Notifications

Six notifications, each switchable under Admin → Settings → Notifications:

Notification	Goes to	When
New affiliate application	Administrators	Someone applies to join
Affiliate application approved	The applicant	You approve them, carries their referral code and link
Affiliate application rejected	The applicant	You turn them down, carries your reason, if you gave one
Commission earned	The affiliate	A referred sale credits them
Payout requested	Administrators	A partner asks to be paid
Payout paid	The affiliate	You settle their payout

Each is delivered by email and as a bell notification in the panel. The three that carry a decision about someone’s account (approved, rejected, paid) are always sent, because a partner needs to know.

Multi-Language

Every screen, email and public page is translated into the languages the add-on ships with, and follows the visitor’s language automatically.

Two things you write yourself are translatable per language:

• Programme terms, under Settings → Programme.
• Banner titles, descriptions and text, on each banner.

Use the language selector above those fields to switch. A language you leave empty falls back to your default one.

Privacy & Retention

• Addresses are never stored. A click keeps a one-way hash of the visitor’s IP address: enough to recognise a repeat visit, never enough to recover the address.
• Payout details are encrypted. Bank and PayPal details are encrypted in the database and shown only to administrators who can see payouts.
• Clicks are pruned. Clicks that never led to a sale are deleted after the number of days set under Settings → Tracking → Keep click records for (180 by default; 0 keeps them forever). Clicks that did convert are kept, because they are the evidence behind a commission.
• The tracking cookie holds nothing but an internal reference, is limited to your own site and expires with the tracking window.

Settings

Admin → Affiliates → Settings, in five tabs.

Programme

Setting	What it does
Affiliate programme	The master switch. Off, links stop being tracked and no new commission is recorded; nothing already earned is lost.
Accept new applications	Closes the application form without closing the programme.
Approve applications automatically	On, an applicant earns immediately. Off, you review each one.
Programme terms	Shown on the public terms page and linked from the application form.

Tracking

Setting	What it does
Tracking window	How long after a click a sale still pays a commission.
Attribution model	Last click or first click: see Attribution Model.
Attribute by coupon code	Credits sales made with a coupon linked to a partner.
Keep click records for	Retention for clicks that never converted. 0 keeps them forever.

Commissions

Setting	What it does
Default commission type / value	A percentage of the sale, or a fixed amount per sale.
Exclude tax and shipping	Pay on what the sale earns, not on charges you pass on.
Hold period	Days a commission waits before it can be approved.
Approve automatically after the hold	Off, every commission waits for you.
Reverse on refund	Takes the commission back when the sale behind it goes away.

Payouts

Setting	What it does
Minimum payout	The floor a balance must clear before a partner can ask to be paid.
Payout currency	What balances and thresholds are shown in. Empty follows the site default.
Pay in wallet credits	Offers wallet credits as a method, and sets how many credits one unit buys.
Pay by bank transfer / PayPal	Offers the two manual methods.

Page Header

Overrides the look of the header on the programme’s public pages (height, background, colours) without touching the rest of your site.

Permissions

The add-on registers its own permissions, assignable per role under Admin → Users → Roles.

Permission	Grants
affiliate.dashboard.view	The programme dashboard and its widgets
affiliate.affiliates.*	View, create, edit and delete affiliates; approve, reject and suspend them
affiliate.conversions.*	View, edit (approve / reject / reverse) and export commissions
affiliate.payouts.*	View, settle and export payouts
affiliate.rules.*	View, create, edit and delete commission rules and volume tiers
affiliate.creatives.*	View, create, edit and delete banners
affiliate.settings.*	View and change the settings

Scheduled Tasks

One task runs daily and does two things: it approves the commissions whose hold period has run out, and it deletes clicks that never converted and are past their retention.

It runs as part of your site’s scheduler, so nothing needs setting up as long as the scheduler itself is running. If it is not, commissions simply stay On hold until you click Release cleared commissions on the Commissions screen, nothing is lost, it just does not happen on its own.

Updating

Upload the new ZIP from Admin → Extensions → Add-ons exactly as you did the first time. The files are replaced, any new database changes are applied, and your affiliates, commissions, payouts, rules, tiers, banners and settings are all kept.

Deactivating

Switching the add-on off without losing anything is a deactivation: go to Admin panel → Add-ons, find Affiliate & Referral and click Deactivate.

• Its routes, views, admin menu entries and permissions stop being registered; the programme pages and the /r/<code> links stop answering.
• Referral links stop being tracked and no new commission is recorded.
• Its database tables and all the data they hold are kept (every affiliate, commission and payout) and its files stay under extensions/addons/affiliate/. Nothing is deleted.
• The purchase code recorded at activation is kept too, so activating the add-on again does not ask for it.
• Deactivation is refused while another active add-on depends on this one: deactivate that add-on first.

Click Activate on the same card to switch it back on. Pending migrations are re-run and the programme picks up exactly where it left off.

Removing

Removing is permanent and destroys the add-on’s data. The Remove button only appears on a deactivated add-on, so removal is always two steps:

1. Deactivate Affiliate & Referral (see Deactivating).
2. Click Remove on its card and confirm the prompt.

The admin panel then, in one pass:

• runs the add-on’s uninstall hook, if it ships one, while its code is still on disk;
• revokes the permissions declared in its addon.json;
• rolls back its migrations, this drops its database tables and every row they hold, including every affiliate account, every commission ever recorded and the whole payout history, and purges its entries from the migrations table, so a later reinstall migrates from scratch;
• deletes its published assets: public/addons/affiliate/, public/vendor/affiliate/ and storage/app/public/addons/affiliate/;
• deletes the add-on directory extensions/addons/affiliate/;
• deletes its row in the addons table (the recorded purchase code goes with it) and clears the application cache.

Removal is refused, with an explanatory message and before anything is destroyed, when the add-on is still active, when another active add-on depends on it, or when the web server (PHP) user cannot delete extensions/addons/affiliate/. In that last case, give that user write permission on the directory and on its parent, then try again.

Deleting the folder over FTP or SSH is not equivalent: the add-on’s tables, its entries in the migrations table and its addons row are all left behind, and its card stays in the list. Use Remove in the admin panel instead.

Troubleshooting

A sale was not credited to the partner who sent the buyer

• Check the affiliate is Approved. Pending, rejected and suspended partners earn nothing.
• Check the click is still inside the tracking window. A visitor who clicked six weeks ago on a 30-day window is no longer attributed.
• Check it is not a self-referral: a partner buying with their own link is never paid.
• Check the buyer did not follow a different partner’s link more recently, under Last click wins.
• If the buyer was never signed in and their browser blocks cookies, there is nothing left to attribute with. A coupon code is the reliable fallback for that case.

Commissions are stuck on hold

• They clear only once the hold period has passed. Their row shows the date.
• Approve automatically after the hold may be off, in which case they are waiting for you on purpose.
• The scheduler may not be running. Use Release cleared commissions on the Commissions screen in the meantime.

A partner cannot request a payout

• Their Available balance must be at or above the minimum payout. Commissions still on hold do not count.
• They may already have a request in progress, which reserves the amount it covers until it is settled.
• At least one payout method must be enabled, and for bank or PayPal they must have filled in their details.

Wallet payouts are not offered

Wallet credits need the wallet add-on installed and active. Without it the method is hidden from partners and cannot be enabled in the settings.

The programme pages return "page not found"

• The add-on may be deactivated. Check Admin → Extensions → Add-ons.
• Affiliate programme may be switched off in the settings, which hides the public pages.

A translated label is not showing

• Pick the language in the selector above the field and check it is filled in for that language: each one is stored separately.
• Empty translations fall back to your default language, which is usually what you want.