The partner's side

Partners run their own side of the program from an Affiliate tab in their customer account. They apply, copy their link, watch their earnings, choose how to be paid and fill in their tax form without writing to you. This page is for the store owner who wants to know what partners see and which emails go out.

Before you begin

• The add-on is installed. See Affiliates.
• Partners need a customer account to use the tab. Someone without one can apply from the public form, and approving them makes the account. A partner you added without one gets emails but no tab. See Customer accounts.

Who sees the tab

The tab is at /account/affiliate, under your store's address.

Apply

There are two ways in, and they're the same form with the same questions:

• Your website
• Where you'll share us
• How you'll promote us
• Your code, which is optional
• How you'd like to be paid, and a PayPal email if that's PayPal
• A tick to accept the program terms, when you've set a Terms Page

Each email address can apply once. Someone who has already applied, including someone you turned down, sees where their application stands on the Affiliate tab, and the public form tells them they've already applied when they confirm.

Choosing a code

The Your code field is optional. The code goes at the end of their link, as in ?ref=yourcode, so the text under the field asks for something short that people will remember. Left empty, we make one from their name.

A moment after they stop typing, the form checks the code and says "yourcode is free." or says why not. That's only a hint, and the form checks again when it's sent. A code is turned away when someone else has it or once had it, when it has one of your Blocked Words in Codes (program.blocked_codes) in it, when the store keeps it for itself, or when it isn't made of letters, numbers and single dashes. The form comes back with every answer kept and the reason under the field. The code is never quietly changed into another one.

The live check allows 30 a minute for each visitor. Past that the hint stops, and the form still checks when it's sent. See Rate limit for the code check.

From their account

With Open Applications on, a signed-in customer sees the form on their Affiliate tab. It starts with "Applying as" and their name and email address from the account, and a Sign out link in case it isn't them. Sending it files the application against their customer straight away, with no email to confirm, because they're signed in.

Without an account

With Apply Without an Account on as well (it's on by default), anyone can apply from the public form at /affiliate/apply under your store's address, for example /shop/affiliate/apply. The Apply button on the program page goes there. Above the form, a line asks people who already have an account to sign in and apply with it, and signing in takes them to their Affiliate tab with the form filled in. Someone who's already signed in is sent straight there.

1. They fill in their name and email address as well as the questions, and send it.
2. The page says "Check your email" and we email them a link to confirm their address. The page says the same thing whatever the address is, so the form never tells anyone whether an address has an account with you.
3. The link opens a page with a Confirm my application button. Opening the link doesn't change anything, because some mail scanners open every link in a message. Pressing the button files the application, and it waits on the Applications tab like any other.
4. Nothing about an account happens until you decide. Approving makes the account: an address that already belongs to a customer gets the program added to that account, and they keep their password. Any other address becomes a new customer with no password yet, and the approval email has a link to choose one. Rejecting makes nothing, so there's never an account for someone you turned down.

The link works once, only the newest email's link works, and it expires after Set-Password Link Expires After in KahunaCart's account settings (account.invite_expiry_days). Only a scrambled copy of it is stored. Applications nobody confirms are deleted once their link expires.

The code they chose waits in the unconfirmed application. If someone else takes it before they confirm their email, confirming still works. They get a code made from their name instead, and the application in the admin says which code they asked for.

The form keeps scripts out without a captcha: a hidden field people never see, a few seconds' minimum between opening the form and sending it, and a limit of three applications an hour from one computer and to one email address. A form that trips any of these gets the same "Check your email" page and no email. To change the limit, set security.rate_limits.affiliate_apply in KahunaCart's settings, for example { limit: 5, window: 3600 }.

Switch Apply Without an Account off and the Apply button goes to the Affiliate tab, which asks people to sign in first. A store that keeps its customers as Grav user accounts instead of in the store database (account.db_identity off) has no public form at all: applying stays something a signed-in customer does.

Review applications

Applications wait on the Applications tab of KahunaCart → Affiliates. The tab shows how many are waiting, and a dashboard alert says so too. Each one says which kind it is, so you always know whether approving makes an account:

Click Approve… or Reject…, and write a message for the email if you like. Rejecting has a box for the reason and quick reasons under it: click one and its sentence goes into the box, where you can change it before you send. The quick reasons are yours to write in Quick Reasons for Rejecting on the Program tab of the settings. Without a message, the rejection email gives a short general reason. It always thanks them, asks them to reply to the email if something has changed, and says it doesn't change their account (or, for someone without one, that no account was made).

Replies go to the address your store's emails come from. If nobody reads that mailbox, set a Reply-To address in the Email plugin's settings, and partner emails use it.

With Approve Automatically on, everyone is active at once, and confirming the email is the approval for someone without an account. See Open applications.

Write the terms page

Make an ordinary page with your program terms and enter its route, such as /affiliate-terms, in Terms Page (program.terms_page). The form then links it and requires the tick. With no terms page the tick isn't shown.

Codes and requests for a new one

An active partner can ask for a different code, and you decide. The old code keeps working either way.

What the partner does

On the Overview page of the Affiliate tab they see "Your code is" and the code, with a Change code button that opens a form in place. It works with JavaScript off too. Every active partner has it, coupon-only partners included. They type a New code, which gets the same live check as the application form, and a reason under Why? (optional) if they like, then press Send.

Only one request waits at a time. While it does, the page says what they asked for and when, and that they'll be emailed once it's decided, and shows a Withdraw button. After withdrawing they can ask again. Their code doesn't change until you approve. The new code isn't held for them while they wait, so someone else could take it first.

What you do

A waiting request shows on the partner's page, above their details, and under Code requests on the Applications tab. It shows the change from the old code to the new one, with the reason, and the buttons Approve… and Reject…. The Applications tab's count and the attention list on Overview include these requests, and so does a dashboard alert, such as "3 partners asked for a new code". The alert's button is Open the request when one is waiting, which goes to that partner's page, and Open requests when several are, which goes to the Applications tab. You also get a message to you.

Click Approve… and a box asks you to confirm, with a switch for Also make a coupon for the new code. Then the partner has the new code, their old one keeps working, and they're emailed their new link. The email says their old code and coupons keep working.

Approving checks the code again, because it isn't held while the request waits. If someone has taken it since, or you've blocked a word that's in it, you're told and nothing changes. Reject the request, or change the code by hand. A partner who is closed or rejected can't be approved. Reject the request instead.

Also make a coupon for the new code makes a percent coupon with the new code in capitals, at the discount of the partner's first enabled percent coupon. It's on when they have one. Their old coupon isn't switched off or renamed. If a coupon with that code already exists, even one made a moment ago, the code still changes, the partner is still emailed, and you're told why no coupon was made.

Click Reject… and the box has an optional Message to the partner. Click Reject and they're emailed that their current code stays, with your message if you wrote one.

Change a code yourself

Open the partner's page and change Code in the Details panel. The old code keeps working here too, and the panel lists their Old codes, which all still credit the partner. Once the code is changed, the box Also make a coupon for the new code appears. The partner isn't emailed when you change a code yourself, so tell them. A code you type is never held to your blocked words. It must still be free, 3 to 32 characters, and made of letters, numbers and single dashes.

What an active partner sees

Every form works as a plain page without JavaScript. The copy buttons and the link builder do more when JavaScript runs. The tab's look comes from KahunaCart's stylesheet tokens, follows light and dark, works on a phone, and is skipped when builtin_css is off. To change the markup, copy a template from templates/partials/kahunacart-affiliates/ into your theme at the same path.

Banners and text for partners

Give partners ready-made things to paste into their own sites.

1. Open KahunaCart → Affiliates → Creatives and click Add creative.
2. Choose the Kind: Banner, Text or Link.
3. Enter a Name.
4. For a banner, click Choose image… and pick an image from the site media, and write the Alternative text. For text, write the Text. For a link, enter the Address of a page worth linking to.
5. Leave Show it to partners ticked and click Add creative.

Use the arrows to reorder. Disable hides one without deleting it. Partners copy a banner's embed code, which includes the right image address, and the text as it is. {link} in a text creative becomes the partner's own link. A link creative is turned into their referral link.

The public program page

To put a "Join our affiliate program" block on any page, with your rate, cookie window, renewals, holding period and payout terms and an Apply button, use one of these.

• The shortcode
  • Commission 30% of each order you send us, after discounts and before tax and shipping
  • Cookie window 60 days: a visitor who buys within that time of clicking your link counts
  • When it's yours Each commission waits 30 days in case the order is refunded
  • Payouts By store credit or PayPal, once you're owed $50.00 or more. Take store credit and we add 20%.

  Apply now No account needed. If you already have one, you can sign in to apply with it.
  in a page's Markdown. It needs the Shortcode Core plugin.
• {{ kahunacart_affiliate_program() }} in a theme template.
• {% include 'partials/kahunacart-affiliates/program.html.twig' %} with program set, or your own copy of that partial in your theme.

The block reads your settings, so it changes when they do. It's the same for every visitor, so it's safe on a cached page. The Apply button goes to the public form while Apply Without an Account is on, with a line saying no account is needed, and to the Affiliate tab (which asks people to sign in first) while it's off. With applications closed, the block says so and has no button.

The emails

Each email is a row on the Notifications screen, where you can switch it off or point it at your own template. See Notifications and Emails. Partner emails go through your store's mailer and show on its email log. The owner messages go to whichever channels you tick for them.

All are on, except the two commission messages for you, which start switched off, and the two partner emails marked above that also need their setting. The owner messages never include a partner's email address or any part of a tax ID, because they can end up in a chat room.

Messages to you

The messages for you are rows under Notifications → Store owner, and they go to whichever channels you ticked there, or to the ones you chose under New messages go to until you tick channels on a row yourself. The two commission messages start switched off because a busy program would send one for every sale. Switch them on from the same screen if you want to watch sales arrive, especially early on.

Email on Each Commission (notifications.new_commission) is a different switch. It only decides whether the partner is emailed.

The program has no payout day, so Affiliate payouts due is sent once a month by a daily check that stays quiet until somebody is over the minimum.

Two of the Affiliates alerts on the dashboard also reach your channels, with a row each on the same screen: PayPal Payouts not switched on (high) and Affiliate tax forms need attention (normal). You get one message when the alert starts showing and a "Cleared" message when it stops. Sending those two alerts, and starting the commission messages switched off, need KahunaCart 1.5.3 or later. On an earlier version the alerts stay on the dashboard and the commission messages start on, though with no channel ticked they go nowhere.

Partner emails are queued as jobs and read what is true when they go. An event that fires twice never mails the same thing twice, and a second payout to the same partner does mail.

Monthly statements

A partner with no customer account has nowhere to look at their numbers. Switch on Monthly Statements on the Notifications tab of the settings, and they get an email in the first week of each month with last month's commissions and payouts. Partners with nothing that month get nothing.

Related

• Tracking
• Payouts
• Tax details
• Customer accounts