Settings reference

Every key the add-on reads, in user/config/plugins/kahunacart-affiliates.yaml, with its default. Each has a field on KahunaCart → Affiliates → Settings, on seven tabs: Program, Tracking, Commissions, Payouts, PayPal, Tax and Notifications. Amounts are in the smallest unit of the currency, so 5000 is 50.00.

The PayPal client secrets are encrypted when the form is saved, and no screen shows them again.

The master switch

Key	Default	Field	What it does
`enabled`	`true`	Plugin status	Off, and the admin section and the migrations stand still. Partners, commissions and tax records stay in the database, and reset, export, erasure and merge still look after them.

Program

Key	Default	Field	What it does
`program.open`	`false`	Open Applications	Anyone can apply, from their account or from the public form. Off, and only partners you add yourself can earn.
`program.public_apply`	`true`	Apply Without an Account	People without an account apply from the public form at `/affiliate/apply` and confirm their email. Their account is made when you approve them. Off, and the program block's Apply button asks people to sign in first. Needs customer accounts in the store database (`account.db_identity`). See Without an account.
`program.auto_approve`	`false`	Approve Automatically	Approve every application as it comes in. Off, and you look at each one first.
`program.reject_reasons`	four reasons	Quick Reasons for Rejecting	The sentences the reject dialog offers under its message box. Clicking one puts it into the message, where you can still change it. Add, edit, remove and drag to reorder them. An empty list offers none, only the box. The four it starts with: "We couldn't find the site or channel you mentioned.", "Coupon and deal sites aren't part of the program.", "Your audience isn't a close fit for the store right now." and "We need a little more detail on how you'd share your link." See Review applications.
`program.terms_page`	empty	Terms Page	The route of the page applicants agree to, for example `/affiliate-terms`. Empty means no terms and no tick.
`program.blocked_codes`	empty	Blocked Words in Codes	Words partners may not use in a code they ask for, such as your brand or a competitor's. A word blocks any code that contains it, so `official` also blocks `theo-official`. Checked on applications and on requests for a new code, and again when you approve a request, so a word you block later still counts. A code made from an applicant's name leaves these words out, so Approve Automatically never hands out a code with your brand in it. Never applied to a code you type yourself. See Choosing a code.
`program.customer_group`	empty	Customer Group	The code of the customer group every customer with an active or paused partner is put in. Partners who leave are taken out, even if you added them yourself, so use a group just for partners. Customers who have never been partners are never touched. Empty puts nobody in a group, and saving a different group moves partner customers to it. See Partners in a customer group.

Tracking and credit

Key	Default	Field	What it does
`tracking.param`	`ref`	Link Parameter	The word in the link that carries a partner's code, as in `?ref=andy`. Only letters, digits, `_` and `-` are kept. Changing it breaks links already shared.
`tracking.window_days`	`30`	Remember a Click For (days)	How long a click still counts when the visitor buys later. At least 1.
`tracking.model`	`last`	Which Click Wins	`last` gives the credit to the last partner clicked. `first` keeps it with the first.
`tracking.coupon_priority`	`true`	Coupon Beats Click	When a click and a coupon name different partners, the coupon's partner gets the credit.
`tracking.consent_mode`	`session`	Cookie Consent	`session` remembers a visitor who hasn't agreed to marketing cookies for that visit only. `strict` remembers nothing without consent. Any other value is treated as `strict`. See Cookie consent.
`fraud.allow_self_referral`	`false`	Credit a Partner's Own Orders	Off, and an order placed by the partner or with their email address earns no commission.

Commissions

Key	Default	Field	What it does
`commission.type`	`percent`	Commission Type	`percent` of the order, or `flat` for each order. Product, category and partner rates override this.
`commission.value`	`20`	Default Rate	A percentage such as `20`. For `flat`, whole minor units of the order's currency, where `500` is 5.00.
`commission.include_shipping`	`false`	Pay on Shipping	Off, and the commission is worked out on goods after discounts, before tax and shipping.
`commission.exclude_gift_cards`	`true`	Nothing on Gift Cards	Buying a gift card earns no commission. The sale that spends it already did.
`commission.hold_days`	`30`	Hold For (days)	How long a commission waits before it can be approved. `0` means no wait.
`commission.require_approval`	`false`	Approve Each Commission	After the holding period a commission waits for you instead of approving itself.
`recurring.mode`	`all`	Earn on Renewals	`off`, `all`, or `limited`. See Renewals.
`recurring.limit`	`0`	Renewals That Earn	With `limited`, how many renewals pay. `0` means none.
`recurring.rate`	empty	Renewal Rate	A percent for renewals. Empty pays the same rate as the first sale.

Payouts

Key	Default	Field	What it does
`payouts.methods`	`store_credit`, `manual`, `paypal`	Payout Methods	What partners can choose from. Unknown names are dropped, and an empty list becomes `manual`.
`payouts.minimum`	`5000`	Minimum Payout	A partner owed less than this waits for a later batch.
`payouts.store_credit_bonus`	`0`	Store Credit Bonus (%)	Extra percent added when a partner takes store credit. `10` turns 50.00 into 55.00.

PayPal

Key	Default	Field	What it does
`paypal.use_driver_credentials`	`true`	Use the PayPal Payment Keys	Borrow the KahunaCart PayPal plugin's keys when it's installed, enabled and set to the same mode.
`paypal.mode`	`sandbox`	Mode	`sandbox` sends pretend payouts. `live` sends real money.
`paypal.sandbox_client_id`	empty	Sandbox Client ID	From a sandbox app in the PayPal developer dashboard.
`paypal.sandbox_client_secret`	empty	Sandbox Client Secret	The secret for that app. Stored encrypted.
`paypal.live_client_id`	empty	Live Client ID	From a live app.
`paypal.live_client_secret`	empty	Live Client Secret	The secret for that app. Stored encrypted.
`paypal.email_subject`	empty	Email Subject	The subject of the email PayPal sends a partner. `{store}` becomes your store's name. Empty is "You have a payout from {store}".
`paypal.note`	empty	Payout Message	The message on each payout. `{store}` works here too. Empty is a thank-you naming your store.
`paypal_connection`	none	PayPal connection	Not a setting. A panel that shows whether the keys can send payouts, with a Check now button. It saves nothing.

Tax

Key	Default	Field	What it does
`tax.collect`	`true`	Collect Tax Details	Partners can fill in a tax form. KahunaCart keeps the details and adds up what each partner was paid. It never files anything.
`tax.require_before_payout`	`us_only`	Require Before Paying	`off`, `us_only` or `all`: which partners need a form on file before they go in a batch.
`tax.nec_threshold`	empty	1099-NEC Threshold	In cents. Empty uses 600.00 for payments up to 2025 and 2,000.00 from 2026. A number replaces that for every year.
`tax.retention_years`	`7`	Keep Records For (years)	After a partner's last payout, their tax records can't be erased for this long.
`tax.documents_path`	empty	Signed Forms Folder	An absolute folder for signed tax forms. Empty is `user/data/kahunacart/affiliates-tax`.
`tax_key_status`	none	Tax ID key	Not a setting. A panel that shows whether `KAHUNACART_TAX_KEY` is set and can generate a key. It saves nothing. See Tax details.

Notifications

Key	Default	Field	What it does
`notifications.new_commission`	`false`	Email on Each Commission	Emails the partner every time they earn a commission. Off, because a busy program would fill their inbox. This is only the partner's email. Your own messages are on the Notifications screen under Store owner.
`notifications.statements`	`false`	Monthly Statements	Email a monthly statement to partners with no account to look at.
`notifications.reply_to`	empty	Reply-To Address	Where a partner's reply to an affiliate email goes, such as `[email protected]`. It covers every email to partners and the confirmation email for a public application, and no other email the store sends. Empty, or a value that isn't an email address, uses the Email plugin's `reply_to` if the site has one, and otherwise replies go to the From address.

Rate limit for the code check

The live check on every code field, as a partner types, asks a small public address whether the code is free. It's limited in KahunaCart's rate limiter with its own bucket, affiliate_code_check, so a script can't hammer it. The default is 30 checks a minute for each visitor. Over that, the hint stops and the form still checks the code when it's sent.

To change it, set security.rate_limits.affiliate_code_check in KahunaCart's settings, for example { limit: 60, window: 60 }. It isn't a key in kahunacart-affiliates.yaml, so it has no field on the Affiliates settings screen. The limit for the application form, affiliate_apply, is described under Without an account.