Affiliates

The affiliates add-on lets other people sell for you and get paid when they do. Bloggers, YouTubers, podcast hosts, agencies and happy customers each get a link, a coupon code, or both. Their sales are credited to them without a spreadsheet, and one batch pays everyone at the end of the month. This page is for the store owner who wants to run a program.

It's an add-on, not part of KahunaCart itself. Install the kahunacart-affiliates plugin beside the base plugin. Until you add a partner or open applications, it does nothing to your orders.

What you get

• Links and coupons. A partner's link ends in ?ref= and their code. A partner's coupon credits every order that uses it, with or without a click. A podcast host with no account on your store can be a partner with just a coupon.
• Commissions that wait. A commission is written when the order is paid and waits out your refund window before it can be paid out.
• Refunds that follow. A refund takes back what the refunded items earned. If the partner was already paid, a negative amount comes off their next payout.
• Renewals. When a customer a partner referred pays for the next period of a subscription, the partner can earn again.
• One payout batch. Pay by store credit, by PayPal, or by hand with a bank file. The preview says who is left out and why.
• Tax details, as data. Partners fill in a W-9 or W-8BEN in their account. At year end you get the totals and an export. KahunaCart collects and totals this information. It doesn't file or give tax advice.
• A partner account. Partners see their link, clicks, commissions, payouts and tax form in an Affiliate tab of their customer account.

How a sale becomes a payout

1. A partner shares https://yourstore.com/shop?ref=andy, or a coupon code such as ANDY10.
2. A visitor opens the link. The store remembers the partner for 30 days. A visitor who types the partner's coupon at checkout is credited to the partner even if they never clicked the link.
3. When the order is paid, a commission is written. It's Pending for the holding period, 30 days by default.
4. A refund inside that time reduces or removes the commission. After it, the commission becomes Approved and joins the partner's balance.
5. You build a payout batch. Everyone whose balance has reached the minimum is in it, unless there's a reason to leave them out.
6. You run the batch. Each partner is paid and told by email.

The words used here

Before you begin

• KahunaCart 1.5.2 or later, Grav 2.0 or later and PHP 8.3 or later.
• The job worker running (bin/plugin kahunacart work, or the scheduler). Commissions mature, PayPal payouts are checked and partner emails go out as jobs. See CLI.
• Your licence covers the add-on. See How do add-ons work with my licence?.

Install the add-on

1. Install the plugin from Plugins in the admin, or from the command line:

bin/gpm install kahunacart-affiliates

2. Enable the plugin.
3. Give your staff the permissions they need, listed below.
4. On MySQL or PostgreSQL, apply the new tables with bin/plugin kahunacart migrate. SQLite stores do this on their own.

Affiliates now appears in the KahunaCart sidebar.

Add your first partner

Add a partner by hand, or open applications and let customers apply. You can do both.

Add a partner yourself

1. Open KahunaCart → Affiliates → Affiliates and click New affiliate.
2. Enter a Name and an Email. Either is enough on its own.
3. Leave Code empty to have one made from the name, or type your own. The code goes in their link, as in ?ref=surfreport. You can change it later on their page. The old code keeps working, so links they've already shared still credit them. See Codes and old codes.
4. Link a Customer account if the partner has one. A partner with an account sees their numbers in their account and can be paid in store credit.
5. Choose Tracking: Link and coupon, Link only, or Coupon only.
6. Under Coupon, pick Use an existing coupon, or Make a new one with a discount percent.
7. Click Add affiliate.

The partner starts Active. A coupon-only partner needs no account at all.

Open applications

1. Open KahunaCart → Affiliates → Settings and go to the Program tab.
2. Switch Open Applications on.
3. Optionally switch Approve Automatically on, or enter the route of your terms page in Terms Page.
4. Save.

Customers now see an Affiliate tab in their account with an application form, where they can also choose their own code, and anyone without an account can apply from the public form once they've confirmed their email (Apply Without an Account, on by default). Applications wait on the Applications tab until you approve or reject them, each marked Existing customer, Matches a customer or No account yet, so you know whether approving makes an account. The tab shows how many are waiting, and a dashboard alert says so too. With applications closed, only partners you added yourself, or who were already in, see the tab. See Apply.

Check that it works

1. Open the partner's page and copy their link.
2. Open the link in a private window. The page loads again with the ?ref= part gone.
3. Place a test order, with a different email address from the partner's. An order placed by the partner themselves isn't credited. Use the offline provider and mark the order paid, or a provider in test mode.
4. Open the Commissions tab.

The order has a commission for the partner. It shows as On hold until the holding period ends, and hovering over the status gives the date it's approved on its own.

Partners in a customer group

Your partners are customers too, so in Customers they look like everyone else. Put them in a customer group and you can find them in the list, and keep a page just for them, such as one with your brand assets or news about the program.

1. Open KahunaCart → Customers, choose the Groups tab and click New group. Call it something like "Partners" and leave Discount percent empty, unless you want every partner to get that discount on what they buy. Use a new group just for partners, not one you already use for something else.
2. Open KahunaCart → Affiliates → Settings and go to the Program tab.
3. Pick the group in Customer Group and save.

Every customer with an active or paused partner is now in the group. A partner who joins later is put in it when they're approved, and taken out when they're closed or rejected. A partner with no customer account, such as a coupon-only podcast host, isn't in it until you link one.

To list your partners, open KahunaCart → Customers and filter by the group.

To keep a page for partners only, open the page in the admin, go to Security → Access and pick the group under Customer groups. You can also put this in the page's header, with your group's code:

access:
  site.customer_group.partners: true

A visitor who isn't signed in is sent to the sign-in page, and a signed-in customer who isn't a partner gets access denied. See Pages only a group can see.

A few things worth knowing:

• Use a group just for partners. A customer who has been a partner is in the group while they have a partner who's active or paused, and out of it otherwise, even if you put them in yourself. Customers who have never been partners are never added or taken out, and nobody's other groups are touched.
• It's a real membership, the same as ticking the group on the customer's record. If you untick it while they're still a partner, they're put back the next time the group is synced.
• Changing the group moves your partners. Save a different group and partner customers are taken out of the old one and put in the new one. Pick None and they're taken out. The add-on remembers which group it last filled, so this also works when the setting was changed by editing kahunacart-affiliates.yaml.
• A group that isn't there adds nobody. If you delete the group or mistype its code, nobody is put in, and partner customers still come out of the group the add-on last filled. If you rename a group's code, change the setting to the new code. Until you do, the renamed group is left alone.
• It keeps itself in line. Approving, pausing, closing and linking a partner change the group straight away. Saving the settings, and a daily job on the store's worker, bring every partner customer into line, which puts right anything an import, a restore or a customer merge changed. To do it now, run bin/plugin kahunacart-affiliates groups:sync, and add --dry-run to see what it would change first.

What it adds

Settings tabs

The settings sit on seven tabs under KahunaCart → Affiliates → Settings. Every key and its default is in the Settings reference.

Permissions

There are four permissions, and each stands alone. Someone who can pay partners can't read their tax forms unless they were given that permission too.

What it does not do

• File taxes or give tax advice. It collects the forms and totals what each partner was paid. See Tax details.
• Hold partner money. PayPal pays from your own PayPal account, store credit is a balance in your own store, and a batch paid by hand is paid by you.
• Pay through Wise automatically. It writes a file in Wise's batch format for you to upload. See Manual payouts.
• Pay on a customer's later orders. A partner earns on the orders they are credited with and on the renewals of those orders' subscriptions. A referred customer's next order earns only if it comes through the partner again.
• Pay several levels. There's one partner per order and no commission on a partner's recruits.

Related

• Tracking
• Commissions
• Payouts
• Coupons, for the discount side of a partner's code
• Store credit, gift cards and credit notes, for paying partners in credit
• Subscriptions, for recurring commissions