> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manifestfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts

# Overview

The Payout object represents a payment from you to one of your activated connections.

<Note>
  **Permission Required**<br /><br />
  Creating payouts requires the `payment.credit` permission from the selected account connection. This permission will be granted automatically if a legacy payout method is specified when creating the account connection.
</Note>

***

# Payout Lifecycle

Each payout follows a lifecycle with events and timing depend on the `type` of the account connection receiving the payout. Payouts to inactive account connections are considered `unclaimed` and allow the recipient 30 days to activate their account connection and receive their payout. This diagram shows lifecycle events for the different types of payouts:

<Frame caption="Payout Lifecycle.">
  <img src="https://mintcdn.com/manifestfinancial/Zmfsb2exisBO0rx8/images/payout-lifecycle.png?fit=max&auto=format&n=Zmfsb2exisBO0rx8&q=85&s=6158d170bace5598bdb133ff70405f88" alt="Payout Lifecycle" width="2944" height="1582" data-path="images/payout-lifecycle.png" />
</Frame>

***

# Methods

<Tabs>
  <Tab title="Create">
    <Card icon="square-plus" iconType="solid" color="#86B74B">
      **`POST`  /payout**<br />
      Make payouts to your account connections. Include an [**idempotency key**](/reference/idempotency) header to make the request idempotent.
    </Card>

    ## Body Parameters

    <ParamField body="account_connection" type="string" required="true">
      ID of Account Connection to pay
    </ParamField>

    <ParamField body="amount_in_cents" type="number" required="true">
      Amount in cents, e.g. \$1.00 would be the number 100.
    </ParamField>

    <ParamField body="description" type="string">
      Description of payout. (Visible to creators.) Default value: `Payment from {enterprise_name}`
    </ParamField>

    <ParamField body="date" type="string">
      Schedule a future payout by setting its date with an [ISO 8601 date/time string](https://www.w3.org/TR/NOTE-datetime). If omitted, payout will be queued for processing immediately.
    </ParamField>

    <ParamField body="user_data" type="object">
      User defined data that can be attached to the object. See the [User Data](/reference/user-data)
      page for details.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Request theme={null}
      // POST /payout
      {
          "account_connection": "acon_XXXXX",
          "amount_in_cents": 10000,
          "description": "January Payout"
      }
      ```

      ```json Response theme={null}
      {
          "id": "pay_AAAAA",
          "type": "direct",
          "status": "pending",
          "account_connection": "acon_XXXXX",
          "amount_in_cents": 10000,
          "description": "January Payout",
          "date": "2024-11-12T20:22:49.075Z",
          "destination": "Manifest Account - Paul McCartney",
          "fee_in_cents": 10,
          "userdata": {},
          "created_at": "2024-11-12T20:22:49.075Z",
          "updated_at": "2024-11-12T20:22:49.075Z"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Create Batch">
    <Card icon="square-plus" iconType="solid" color="#86B74B">
      **`POST`  /payout/batch**<br />
      Create many payouts at once. This method is more performant than individually creating payouts, and should be used in high-volume situations.<br /><br />**This method is strict.** If any payout object fails validation, no payouts will be created. If addition to the top-level error `message` in the error response, the `details` key will contain an array of any problematic request objects and their individual errors. See example `Bad Request` error response below.<br /><br />Include an [**idempotency key**](/reference/idempotency) header to make the request idempotent.
    </Card>

    ## Body Parameters

    <ParamField body="payouts" type="object[]" required="true">
      Array of payout objects. See Payout object specification from Create Payout method.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Request theme={null}
      // POST /payout/batch
      {
          "payouts": [
              {
                  "account_connection": "acon_XXXXX",
                  "amount_in_cents": 10000,
                  "description": "January Payout"
              },
              {
                  "account_connection": "acon_YYYYY",
                  "amount_in_cents": 10000,
                  "description": "January Payout"
              }
          ]
      }
      ```

      ```json Response theme={null}
      {
          "payouts": [
              {
                  "id": "pay_AAAAA",
                  "type": "direct",
                  "status": "pending",
                  "account_connection": "acon_XXXXX",
                  "amount_in_cents": 10000,
                  "description": "January Payout",
                  "date": "2024-01-15T20:22:49.075Z",
                  "destination": "Manifest Account - Paul McCartney",
                  "fee_in_cents": 10,
                  "userdata": {},
                  "created_at": "2024-01-15T20:22:49.075Z",
                  "updated_at": "2024-01-15T20:22:49.075Z"
              }, {
                  "id": "pay_BBBBB",
                  "type": "direct",
                  "status": "pending",
                  "account_connection": "acon_YYYYY",
                  "amount_in_cents": 10000,
                  "description": "January Payout",
                  "date": "2024-01-15T20:22:49.075Z",
                  "destination": "Manifest Account - Ringo Starr",
                  "fee_in_cents": 10,
                  "userdata": {},
                  "created_at": "2024-01-15T20:22:49.075Z",
                  "updated_at": "2024-01-15T20:22:49.075Z"
              }
          ]
      }
      ```

      ```json Bad Request theme={null}
      {
          "message": "Errors occurred while creating payouts. No payouts were created. See details.",
          "details": [
              {
                  "message": "You have not requested the 'payment.credit' permission from this account connection.",
                  "request": {
                      "account_connection": "acon_XXXXX",
                      "amount_in_cents": 10000,
                      "description": "January Payout",
                  }
              },
              {
                  "message": "Deleted account connections cannot receive payouts.",
                  "request": {
                      "account_connection": "acon_YYYYY",
                      "amount_in_cents": 10000,
                      "description": "January Payout",
                  }
              }
          ]
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Get">
    <Card icon="square-arrow-right" iconType="solid" color="#425BE0">
      **`GET`  /payout/:id**<br />
      Get details of one of your payments.
    </Card>

    ## Path Parameters

    <ParamField path="id" type="string" required="true">
      The ID of the payout to retrieve.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      {
          "id": "pay_AAAAA",
          "type": "direct",
          "status": "pending",
          "account_connection": "acon_XXXXX",
          "amount_in_cents": 10000,
          "description": "January Payout",
          "date": "2024-11-12T20:22:49.075Z",
          "destination": "Manifest Account - Paul McCartney",
          "fee_in_cents": 10,
          "userdata": {},
          "created_at": "2024-11-12T20:22:49.075Z",
          "updated_at": "2024-11-12T20:22:49.075Z"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Update">
    <Card icon="square-pen" iconType="solid" color="#F1E067">
      **`PUT`  /payout/:id**<br />
      Update data associated with one of your enterprise's payouts. Only certain fields can be updated. See below.
    </Card>

    ## Path Parameters

    <ParamField path="id" type="string" required="true">
      The ID of the payout to update.
    </ParamField>

    ## Body Parameters

    <ParamField body="status" type="string">
      Pass the string `canceled` to cancel the payout. This is only effective if the payout is in ready status.
    </ParamField>

    <ParamField body="description" type="string">
      Description of payout. (Visible to creators.) Default value: `Payment from {enterprise_name}`
    </ParamField>

    <ParamField body="date" type="string">
      Reschedule a future payout by setting its date with an [ISO 8601 date/time string](https://www.w3.org/TR/NOTE-datetime).
    </ParamField>

    <ParamField body="user_data" type="object">
      User defined data that can be attached to the object. See the [User Data](/reference/user-data) page for details.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Request theme={null}
      // PUT /payout/pay_AAAAA
      {
          "description": "Royalties for Hey Jude"
      }
      ```

      ```json Response theme={null}
      {
          "id": "pay_AAAAA",
          "type": "direct",
          "status": "pending",
          "account_connection": "acon_XXXXX",
          "amount_in_cents": 10000,
          "description": "Royalties for Hey Jude",
          "date": "2024-11-12T20:22:49.075Z",
          "destination": "Manifest Account - Paul McCartney",
          "fee_in_cents": 10,
          "userdata": {},
          "created_at": "2024-11-12T20:22:49.075Z",
          "updated_at": "2024-11-12T20:22:49.075Z"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="List">
    <Card icon="square-list" iconType="solid" color="#BDE1CD">
      **`GET`  /payout**<br />
      List all payouts from your enterprise.
    </Card>

    ## Query Parameters

    <ParamField query="page" type="integer">
      The page number to return. Default is 1.
    </ParamField>

    <ParamField query="page_size" type="integer">
      The number of items to return per page. Default is 10.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      {
          "data": [
              {
                  "id": "pay_CCCCC",
                  "type": "direct",
                  "status": "sent",
                  "account_connection": "acon_XXXXX",
                  "amount_in_cents": 10000,
                  "description": "January Payout",
                  "date": "2024-01-15T20:22:49.075Z",
                  "destination": "Manifest Account - Paul McCartney",
                  "fee_in_cents": 5,
                  "userdata": {},
                  "created_at": "2024-01-15T20:22:49.075Z",
                  "updated_at": "2024-01-15T20:22:49.075Z"
              },
              {
                  "id": "pay_BBBBB",
                  "type": "direct",
                  "status": "sent",
                  "account_connection": "acon_YYYYY",
                  "amount_in_cents": 10000,
                  "description": "January Payout",
                  "date": "2024-14-12T20:22:49.075Z",
                  "destination": "Manifest Account - Ringo Starr",
                  "fee_in_cents": 10,
                  "userdata": {},
                  "created_at": "2024-14-12T20:22:49.075Z",
                  "updated_at": "2024-14-12T20:22:49.075Z"
              },
              {
                  "id": "pay_AAAAA",
                  "type": "direct",
                  "status": "sent",
                  "account_connection": "acon_XXXXX",
                  "amount_in_cents": 10000,
                  "description": "December Payout",
                  "date": "2024-11-12T20:22:49.075Z",
                  "destination": "Manifest Account - Paul McCartney",
                  "fee_in_cents": 10,
                  "userdata": {},
                  "created_at": "2024-11-12T20:22:49.075Z",
                  "updated_at": "2024-11-12T20:22:49.075Z"
              },
          ],
          "pagination": {
              "page": 1,
              "page_size": 10,
              "total": 3
          }
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="List for Account Connection">
    <Card icon="square-list" iconType="solid" color="#BDE1CD">
      **`GET`  /account-connection/:id/payout**<br />
      List all payouts from your enterprise to a specific account connection.
    </Card>

    ## Path Parameters

    <ParamField path="id" type="string" required="true">
      The ID of the account connection to list payouts for.
    </ParamField>

    ## Query Parameters

    <ParamField query="page" type="integer">
      The page number to return. Default is 1.
    </ParamField>

    <ParamField query="page_size" type="integer">
      The number of items to return per page. Default is 10.
    </ParamField>

    ## Example

    <CodeGroup>
      ```json Response theme={null}
      {
          "data": [
              {
                  "id": "pay_CCCCC",
                  "type": "direct",
                  "status": "sent",
                  "account_connection": "acon_XXXXX",
                  "amount_in_cents": 10000,
                  "description": "January Payout",
                  "date": "2024-01-15T20:22:49.075Z",
                  "destination": "Manifest Account - Paul McCartney",
                  "fee_in_cents": 5,
                  "userdata": {},
                  "created_at": "2024-01-15T20:22:49.075Z",
                  "updated_at": "2024-01-15T20:22:49.075Z"
              },
              {
                  "id": "pay_BBBBB",
                  "type": "direct",
                  "status": "sent",
                  "account_connection": "acon_XXXXX",
                  "amount_in_cents": 10000,
                  "description": "December Payout",
                  "date": "2024-14-12T20:22:49.075Z",
                  "destination": "Manifest Account - Paul McCartney",
                  "fee_in_cents": 10,
                  "userdata": {},
                  "created_at": "2024-14-12T20:22:49.075Z",
                  "updated_at": "2024-14-12T20:22:49.075Z"
              },
              {
                  "id": "pay_AAAAA",
                  "type": "direct",
                  "status": "sent",
                  "account_connection": "acon_XXXXX",
                  "description": "November Payout",
                  "date": "2024-11-12T20:22:49.075Z",
                  "destination": "Manifest Account - Paul McCartney",
                  "amount_in_cents": 10000,
                  "fee_in_cents": 10,
                  "userdata": {},
                  "created_at": "2024-11-12T20:22:49.075Z",
                  "updated_at": "2024-11-12T20:22:49.075Z"
              },
          ],
          "pagination": {
              "page": 1,
              "page_size": 10,
              "total": 3
          }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

***

# Properties

<ParamField path="id" type="string">
  Identifier for this payout.
</ParamField>

<ParamField path="account_connection" type="string">
  ID of Account Connection to pay
</ParamField>

<ParamField path="description" type="string">
  Description of payout. (Visible to creators.)
</ParamField>

<ParamField path="date" type="string">
  Schedule a future payout by setting its date with an [ISO 8601 date/time string](https://www.w3.org/TR/NOTE-datetime). If omitted, payout will be queued for processing immediately.
</ParamField>

<ParamField path="destination" type="string">
  A plaintext label of the payout's destination account, suitable for display.
</ParamField>

<ParamField path="amount_in_cents" type="number">
  Amount in cents, e.g. \$1.00 would be the number 100.
</ParamField>

<ParamField path="fee_in_cents" type="number">
  Fee paid to Manifest for this payout, in cents, e.g. \$1.00 would be the number 100.
</ParamField>

<ParamField path="type" type="string">
  Type of payment. One of `direct`, `ach`, `wallet`, or `unclaimed`. This field will be populated based on the Account Connection type at the time of payment.

  <Info>Note: Payouts to inactive account connections are considered `unclaimed` and allow the recipient 30 days to activate their account connnection and receive their payout.</Info>
</ParamField>

<ParamField path="activity" type="object[]">
  An activity log that tracks the status changes, internal transfers, and any errors associated with a given payout.
</ParamField>

<ParamField path="status" type="string">
  Status of payout. One of:

  | Status                | Description                                                                                                                                                                                                                                                                                           |
  | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `created`             | Initial status after object creation. Payouts should only remain in this status a few seconds.                                                                                                                                                                                                        |
  | `ready`               | Once a payout's funds have been moved to your enterprise's pending payouts account, the payout will be changed to `ready` status.                                                                                                                                                                     |
  | `pending`             | The payment to the creator has been initiated, based on the `type` of the account connection. Final fees are calculated, and any over-estimated fees are put back in your operating account.<br /><br />ACH: Payment is queued for processing, which happens periodically throughout the banking day. |
  | `sent`                | Manifest: The payment was completed and the amount is now available in the creator's account.<br /><br />ACH: The payment was processed and sent out to the ACH network for clearing and settlement.                                                                                                  |
  | `error`               | The transfer encountered an error during processing. The reasons a transfer might be set to error include insufficient funds, suspected fraud, or failed validation.<br /><br />Check your payout's `activity` log for details.                                                                       |
  | `returned` (ACH only) | The transfer was processed and sent, but the network or receiving bank could not complete the transfer successfully. The payout amount has been returned to your operating account.                                                                                                                   |
  | `canceled`            | The payout was canceled by you before its `date`. The pending funds have been returned to your operating account.                                                                                                                                                                                     |
</ParamField>

<ParamField path="user_data" type="object">
  User defined data that can be attached to the object. See the [User Data](/reference/user-data) page for details.
</ParamField>