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

# List payouts

> Lists the business's payouts, newest first by `initiated_at`. A payout is one transfer of your available balance in one currency to your bank account. Its figures are the ones the Finance page of the dashboard shows. This resource follows the API convention: `{object, id}` references, `*_minor_units` amounts, millisecond UTC timestamps.

Requires the `payouts` permission at `read`. An API key holds a permission at the lower of its own level (`read` for a read-only key) and its holder's role; a key without it is refused with 403.



## OpenAPI

````yaml /api-reference/commerce-v1.openapi.json get /v1/commerce/payouts
openapi: 3.0.3
info:
  description: >-
    Public REST API for COPE vendor integrations. Authenticate with a COPE API
    key and call the endpoints described below.
  title: COPE Public API
  version: v1
servers:
  - description: Production
    url: https://api.cope.com
security:
  - cope_sk: []
paths:
  /v1/commerce/payouts:
    get:
      tags:
        - Payouts
      summary: List payouts
      description: >-
        Lists the business's payouts, newest first by `initiated_at`. A payout
        is one transfer of your available balance in one currency to your bank
        account. Its figures are the ones the Finance page of the dashboard
        shows. This resource follows the API convention: `{object, id}`
        references, `*_minor_units` amounts, millisecond UTC timestamps.


        Requires the `payouts` permission at `read`. An API key holds a
        permission at the lower of its own level (`read` for a read-only key)
        and its holder's role; a key without it is refused with 403.
      operationId: commerce.payouts.list
      parameters:
        - description: >-
            Page number for paginated results. Values below 1 and non-numeric
            values are ignored and the first page is returned; a page past the
            last one returns the last page. `current_page` is accepted as an
            older name for it and wins when both are sent.
          in: query
          name: page
          required: false
          schema:
            minimum: 1
            type: integer
        - description: >-
            Number of records per page. Defaults to 12; values above 25 are
            clamped to 25; values below 1 and non-numeric values are ignored and
            the default is used. `items` and `limit` are accepted as older names
            for it, read only when `per_page` is absent.
          in: query
          name: per_page
          required: false
          schema:
            maximum: 25
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  data:
                    items:
                      additionalProperties: false
                      properties:
                        amount_minor_units:
                          description: >-
                            The balance this payout took, in minor units of
                            `currency`: the sum of its transactions, before the
                            payout fee.
                          type: integer
                        arrival_date:
                          description: >-
                            The calendar day the money reaches your bank
                            account. Null when no arrival is expected: on a
                            `failed`, `canceled` or `retrying` payout, and on
                            one that is long overdue.
                          format: date
                          nullable: true
                          type: string
                        arrival_estimated:
                          description: >-
                            True while `arrival_date` is an estimate that can
                            still move; false once the payout has settled.
                          type: boolean
                        currency:
                          type: string
                        fee_minor_units:
                          description: The payout fee, in minor units of `currency`.
                          type: integer
                        id:
                          example: po_A1b2C3d4E5f6G7h8
                          pattern: ^po_[A-Za-z0-9]{8,32}$
                          type: string
                        initiated_at:
                          description: When the payout was initiated.
                          format: date-time
                          nullable: true
                          type: string
                        object:
                          enum:
                            - payout
                          type: string
                        payout_date:
                          description: The calendar day (UTC) the payout was initiated.
                          format: date
                          nullable: true
                          type: string
                        settled_at:
                          description: When the payout settled. Null until then.
                          format: date-time
                          nullable: true
                          type: string
                        status:
                          description: >-
                            `processing`: the payout was created and the
                            transfer has not been confirmed yet. `retrying`: the
                            transfer could not be made and is attempted again on
                            the following days. `pending`: the money is on its
                            way to your bank. `paid`: it arrived. `failed` and
                            `canceled`: no money was paid out, and the amount
                            stays in your balance.
                          enum:
                            - processing
                            - retrying
                            - pending
                            - paid
                            - failed
                            - canceled
                          type: string
                        transaction_count:
                          description: >-
                            How many items the payout is made of, the
                            `total_count` of GET
                            /v1/commerce/payouts/{id}/transactions.
                          type: integer
                        transfer_amount_minor_units:
                          description: >-
                            What is transferred to your bank account:
                            `amount_minor_units` minus `fee_minor_units`.
                          type: integer
                        transferred_at:
                          description: When the transfer was made. Null until then.
                          format: date-time
                          nullable: true
                          type: string
                      required:
                        - object
                        - id
                        - status
                        - amount_minor_units
                        - fee_minor_units
                        - transfer_amount_minor_units
                        - currency
                        - payout_date
                        - arrival_date
                        - arrival_estimated
                        - initiated_at
                        - transferred_at
                        - settled_at
                        - transaction_count
                      type: object
                    type: array
                  pagination:
                    additionalProperties: false
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type: integer
                      total_count:
                        type: integer
                      total_pages:
                        type: integer
                    required:
                      - total_pages
                      - current_page
                      - per_page
                      - total_count
                    type: object
                required:
                  - data
                  - pagination
                type: object
          description: Successful response
        '400':
          content:
            application/problem+json:
              examples:
                unparsable_request:
                  summary: Unparsable request
                  value:
                    code: invalid_request
                    detail: >-
                      The request could not be parsed. Check the query string
                      and the request body.
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 400
                    title: Invalid Request
                    type: https://docs.cope.com/errors/invalid_request
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: Invalid request
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: Missing or invalid bearer token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: Bearer token is not authorized for this route
        '503':
          content:
            application/problem+json:
              examples:
                user_not_ready:
                  summary: The key's user is not available yet
                  value:
                    code: user_not_ready
                    detail: Retry after 2 seconds
                    errors:
                      - code: user_not_ready
                        detail: Retry after 2 seconds
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 503
                    title: User Not Ready
                    type: https://docs.cope.com/errors/user_not_ready
                tenant_not_ready:
                  summary: The key's business is not available yet
                  value:
                    code: tenant_not_ready
                    detail: Retry after 2 seconds
                    errors:
                      - code: tenant_not_ready
                        detail: Retry after 2 seconds
                    request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90
                    status: 503
                    title: Tenant Not Ready
                    type: https://docs.cope.com/errors/tenant_not_ready
              schema:
                $ref: '#/components/schemas/PublicProblemDetail'
          description: >-
            The API key is valid but its user or business is not available to
            this API yet (`user_not_ready`, `tenant_not_ready`). Retry after the
            `Retry-After` seconds.
      security:
        - cope_sk: []
components:
  schemas:
    PublicProblemDetail:
      additionalProperties: false
      properties:
        code:
          type: string
        detail:
          nullable: true
          type: string
        errors:
          items:
            additionalProperties: false
            properties:
              code:
                type: string
              detail:
                type: string
              param:
                type: string
            required:
              - code
              - detail
            type: object
          type: array
        request_id:
          description: >-
            Correlates this response with COPE's logs; the response also carries
            it as `X-Request-Id`. It is the `X-Request-Id` you sent when that is
            1-128 letters, digits, `_`, `@` or `-`, and otherwise one COPE
            generated. Quote it when you contact support.
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
      required:
        - type
        - title
        - status
        - code
        - request_id
      type: object
  securitySchemes:
    cope_sk:
      description: >-
        Bearer credential for the public API: a live COPE API key (`ck_live_*`;
        keys issued earlier as `cope_sk_live_*` keep working). Dashboard sign-in
        tokens are not accepted.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.