# payout-instructions

Endpoints for creating and managing payout instructions. A payout instruction represents an intention to pay a specific amount of money to a beneficiary.It is associated with one and only one campaign. 

## Get Payout Instructions

 - [GET /v2/campaign-manager/payout-instructions](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions/get.md): Retrieves a paginated list of payout instructions, optionally filtered by campaign id, status, external id, or email. 
                A payout instruction represents an intention to pay a specific amount of money to a beneficiary and is associated with exactly one campaign.

## Create Payout Instruction

 - [POST /v2/campaign-manager/payout-instructions](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions/post.md): Creates a new payout instruction with the specified campaign and recipient details. 
                Note that creating a payout instruction does not automatically send it to the beneficiary or allocate funds; it only records the intention to pay. 
                The payout instruction must be explicitly initiated in a separate step to notify the beneficiary.

## Get Payout Instruction

 - [GET /v2/campaign-manager/payout-instructions/{id}](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D/get.md): Retrieves a single payout instruction based on provided identifier. 
                Creating a payout instruction does not automatically distribute funds to the beneficiary; it requires subsequent initiation.

## Update Payout Instruction

 - [PATCH /v2/campaign-manager/payout-instructions/{id}](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D/patch.md): Patches an existing payout instruction with the provided data.
Note: This operation might be pefrormed only for payout instructions that have not been redeemed or requested.
Note2: If the email is changed then the previous links get invalidated and the payout instruction moves back to Restored status.

## Get Payout Instruction Activity

 - [GET /v2/campaign-manager/payout-instructions/{id}/activity](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1activity/get.md): Retrieves the complete activity history for a specific payout instruction, including status changes, notifications sent, and actions performed by both administrators and beneficiaries.

## Get Payout Instruction Payout

 - [GET /v2/campaign-manager/payout-instructions/{id}/payout](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1payout/get.md): Retrieves the payout details for a specific payout instruction. 
                A payout is created when a beneficiary acts on a payout instruction and selects a specific payout method to receive their funds. 
                The payout contains additional details specific to the chosen method, such as gift card identifiers or transaction references.

## Initiate Payout Instruction

 - [POST /v2/campaign-manager/payout-instructions/{id}/:initiate](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1:initiate/post.md): Initiates the payout process for a specific payout instruction using the specified notification channel. 
                This action allocates funds from the associated campaign to this payout instruction and sends the initial notification to the beneficiary, allowing them to claim their funds.

## Cancel Payout Instruction

 - [POST /v2/campaign-manager/payout-instructions/{id}/:cancel](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1:cancel/post.md): Cancels a specific payout instruction with the provided cancellation reason. 
                This halts the payout process and prevents the beneficiary from claiming the funds. 
                If funds were already allocated, they will be returned to the campaign budget.

## Try Restore Payout Instruction

 - [POST /v2/campaign-manager/payout-instructions/{id}/:try-restore](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1:try-restore/post.md): Attempts to restore a payout instruction when a payment was requested but not successfully processed (e.g., a PayPal transfer that the beneficiary hasn't accepted). 
                This action attempts to cancel the pending external payout and return the beneficiary to a state where they can select a different payout method and process their payout again.

## Send Payout Instruction Reminder

 - [POST /v2/campaign-manager/payout-instructions/{id}/:send-reminder](https://docs.talli.ai/reference/swagger/payout-instructions/paths/~1v2~1campaign-manager~1payout-instructions~1%7Bid%7D~1:send-reminder/post.md): Sends a reminder notification to the beneficiary about their pending payout instruction. 
                This can be used when a beneficiary has not claimed their funds after the initial notification was sent.