Skip to content
KahunaCart

Powered by Grav CMS + Helios Theme

Tracking

Tracking is how an order ends up credited to a partner. It works by link, by coupon, or by hand. This page is for the store owner who sets up the program and answers "why wasn't this order credited?".

Before you begin

  • The add-on is installed and enabled. See Affiliates.
  • To handle cookie consent the way the Tracking tab describes, install the Consent plugin. Without it, the cookie is set for every visitor.

Every partner has a code, and their link is your store's address with ?ref= and the code on the end: https://yourstore.com/shop?ref=andy. Partners can also turn any page of your site into a referral link from their account, because the same parameter works on every page.

You can change the word ref in Link Parameter (tracking.param). Changing it breaks every link partners have already shared, so decide once.

Codes and old codes

A code is made of the letters a to z, the numbers 0 to 9 and single dashes between them, 3 to 32 characters long. Capitals are turned into small letters. A few words are kept for the store and can't be used: admin, shop, api, kahunacart, affiliate and affiliates.

A partner's code is made from their name, typed by you, or chosen by the partner when they apply or ask for a new one. See Apply and Codes and requests for a new one.

When a code changes, the old one keeps working. It doesn't matter whether you changed it or you approved the partner's request. A link printed with the old code still credits the same partner and the click is still counted. Nobody else can ever take an old code, so a link can't end up crediting someone new. A partner can take their own old code back later.

The database keeps this straight. Every code a partner has had, the current one too, is one row in kahunacart_affiliate_codes, and a unique index decides who has a code. If two people ask for the same code in the same moment, only one gets it. This covers applications, requests, your own edits and store imports alike. Erasing a partner keeps their codes, so they stay out of reach.

A code made for an applicant who didn't choose one leaves out your Blocked Words in Codes (program.blocked_codes), so Approve Automatically can't hand out a code with your brand in it. A code you make for a partner yourself is never held to that list.

A partner's coupon is separate from their code. Changing the code doesn't rename or switch off the coupon. See Partner coupons.

  1. The store checks the code. An old code counts as the partner's own. If it belongs to an active partner who is tracked by link, the visitor is remembered as theirs (see The cookie).
  2. The partner's click counter for today goes up by one.
  3. The visitor is sent to the same address without the ?ref= part. Other parameters such as utm_source stay.

The code comes off the address whether it was good or not, so links with codes in them don't end up bookmarked or indexed. Nobody is told that a code was wrong.

Visitor or link What happens
Code is unknown The ?ref= part comes off. Nothing is remembered.
Partner is paused, closed or rejected The same.
Partner is Coupon only The same. Their coupon link is what they share.
Visitor is a bot The same. Bots are told apart the way your store's reports tell them apart.
Visitor already holds today's click for this partner Nothing changes and the click isn't counted twice.
Visitor clicks the same partner again on a later day The time window starts again and the click is counted.

Clicks are kept as a count per partner per day. The store keeps no IP address, no browser details and no row per click.

A visit on a valid link sets a first-party cookie named kc_ref. It holds the partner's number and the time of the click, signed so it can't be edited, and nothing about the visitor. It lasts as long as the program's window.

Remember a Click For (days) (tracking.window_days) sets that window. The default is 30. A click older than the window is ignored when the order is placed.

First click or last click

Which Click Wins (tracking.model) decides what happens when a visitor clicks two partners' links.

Setting A second partner's link
The last click (last, the default) Replaces the first. The partner who sent them last gets the credit.
The first click (first) Is ignored and isn't counted. The first partner keeps the credit until the window runs out.

When the order is placed

At every checkout attempt the store writes the visitor's partner onto the order. If the visitor tries again after another click, the last click before paying wins. Nothing is owed yet. The credit only counts once the order is paid.

Orders placed by an AI shopping agent aren't stamped with a link, because the agent has no cookie. A partner's coupon still credits them.

The kc_ref cookie is declared to the Consent plugin as a marketing cookie, and the consent banner lists it as "Affiliate referral". What happens when a visitor hasn't agreed to marketing cookies depends on Cookie Consent (tracking.consent_mode).

Setting A visitor who hasn't agreed to marketing cookies
Session (session, the default) No cookie is set. The partner is remembered for that one visit in the session your store already keeps, so nothing new is put on the visitor's device. An order placed in that visit is credited.
Strict (strict) No claim is kept at all, so these visitors can only be credited by a partner's coupon. The click is still counted on the daily counter, which stores nothing about the visitor.

With either setting:

  • A visitor who agrees later has their remembered partner moved into the cookie, with the original click time.
  • A visitor who withdraws consent loses the cookie on their next page view, and the store stops reading it.
  • With no Consent plugin installed, the cookie is set for everyone.

Note

Strict is the cautious choice for stores that sell in the EU. KahunaCart can't tell you what your law requires, so ask your adviser if you're unsure.

Partner coupons

A partner's coupon is an ordinary coupon from Coupons. The add-on only records whose it is, and every rule about the discount stays with the coupon. A coupon credits its partner whether or not the buyer ever clicked a link. It also works for orders from the API, from AI agents and from the admin, which never carry a cookie.

Give a partner a coupon

  1. Open the partner's page and find Coupons.
  2. Click Add a coupon.
  3. Choose Make a new one and enter the Discount (%), or choose Use an existing coupon and search for its code.
  4. Click Add coupon.

A new coupon is a percent-off code. It's named after the partner's code in capitals, for example ANDY, unless you type a different Code. A code that already exists is refused, so the partner isn't handed one that quietly changed. Open the coupon in Coupons afterwards to add limits, an expiry or a scope. One coupon can belong to one partner.

Take off this partner in a coupon's menu stops it earning. The coupon keeps working at the till.

KahunaCart can apply a coupon from a link, as in https://yourstore.com/shop?coupon=ANDY. The partner's page and account show that link next to the code. It needs coupon links to be on in your store, which they are by default. See coupons.link.enabled in Configuration. A Coupon only partner shares this link instead of a referral link, and no cookie is involved.

Coupons against clicks

When a visitor came through one partner's link and pays with a different partner's coupon, Coupon Beats Click (tracking.coupon_priority) decides. On, which is the default, the coupon's partner gets the credit. Typing a code is a more deliberate act than a click three weeks ago. Off, and the link's partner keeps it. When the link and the coupon name the same partner, the order shows as credited by coupon.

Who isn't credited

An order can have a referral and still earn nothing. The order panel says why.

  • The buyer is the partner. The order's customer is the partner's own account, or the order's email matches the partner's email, in any capitals. The panel says "The buyer is the partner, so it earns nothing." To allow it, switch on Credit a Partner's Own Orders (fraud.allow_self_referral).
  • The partner isn't active when the order is paid. A paused, closed, rejected or still-applied partner earns nothing, even if the click was made while they were active.
  • There's nothing to pay a commission on. A free order, or a 100% coupon, earns nothing but keeps its referral. A free subscription start keeps its referral so its paid renewals can earn.

Credit, change or take off a partner by hand

A customer says they bought after hearing about you on a podcast but forgot the code. Set the partner yourself.

  1. Open the order and find the Affiliate panel.
  2. Click Credit to a partner…, or Change partner… if there's one already.
  3. Choose the Partner and click Credit.

To remove one, click Take off… and confirm. You need kahunacart.affiliates.manage. Each change is written to the order's history under your name.

What happens to a commission depends on where it stands.

The order's commission is Change or take off
Not paid out yet and in no batch It's reversed and moved. The new partner gets a fresh commission worked out from the order.
Already paid, or in a batch that's still out It stays with the old partner, and a negative Clawback nets it off their next payout. The new partner gets a fresh commission.
Not written yet because the order wasn't paid The new partner earns when it's paid.

Take off writes no new commission. Renewal commissions a partner has already earned stay with them. Later renewals follow the order's current partner.

A choice you make by hand is final. Link tracking and coupons never overwrite it, and taking a partner off holds even if a partner's coupon is still on the order.

Which credit wins

When more than one thing could credit an order, the store decides at payment in this order.

  1. Your choice by hand, including taking the partner off.
  2. A partner's coupon, when Coupon Beats Click is on.
  3. The link click stamped on the order.

See the clicks

  • Overview shows clicks over the last 30 days for the whole program.
  • Affiliates has a Clicks column for the last 30 days.
  • A partner's page has a chart of their clicks.