Commissions

A commission is the money a partner is owed for one order or one renewal. It's written when the order is paid, waits out your refund window, and shrinks when the order is refunded. This page is for the store owner who sets the rates and watches the money.

Before you begin

The add-on is installed and a partner has been credited with an order. See Tracking.
The job worker is running. It approves commissions when their holding period ends. See CLI.

How a commission is written

A sale earns when its order counts as paid, whether it was paid at checkout or later. That is decided by KahunaCart's payment statuses, so a status you add with the counts_as_paid flag works too. See Order statuses. Each order earns once. A payment reported twice changes nothing.

A commission has a status.

Status	What it means
Pending	Earned and waiting. The list shows On hold during the holding period, Needs approval when you approve each one yourself, and Disputed while the buyer disputes the payment with their bank.
Approved	Past the holding period. It's in the partner's balance and goes out in the next batch.
Paid	Paid out in a batch.
Rejected	You turned it down. It pays nothing.
Reversed	A refund or reversal took all of it back before it was paid.

The Kind is Sale, Renewal, Adjustment, or Clawback, which is the negative amount written when a paid commission is refunded.

What the commission is worked out on

The base is what the customer paid for the goods. It's worked out line by line.

Discounts are taken off. A line's own coupon discount comes off that line. An order-wide discount is spread over the lines by what is in them.
Tax is left out. Tax added on top is never counted. Tax that is inside a price is taken back out of the lines priced with tax inside.
Shipping is left out unless you switch on Pay on Shipping (commission.include_shipping). Then it earns at the order's rate.
Gift card purchases earn nothing while Nothing on Gift Cards (commission.exclude_gift_cards) is on, which it is by default. The order that spends the card earns instead.
Store credit and gift cards spent don't reduce the base. They were real money earlier.
Payment fees are left out. A surcharge for paying a certain way isn't something a partner sold.

Every line keeps its exact share, and the total is rounded half up once at the end. Three lines that earn 0.333 each are worth 1.00 together, not 0.99.

For example, an order has $100 of goods, a 10% coupon, $8 of shipping and tax on top. The base is $90.00. At 20% the commission is $18.00.

Rates

One order can have several rates, because each line looks for the most specific rate that applies to it. The first match wins.

Order	The rate
1	A product rate for this partner
2	A product rate for everyone
3	A category rate for this partner
4	A category rate for everyone
5	The partner's own rate
6	The program's default rate

A product in several categories that each have a rate takes the highest of them, measured on what each would earn on that line. A tie keeps the rate that was created first. A rate on a parent category doesn't reach a product filed only under one of its children.

A rate is a percent or a flat amount. Flat means something different at each level.

Where	A flat amount is paid
Product or category rate	Once for each unit bought
Partner's own rate, program default, renewal rate	Once for the order, shared across the lines that use it by what they cost

A flat amount is never more than what the customer paid for what it covers. Flat amounts are typed in the smallest unit of the order's currency, so 500 is 5.00. It's one number for every currency, so a store that sells in more than one currency should use percent.

Set the program default

Open KahunaCart → Affiliates → Settings and go to the Commissions tab.
Choose the Commission Type (commission.type): Percent of the order, or Flat amount per order.
Enter the Default Rate (commission.value). The default is 20.
Save.

Give one partner a different rate

Open the partner's page and find Rates.
Under Commission, choose Percent of the order or Flat amount per order.
Enter the Rate (%) or the Amount (minor units).
Click Save changes.

Leave Commission on The program's rate to use the default. A partner's own rate doesn't beat a product or category rate.

Set a product or category rate

There's no screen for these yet. They're set through the REST API with an API key that has kahunacart.affiliates.manage. A partner's own overrides are listed on their page under Product and category rates for this partner, where you can remove them.

BASH

# 30% on everything in category 12, for every partner
curl -s -X POST https://example.com/api/v1/kahunacart/affiliates/rates \
  -H "X-API-Key: grav_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"scope": "category", "scope_id": 12, "rate_type": "percent", "rate_value": "30"}'

Add "affiliate_id": 3 to make it for one partner. scope is product or category. rate_type is percent (at most 100) or flat. A product or category has one rate for each partner and one for everyone. Change a rate with PATCH on /kahunacart/affiliates/rates/{id}, remove it with DELETE, and list the rates for everyone with GET /kahunacart/affiliates/rates?affiliate_id=program.

Renewals

When a customer a partner referred pays for the next period of a subscription, the partner can earn a Renewal commission. It's worked out from the renewal order, so plan changes and pauses need nothing special. The order that started the subscription decides who earns. A partner who's no longer active, or an order the partner was taken off, earns nothing. A renewal order never also earns as a sale.

Set the rule on the Commissions tab of the settings.

Setting	What it does
Earn on Renewals (`recurring.mode`)	Nothing (`off`), Every renewal (`all`, the default), or A set number of renewals (`limited`).
Renewals That Earn (`recurring.limit`)	How many renewals pay, with the set number. `0` means none. Every renewal counts toward the number, even one that was refunded.
Renewal Rate (`recurring.rate`)	A percent for renewals. Blank pays the same rate as the first sale. A renewal rate replaces product and category rates on renewals.

A partner's page has Renewals with the same choices, and Renewal rate (%), to give one partner their own rule. See Subscriptions.

The holding period

Hold For (days) (commission.hold_days) is how long a commission waits before it can be approved. The default is 30, your refund window plus a week. A refund inside the window takes the commission back before any money has moved.

The worker approves commissions whose hold has ended, about every quarter of an hour. With Approve Each Commission (commission.require_approval) on, a commission instead waits as Needs approval until you approve it.

Approve or reject commissions

Open KahunaCart → Affiliates → Commissions.
Filter by status, kind, partner, dates or order number.
Click Approve now in a row's menu. Or tick several rows and click Approve or Reject… in the bar.

Approve now works on any pending commission, held or not. You can reject a pending commission, or an approved one that isn't in a payout batch. A paid commission can't be rejected, and a clawback can't either. Each approval is announced to other plugins. See Developers.

Refunds and clawbacks

A refund takes back exactly what the refunded items earned.

A refund that names items takes back what those items and units earned. Refund one unit of a two-unit line and half the line's commission goes.
A refund that is only an amount takes back a proportional share of what was still refundable.
A refund of shipping alone changes nothing, unless the commission is paid on shipping.
A full refund or a reversed order takes the whole commission back.
The same refund delivered twice takes back once.

What happens next depends on whether the commission has left your hands.

The commission is	A refund
Pending or approved, and in no batch	Lowers the commission. The list shows the amount refunded under it.
Paid, or in a batch that is still out	Leaves it alone and writes a negative Clawback, approved at once. It comes off the partner's next payout.

The clawback is what the partner owes back. If a partner's balance goes below zero, the batch builder leaves them out until it recovers. The reason in the preview is "Their balance is below zero after a refund, so they are skipped until it recovers." Their next commissions bring it back up. You can also write the balance off with an adjustment.

Disputes

When a buyer disputes a payment with their bank, an unpaid commission goes back to Pending with no approval date and shows as Disputed. It stays held until the dispute is settled, a refund or reversal settles it, or you let it go. To let it go, click Release the dispute in the row's menu. It returns to where it stood, or becomes approved if the holding period ended in the meantime.

When the dispute is settled, the commission follows the outcome:

Won: you kept the money, so the hold is let go, exactly as Release the dispute would, and the commission's note says the dispute was won.
Lost: the money went back to the buyer, so the commission is taken back as if the order had been fully refunded. An unpaid commission is reversed. One that was already paid becomes a clawback that comes off the partner's next payout, and you get the Commission taken back message saying the buyer won a dispute.

Stripe and PayPal report the outcome themselves. For Paddle and Mollie, or to correct an outcome, set it on the order with the select beside its Disputed badge. Setting a dispute back to open holds the commission again. A lost dispute's clawback stays, though: putting a commission back after it was taken is an adjustment.

The store learns of a dispute from the payment provider. Stripe, PayPal, Paddle and Mollie report one as soon as it is opened, and you also get the Dispute opened message on your notification channels. See Payment providers. Polar does not report disputes to the store, so a commission on a Polar order is not held automatically.

Adjustments

An adjustment is an amount you add or take off by hand, for a bonus, a correction or a write-off.

Open Commissions and click Add adjustment.
Choose the Partner.
Enter the Amount. A positive amount adds to what they're owed, and a negative one such as -5.00 takes it off.
Choose the Currency, if you sell in more than one.
Enter a Note. It's required, and the partner sees it in their account.
Click Add adjustment.

The adjustment is approved at once and joins the partner's balance.

Currencies

A commission is in the order's currency. Balances, batches and reports are kept per currency, and nothing is converted. A partner paid in two currencies has two balances and is paid in two batches.