Autonomous ventilation

Work in progress, under review. This page is not validated yet and may contain inaccuracies. Track and record its status in the documentation review tracker. This banner is removed once the page is validated.

By default, Paylead manages the Consumer pool and runs the payout. This page covers the autonomous model, where the Program Manager distributes Cashbacks to its Consumers itself.

Autonomous ventilation is not the default. Use it only if your Program operates its own Consumer payouts. Coordinate the setup with your Paylead representative.

In the autonomous model, Paylead computes who owes what to whom; the Program Manager executes the payout to its Consumers. Two approaches exist. The Program Manager picks one when the Program is created, then operates it consistently for every Cashback.

How it works

The first three steps are identical. The split happens at payout: either the Program Manager pays the Consumer up front and Paylead reimburses later, or the Program Manager waits for Paylead’s settlement schedule before distributing.

Choosing an approach

Consumer-centric
Standard

When to use: Programs that compete on Consumer experience and where the Program Manager can pre-fund Cashbacks.How it works

Paylead validates the Reward and sets its technical status to VALIDATED.
Paylead emits the REWARD_VALIDATED Webhook.
The Program Manager immediately credits the Consumer’s bank account with the Cashback amount.
Paylead reimburses the Program Manager at the next monthly settlement.

Trade-offs

Pros	Cons
Cashback lands in the Consumer’s account within hours of validation.	The Program Manager fronts the cash for up to 30 days.
Strong NPS and retention signal.	Requires reconciliation between advances paid and the monthly Paylead settlement.
No CSV download step.	The Program Manager bears the risk on any post-advance refund (Paylead does not claw back Cashbacks).

When to use: Programs that prefer to avoid cash advances or do not yet have automated banking flows wired to Paylead Webhooks.How it works: follows the settlement schedule below.

Paylead identifies validated commissions at each month end and emits a ventilation file the following month end.
Two months after the file, Paylead pays the Program Manager, setting affected Rewards to PAID_OUT.
Paylead emits the PAYOUT_SUCCESS Webhook.
The Program Manager pulls the ventilation file via the Paylead API and credits each Consumer.

Trade-offs

Pros	Cons
No cash advance. The Program Manager only distributes funds it has received.	The Consumer waits until M+3 to M+4 after validation (see schedule).
One batch reconciliation per month.	Lower NPS impact; the Cashback feels slower.
Predictable cash flow.	Requires CSV or JSON ingestion in the Program Manager’s accounting stack.

Retrieving the ventilation file

When the payout is successfully processed by Paylead’s PSP, Paylead emits a PAYOUT_SUCCESS Webhook and makes the matching ventilation file available. All affected Rewards move from PAID_IN to PAID_OUT.

Configure the Webhook

In Shift, set the Webhook URL under My Account → Developers → Hooks → Payout success. The payload Paylead POSTs to that URL carries the payout_id as its resource_id. Pass it to the ventilation endpoint below.

Code examples coming soon. The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.

Retrieve the file

Call GET /programs/me/ventilation?payout_id=<payout_id>.

This endpoint must be called with your Program’s access token. See Authentication.

The response carries a signed download_url for the CSV file.

CSV schema

The CSV contains one row per Reward included in the payout:

Column	Description
`reward`	The Reward identifier.
`consumer_id`	The Program-scoped Consumer identifier.
`offer_reference`	The Offer that triggered the Reward.
`reward_rate`	The Cashback rate applied.
`amount`	The Reward amount.
`bankwire_ref`	The bank wire reference for the payout.
`payment_date`	When the payout was executed.

The Program Manager aggregates rows by consumer_id before issuing bank transfers.

The file can also be downloaded directly from Shift: My account → Ventilation.

Settlement schedule

Payout in the Standard approach follows a fixed monthly cadence:

End of each month: Paylead identifies the commissions generated and validated by the Program’s Consumers during that month.
End of the following month: Paylead emits a ventilation file detailing the validated commission per Consumer (consumer_id and total amount).
End of the month two months after that: Paylead pays out the full set of commissions. The payment may be split in two: one for the Program Manager’s own commission, one for the commissions attached to a Reward.

Net delay. Once a Reward is VALIDATED, you wait until that month end to be counted, the next month end to appear in the ventilation file, then two more months to receive the funds: roughly M+3 to M+4 depending on when validation occurred.

Changing the Ventilation approach on a live Program does not retroactively re-allocate Rewards already paid out. Coordinate the switch with your Paylead representative and pick a clean month boundary.

Recommendations

To absorb the M+3/M+4 delay without hurting the Consumer experience:

Advance funds on validation. Use the Consumer-centric approach: credit the Cashback as soon as it reaches VALIDATED, then reconcile against Paylead’s later payment.
Use a pool with a minimum payout threshold. Holding Cashback in a pool and paying out only past a small threshold (€5 is enough) reduces the working-capital need and maximizes marketing value: the Consumer watches their pool grow and is paid in meaningful increments.

No clawback

As soon as a Cashback reaches VALIDATED, it can no longer be cancelled or modified. Refunds, disputes, and cancellations must happen before validation. Once validated (and a fortiori once included in a Ventilation file) the amount is definitively owed to the Consumer.

Edge cases

The Consumer leaves the Program before payout

A Consumer may unsubscribe between Reward validation and ventilation. Paylead drops them from the ventilation file because their account link is no longer authoritative.The Program Manager handles this case in one of two ways:

Honor the Cashback from internal records (recommended for Consumer-centric Programs that already advanced the funds).
Document in the Program’s terms and conditions that unsubscribing forfeits the Consumer’s pending pool.

The transaction is refunded before the Reward is validated

Paylead reconciles the refund against the original transaction and cancels the Reward during the refund window, before it reaches VALIDATED. Once validated, the Cashback is locked, even if a later refund hits the bank account. Programs running the Consumer-centric approach may have already advanced the Cashback. Recovering it on a pre-validation refund is the Program Manager’s responsibility, based on Program policy.

Multiple Rewards on one Consumer in the same payout

The ventilation file lists one row per Reward, grouped together by consumer_id. The Program Manager aggregates rows before issuing a single bank transfer per Consumer to reduce transfer fees.

Currency

All Ventilation files are denominated in EUR. Paylead does not support multi-currency Programs.

What’s next

Ventilation (default)

The default model, where Paylead manages the Consumer pool and runs the payout.

Webhooks

Subscribe to REWARD_VALIDATED and PAYOUT_SUCCESS to drive autonomous payouts in real time.

​How it works

​Choosing an approach

​Retrieving the ventilation file

​Configure the Webhook

​Retrieve the file

​CSV schema

​Settlement schedule

​Recommendations

​No clawback

​Edge cases

​What’s next

Ventilation (default)

Webhooks

How it works

Choosing an approach

Retrieving the ventilation file

Configure the Webhook

Retrieve the file

CSV schema

Settlement schedule

Recommendations

No clawback

Edge cases

What’s next