Payouts
A payout batch pays every partner who is owed enough, in one run. You choose how, preview who is in it, and run it. This page is for the person who pays partners, who needs the kahunacart.affiliates.payouts permission.
Before you begin
- Some commissions are Approved. See Commissions.
- Each partner has a payout method, or you'll pay everyone one way. A partner chooses theirs in their account. You can also set it on their page under How they're paid.
- For PayPal, the PayPal keys and Payouts switched on at PayPal. See PayPal Payouts.
The methods
| Method | How it's paid | When the partner has it | Fees |
|---|---|---|---|
| Store credit | Added to the partner's store credit through the ledger. Needs a customer account. | At once | None. |
| Manual (Paid by hand in the settings) | You pay outside the store and mark it paid. Files for your bank, PayPal or Wise are made for you. | When you pay them | Whatever you pay. |
| PayPal | PayPal Payouts sends the money from your PayPal account. | When PayPal sends it, checked every ten minutes | PayPal charges you a fee for each payout. |
Payout Methods (payouts.methods) on the Payouts tab of the settings decides which of these partners can pick. All three are on by default. A partner who picked a method you've since switched off is left out of batches until they choose another.
A partner sees Bank transfer where the admin says Manual.
Pay partners at the end of the month
- Open KahunaCart → Affiliates → Payouts and click New batch.
- Under Pay by, choose Each partner's choice, Store credit, Manual or PayPal.
- Choose the Currency, if you sell in more than one.
- Click Preview.
- Look at the tables. Each partner is in or left out with a reason. Untick anyone you'd rather skip this time.
- Click Create the batch. With Each partner's choice you get one batch per method.
- Open the batch and click Run the batch, then confirm.
The batch is a draft until step 7. A draft pays nobody. You can throw it away with Delete draft… and every commission goes back to the partners' balances. After it has run, a batch is history.
Creating a batch works every amount out again from the commissions it locks, so a refund between your preview and your click is counted. Two people building batches at once can never pay the same commission twice.
Who is left out
The preview says why next to each name.
| Reason | What to do |
|---|---|
| Not active | Resume or approve the partner. |
| Nothing is owed, or below the minimum | Wait for a later batch. Minimum Payout (payouts.minimum) is 5000 by default, which is 50.00. It's in the smallest unit of the currency and the same number for every currency. |
| Their balance is below zero after a refund | It recovers with their next commissions. See Refunds and clawbacks. |
| Has not chosen how to be paid | Set their method, or ask them to. |
| The method is switched off in the settings | Switch it on under Payout Methods. |
| No PayPal email address on file | Add it on their page. |
| Store credit needs a customer account | Link an account, or pay another way. |
| PayPal can't send the currency, or only sends whole amounts in it | Pay another way. |
| A tax form is missing, expired or needs filling in again | See Tax details. |
Store credit
Each partner's payout is posted to their store credit account in the batch currency. They can spend it at checkout straight away. It shows in their credit history as Affiliate commission. See Store credit, gift cards and credit notes. Items are paid as soon as the batch runs.
Store Credit Bonus (%) (payouts.store_credit_bonus) adds a percentage when a partner takes credit, because credit costs you no fees. With 10, a payout of 50.00 becomes 55.00. The preview shows the bonus beside the balance. The partner sees "includes a bonus".
If a run is cut off partway, the batch stays In progress and shows Resume. Click it, or click Run the batch again. It pays only the partners still waiting. Nobody is credited twice.
Manual payouts and the files
A partner can give bank details in their account, or you can add them on their page. They're stored encrypted and shown masked. Click Show on a partner's page to read them. Each time is recorded.
To pay a batch by hand:
- Create the batch with Pay by set to Manual, and click Run the batch. It moves to In progress.
- Click the file you need on the batch page.
- Pay the partners outside the store.
- Click Mark all paid…, or Mark paid… on each item. A reference such as a transfer number is optional.
An item whose payment bounced is Mark not paid…. Its commissions go back to the partner's balance for the next batch.
| File | What it's for |
|---|---|
| Download CSV | A plain file for a bank or a spreadsheet: name, email, amount, currency, the partner's payout details and a reference such as KC-AFF-12. |
| PayPal bulk file | PayPal's Payouts upload format, with no header row. |
| Wise bulk file | Wise's batch payment template. Wise emails each partner for their bank details, so you never hold them. |
The PayPal and Wise files are only on manual batches, and they hold only the items still waiting, so a second download can't pay anyone twice. The plain file also holds items already paid. Partner names are made safe for spreadsheets.
PayPal Payouts
PayPal Payouts sends the money straight from your PayPal account. The add-on has its own small PayPal client, so it works on a store that doesn't take PayPal at checkout.
Switch on Payouts at PayPal
PayPal has to enable Payouts for your business account before a batch can be sent. If Payouts is off, the PayPal tab says so and links PayPal's page to ask for it.
Add the keys
- Open KahunaCart → Affiliates → Settings and go to the PayPal tab.
- Choose the Mode. It's Sandbox until you change it. Live sends real money.
- If the KahunaCart PayPal plugin is installed, enabled and in the same mode, Use the PayPal Payment Keys (
paypal.use_driver_credentials) borrows its keys. Otherwise, enter the Client ID and Client Secret for the mode from an app in the PayPal developer dashboard. Secrets are stored encrypted. - Optionally change the Email Subject and Payout Message.
{store}becomes your store's name. - Save.
Saving checks the connection. The PayPal connection field on the tab shows Ready to pay partners or says what's wrong, and Check now runs the check again. The same result shows at the top of Payouts, where the button is Check again. Run the batch stays off for a PayPal draft until the check passes. A dashboard alert appears when PayPal Payouts isn't switched on.
What happens when you run a PayPal batch
PayPal gets one request for the whole batch. The request is saved first, and every id in it is built from the batch's own random reference. Two stores sharing one PayPal account never use the same id, and PayPal refuses a repeat id, so sending the same request again can't pay twice.
PayPal can send AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RUB, SEK, SGD, THB, TWD and USD. HUF, JPY and TWD take whole amounts only.
The store then asks PayPal about open batches every ten minutes, so there are no webhooks to set up. Ask PayPal now checks straight away.
| PayPal says | The item becomes | What happens |
|---|---|---|
| Success | Paid | The commissions are paid. The partner is told. |
| Unclaimed | Unclaimed | The partner has no PayPal account yet. Their commissions stay locked because they can still claim it. They're emailed, and a reminder with a subject starting "Reminder:" goes a week before PayPal returns it after 30 days. |
| Returned | Returned | PayPal's reason is kept. The commissions go back to the balance. The partner is told. |
| Failed, blocked, refunded or reversed | Failed | The same. |
| Pending or on hold | Unchanged | Checked again in ten minutes. |
When every item has an answer, the batch is Completed, Partly paid or Failed. A batch with unclaimed items is checked for up to 30 days.
When the outcome is unknown
Sometimes PayPal never answers. The batch stays In progress and the store sends the saved request again, exactly as it was, for up to 72 hours. PayPal's memory of an id lasts 30 days, so a resend can't land after PayPal has forgotten the first.
After 72 hours, or if PayPal shows a batch that doesn't match what the store sent, the batch says "outcome unknown, check PayPal". Every commission stays claimed, because the money might be out.
- Find the batch in your PayPal dashboard and see what happened to each payment.
- In the batch, click Mark paid… or Mark not paid… on each item.
A commission only goes back to a balance when the store knows the payment didn't happen.
Retry failed items
When items in a batch Failed or Returned, the batch shows Retry the failed payout or Retry N failed. It makes a new draft for those partners with the same method and currency, from their balances as they are now. Nothing is sent again under the old ids. The old item shows Retried with a link to the new batch.
If nobody can be paid yet, you're told why. A partner with a missing PayPal address, for instance, needs one added first.
The emails
A partner is emailed when a payout is sent, fails, or waits unclaimed. You get a message through your notification channels when partners have reached the payout minimum, when one payout fails, comes back or waits unclaimed (or a PayPal batch is stuck or its outcome is unknown), and when a batch finishes, with failures called out. See The partner's side.