Affiliates & payouts

Paylera’s affiliates module attributes referred customers to an affiliate, accrues commissions on the customer’s payments, and pays them out in batches with configurable hold periods.

The model

Affiliate ── earns ──► Commission ── batched ──► Payout ── settled ──► Provider
                                                           via

Affiliate — the entity earning commission. Has a payout method (bank account, PayPal, wallet credit).
Commission — accrued for each qualifying customer payment, per a programme’s rules.
Payout batch — periodic aggregation of an affiliate’s ready-to-pay commissions, paid in one transfer.

Programmes

A programme defines the commission rule and which products it applies to:

POST /v1/affiliates/programmes
{
  "code": "saas-30",
  "rule": {
    "type": "percent",
    "rate": "30.0",
    "applies_to": { "product_codes": ["pro", "business"] },
    "duration": "first_year"
  },
  "hold_period_days": 30,
  "min_payout_amount": "50.00",
  "currency": "USD"
}

Field	Meaning
`rule.type`	`percent` or `fixed`.
`rule.rate`	Percent (0–100) or money amount.
`rule.duration`	`first_payment`, `first_year`, `lifetime`.
`hold_period_days`	Days a commission stays `pending` before it’s eligible for payout (chargeback / refund window).
`min_payout_amount`	Below this, batches are deferred to the next cycle.

Attribution

Three attribution methods, picked per programme:

Method	How it links a customer to an affiliate
`code`	Customer is created with `referral_code: "alice"` matching an affiliate’s code.
`cookie`	Hosted-checkout sets a first-party cookie at the click; resolved at customer creation.
`api`	Your application calls `POST /v1/affiliates/attribute` explicitly.

A customer can have at most one affiliate; once attributed, the link is permanent unless an operator overrides it (audited).

Commission lifecycle

accrued ──► pending ──► eligible ──► paid
                │
                └──► reversed   (on refund / chargeback)

State	Meaning
`accrued`	Created at the moment the customer’s payment succeeded.
`pending`	Within the hold period.
`eligible`	Hold period elapsed; ready for the next payout batch.
`paid`	Included in a settled payout batch.
`reversed`	The originating payment was refunded or charged back; the commission is debited.

A reversal during the hold period silently cancels the commission. After payout, a reversal creates a debit against the next batch.

Payout batches

A scheduled worker runs nightly:

Finds every affiliate with eligible commissions ≥ min_payout_amount.
Aggregates them into a payout_batch.
Initiates the transfer through the affiliate’s payout method.
Marks the batch and underlying commissions paid on success.

Manual trigger:

POST /v1/payouts/batches/run
{ "as_of": "2026-05-31T23:59:59Z", "affiliate_ids": ["aff_…"] }

Commission ledger

Every accrued commission posts to the ledger as a liability:

Affiliate cost (expense)        30.00   debit
  Affiliate payable (liability) 30.00   credit

When the payout settles:

Affiliate payable               30.00   debit
  Cash                          30.00   credit

Reversals reverse the posting. The liability balance always reconciles to the sum of pending + eligible commissions per affiliate.

Payout methods

Method	Notes
`bank`	ACH (US), SEPA (EU), Faster Payments (UK). 1–3 business days.
`paypal`	Same-day in supported countries.
`wallet_credit`	Credits the affiliate’s customer wallet. Same-instant.
`manual`	We mark the commission `paid`; you settle out-of-band. Useful for crypto or rare rails.

Webhook events

Event	When
`commission.accrued`	A qualifying payment produced a commission.
`commission.eligible`	Hold period elapsed.
`commission.reversed`	The originating payment was refunded / charged back.
`payout_batch.created`	A batch was assembled.
`payout_batch.settled`	All transfers in the batch succeeded.
`payout_batch.failed`	A transfer failed; the batch needs operator attention.

Common pitfalls

duration: lifetime on a percent rule with a high rate is a great way to lose money on a long-tail customer. Model the LTV first.
Cookie attribution is fragile. If you have an account creation flow, prefer code (let users enter the referral code at signup) or api (set it explicitly when you create the customer).
Hold period < refund window = paying for refunded sales. Set hold_period_days ≥ 30 for card-based payments.