A payout is a batch: you select approved referrals, build the batch, and settle it. Nothing moves money on its own, and there is no setting that makes it. Even on Pro’s automated rails, a batch still goes through the same build-then-process sequence — “automated” means scheduled, not skipped.
Building a batch#
- Squad Affiliate → Payouts → New batch.
- Filter to what you intend to pay — a date range, a minimum balance, a rail.
- Review the totals per affiliate.
- Build the batch. It sits in draft.
- Settle it when you are ready.
A draft batch changes nothing: the referrals in it are still unpaid and the affiliates see no difference. Building and settling are separate steps because the moment before money leaves is the moment to check.
What “build” actually does#
Building a batch groups every unpaid referral by affiliate, sums what each is owed, and snapshots the exact referral IDs behind that sum onto the batch — one line item per affiliate. That snapshot matters: settling the batch later pays and marks paid exactly those referrals, not “whatever is unpaid at settlement time,” so a new commission that lands after you built the batch is left for the next one rather than silently swept into this one.
If you’ve configured a payout grace period — a number of days a commission must sit before it’s eligible to be paid, so a refund window can close first — the batch-building step is where that’s enforced: a referral younger than the grace period is skipped over entirely and picked up by a later batch once it clears. The grace period defaults to zero (no waiting) unless you set one.
Rails in the free plugin#
- Manual — mark as paid once you have sent it however you send it, with a CSV export of the batch.
- Store credit — pay in credit rather than cash, posted to the affiliate’s wallet ledger. See Withdrawals and the affiliate wallet.
- Bank transfer — collect the details, export the batch, pay from your bank.
None of the three free rails sends money through an API — each is either a record of a payment you made by hand, or (for store credit) a ledger entry the plugin itself posts. Affiliates choose their preferred rail in their portal and can request a withdrawal once they clear your minimum.
Rails in Pro#
PayPal Payouts, Wise and Stripe Connect settle a batch without leaving WordPress, and scheduled dispatch runs the whole thing on a cadence. Pro also generates provider-shaped export files for PayPal and Wise, and can pay in loyalty points. A rail that sends money is checked for valid configuration once, before the batch starts processing — a missing API key fails the whole run with one clear reason rather than failing every line item in it for what was never about any individual affiliate. Some providers can also refuse an entire batch in advance: Stripe, for instance, is asked whether the platform balance can even cover the batch total before a single transfer is attempted, so a shortfall produces one refusal with the real cause instead of a stack of per-item failures that all say the same unhelpful thing.
When a payment fails#
A failed line does not fail the batch. The line is marked failed with the provider’s reason, the referrals behind it stay unpaid rather than being marked paid, and the affiliate stays owed — which is the only correct behaviour, because a failed transfer is not a paid commission. A batch where every line failed is itself marked failed; a batch where some lines went through and others didn’t is marked completed, because pretending the whole run failed would hide the affiliates who actually got paid. Failed lines can be picked up again in a later batch the normal way, since the underlying referrals are still sitting unpaid.
The CSV export#
Every batch can be exported as a plain CSV — affiliate name, payout email or address for that batch’s rail, amount, method and a reference. The rail is fixed once, on the batch as a whole, when it’s created; there’s no per-line rail, so every row in the export reflects the one method the whole batch was built for.
Rail credentials live with the rail, not with the programme#
A payout rail that authenticates against a service — an API key for a gateway, a client secret — declares what it needs through its own registration rather than sharing one general “Payouts” settings card with the minimum withdrawal and the schedule. That distinction matters because those are two different kinds of setting: a minimum balance or a payout schedule is a policy about your whole programme, while an API key belongs to one specific rail and has no business being configured somewhere that reads as programme-wide. None of the three free rails need a credential at all — manual, store credit and bank transfer are all payments a person makes and records rather than ones the plugin sends through an API — so this only becomes visible once a rail that does authenticate against a service, like a Pro payment gateway, is registered.
Deciding which rail to offer#
The rails your affiliates actually see are built from the registered set — whatever SettingsService::default_payout_methods() reports, already including anything an add-on has registered on top of the free plugin’s own three. A rail that’s registered but never separately described still gets a row on the settings screen, falling back to its own slug as a label and to manual settlement, rather than silently vanishing — the plugin would rather show you an ugly, undescribed rail than hide one that’s technically available and leave you wondering why an affiliate mentioned a payment method you don’t remember offering.