Developers

Everything the affiliates add-on registers, in one place. It's for a developer who builds on the program, feeds it from a script or listens to what it does.

REST routes

Every route is under {api}/kahunacart/affiliates, where {api} is the API plugin's base, /api/v1 by default. Authentication, errors and paging work as described in REST API. Money is in minor units with a currency code beside it. Timestamps are unix seconds.

Reads take kahunacart.affiliates.view or kahunacart.affiliates.manage. Writes take manage. The payout routes take kahunacart.affiliates.payouts and the tax routes take kahunacart.affiliates.tax, and each is checked first.

Partners

Commissions and rates

Payouts

Tax

Creatives

The signed-in customer's routes

These are the routes the account tab uses. They're declared public to the API plugin, because a customer is never an API user. The API plugin attaches the signed-in session's customer and refuses the session as proof on a cross-site write, and every controller answers 401 to anyone who isn't a signed-in customer. Orders are shown by number and date only. The one exception is code-check, which answers anyone, because the public application form asks it too.

The add-on publishes no MCP tools and has no REST reference pages of its own yet.

Permissions

Each stands alone. None implies another. See Affiliates.

Events

Each event is fired after the change is written, and a listener that throws can't undo it. Payloads are arrays.

profile is always masked and never holds a full tax ID.

AffiliateService::changeCode() is the one way a code ever changes. It claims the new code and keeps the old one in a single transaction, then fires onKahunaCartAffiliateCodeChanged. It refuses to run inside a transaction that's already open, because the event, and the partner's email it sends, would go out for a change that might still roll back. It throws a LogicException there. Pass any write that belongs with the change as $alongside, and it runs inside the same transaction.

What the add-on listens to

Twig, shortcode and partial

CLI

See Tax details.

Jobs

The tax sweep that sends expiry emails runs inside the worker's tick about once every 23 hours.

Notifications

The owner rows and when each is sent are in The partner's side. The two commission rows register switched off (enabledByDefault: false, which needs KahunaCart 1.5.3). Each message has a dedupe key: affiliates.owner_payouts_due once per month in the store's time zone, affiliates.owner_payout_problem once per payout item and status or per batch and kind, affiliates.owner_tax_form once per form, the commission rows once per commission (a reversal once per amount taken back), and affiliates.owner_code_request once per request.

The add-on also opts two of its dashboard alerts in to being pushed (notify:): affiliates_paypal_payouts (high) and affiliates_tax_forms (normal). Core makes alert.affiliates_paypal_payouts and alert.affiliates_tax_forms rows for them. See Dashboard alerts → Pushing an alert to your phone.

Partner emails are templates in templates/emails/ named affiliate-*.html.twig and affiliate-*.txt.twig. See The partner's side.

Tables

The add-on adds its tables to KahunaCart's database through the base plugin's migrations, and a store reset empties all of them.

Export sets, merge and erasure

A store bundle carries the program in three sets, so the permission that guards each is the permission needed to take it out. See Export and restore.

A bundle never carries a partner's bank details, the full tax ID, the foreign tax ID, the date of birth or the signed PDF. The last four digits and the rest of the form do travel. A restored form is marked Needs re-entry.

A merge matches a partner by code, a commission by its dedupe_key, a referral by its order and a batch by its ref. It never deletes, and it never overwrites the columns a set leaves out.

Codes are matched by the code alone, and a code is never moved from one partner to another. A code nobody has here is added for its partner. A code the same partner already has is left as it is. A code that belongs to another partner here stays theirs, is left out of the merge and is named in the report. A partner in the bundle whose code is an old code of a partner already here is matched to that partner, and keeps this store's current code. Code requests are matched by partner, code and the time they were made. After every import each partner's current code is claimed if it isn't yet, which also covers a bundle from a store that never kept old codes.

Merging two customers moves the partner record to the survivor. Erasing a customer is refused while a paid payout is inside the retention period, and afterwards the partner row is anonymised. See Customers.

Related

• REST API
• Events
• Admin sections
• Settings reference