> For the complete documentation index, see [llms.txt](https://docs-vnext.kiflo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-vnext.kiflo.com/partner-incentives/payouts/how-to-automate-payouts-via-api.md). # How to automate payouts via API This article explains how to automate payouts using Kiflo API. Please read first this article to understand [What is the payout process?](/partner-incentives/payouts/payout-process.md) {% hint style="info" %} **Target audience** This article is written for developers. {% endhint %} Automating payouts is a four steps process: 1. [**Create payouts**](#create-payouts): Create payouts at regular intervals (ex: every month, or every quarter) for all partners with pending rewards 2. [**Validate payouts**](#validate-payouts): Change statuses from Pending to Validate to make payouts visible to partners. Optionally ask them to also validate payouts and upload invoices. 3. [**Send payments**](#send-payments): Export payouts from Kiflo to send payments manually or via your bank API. 4. [**Mark payouts as paid**](#mark-payouts-as-paid): Change statuses from Accepted to Paid to let partners know they will receive the funds soon. ## Create payouts Endpoint: The first step is to create payouts for all partners with pending rewards. Payouts are created with the status *Draft* by default and are **not visible to partners**. ### Frequency You must define the frequency at which you need to create payouts. It can be every month, every quarter, or even every time a reward is generated. ### Parameters When creating payouts you must set the following parameters: | Parameter | Description | Optional | Example | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------------------- | | partnerIds | List of partner IDs for whom you want to create payouts. Don't set this parameter if you want to create payouts for ALL partners. In any case, payouts are not created for partners without pending rewards. | Yes | \[42] | | currency | The currency of rewards that must be included in payouts. If set, only rewards in that currency are included in payouts. Don't set it to create payouts for all currencies. | Yes | EUR | | rewardType | The type of rewards that must be included in payouts. If set, only rewards with this type are included in payouts. Don't set it to create payouts for all types of rewards. | Yes | Cash | | rewardStatus | The status of rewards that must be included in payouts. If set, only rewards with this status are included in payouts. Don't set it to create payouts for all *Pending* and *Accepted* rewards. In any case, rewards already *Paid* or *Rejected* are NOT included in payouts. | Yes | Accepted | | fromDate | Only include rewards generated after this date (ISO 8601). | Yes | 2024-01-01T00:00:00Z | | toDate | Only include rewards generated before this date (ISO 8601) | Yes | 2024-02-01T00:00:00Z | | threshold | The amount of pending rewards per partner that must be reached to generate the payout for that partner. | Yes | 1500 | | properties | Additional list of JSON property to be included in ALL payouts. | Yes | | {% hint style="info" %} **Important notice** The upper parameters are used to select rewards to be included in payouts. In case there is no reward matching these criteria for one partner, no payout is created for this partner. {% endhint %} ### Examples Create payouts for all partners for January 2024 (timezone: UTC+1): ``` { "fromDate": "2023-12-31T23:00:00Z", "toDate": "2024-01-31T23:00:00Z" } ``` Create payouts for a specific partner for all rewards waiting to be paid: ``` { "partnerIds": [42] } ``` Create payouts for Q1 2024 for all partners who must be paid in Euro (timezone: UTC+1): ``` { "currency": "EUR", "fromDate": "2023-12-31T23:00:00Z", "toDate": "2024-03-31T23:00:00Z" } ``` ## Validate payouts Endpoint: Draft payouts must be validated to be visible to partners. Optionally you can ask partners to upload invoices or review rewards including in payouts. Payouts must be validated one by one. ### Parameters When creating payouts you must set the following parameters: | Parameter | Description | Optional | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------- | | shouldValidateRewards | Determine whether the partner must validate rewards in the new payout. If *True*, the payout status goes from *Draft* to *Pending*. | Yes | | shouldAttachInvoice | Determine whether the partner must validate rewards in the new payout. If *True*, the payout status goes from *Draft* to *Pending*. | Yes | If both parameters are *False*, the payout status goes from *Draft* to *Ready* and is ready to be paid. ### Examples Validate one payout and ask the partner to upload an invoice: ``` { "shouldValidateRewards": true, "shouldAttachInvoice": true } ``` Validate one payout, without requiring any additional actions from the partner: ``` { "shouldValidateRewards": false, "shouldAttachInvoice": false } ``` ## Send payments All payouts with the status *Ready* are ready to be paid. They are *Ready* when either: * They have been validated in the previous step without asking for additional actions from partners; OR * Partners have accepted the payouts after uploading the invoices or reviewing the rewards You cannot send payments from Kiflo directly. You must export payouts using the list payouts endpoint: And filter returned payouts by status, date, or partner, depending on which payouts you want to pay. Then, connect to your bank or payment platform and trigger payments according to their instructions. ## Mark payouts as paid Endpoint: When payments are sent, payouts must be marked as paid. Manually change their status from *Ready* to *Paid* and partners are notified using the referenced endpoint. Payouts must be marked as paid one by one. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs-vnext.kiflo.com/partner-incentives/payouts/how-to-automate-payouts-via-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.