openapi: 3.2.0
info:
  version: 1.0.0
  title: CreatorIQ Payments Payouts API
  description: 'The Payments API exposes read-only access to a partner''s creator payouts,

    payables and creator payment-info collection status. It is the public

    counterpart of the CreatorIQ Payments product and lets integrators reconcile

    payout data, monitor payable statuses and track which creators still need to

    submit their payment information.


    ## Key Use Cases:

    - **Reconcile payouts**: Retrieve a paginated list of payouts (creator view) with amounts, statuses and payout dates to reconcile against your own ledger.

    - **Track payables**: List individual payables with their campaign, currency, due/completion dates and current status.

    - **Monitor payment-info collection**: Identify creators whose payment info, tax info or approval is still pending so payouts are not blocked.


    ## Authentication

    All requests are authenticated with your API key sent in the `X-API-KEY`

    header. The platform gateway validates the key and implicitly scopes every

    response to the authenticated partner (and division, when the key is

    division-scoped).


    ## Pagination

    All endpoints use keyset (cursor) pagination. Send `PageSize`, `Direction`,

    `SortField` and `SortOrder` on the first request, then pass the `EndCursor`

    (forward) or `StartCursor` (backward) returned in `Metadata.Pagination` as the

    `Cursor` value to fetch the next page.

    '
  termsOfService: https://www.creatoriq.com/legal/terms-of-use
  contact:
    name: CreatorIQ
    url: https://www.creatoriq.com
    email: support@creatoriq.com
  license:
    url: https://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0
servers:
- url: https://apis.creatoriq.com
  description: Live
security:
- apiKey: []
tags:
- name: Payouts
  description: Creator payouts
paths:
  /payments/v1/payouts:
    get:
      tags:
      - Payouts
      summary: List payouts
      description: 'Returns a paginated list of the authenticated partner''s payouts in the

        creator view. Payouts are referenced exclusively by their customer-facing

        `PayoutID`; the internal payout identifier is never exposed.

        '
      operationId: listPayouts
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/Direction'
      - $ref: '#/components/parameters/SortOrder'
      - name: SortField
        in: query
        description: 'Field to sort by. One of: PayoutDate, PublisherID, CreatedAt.'
        required: true
        schema:
          type: string
          enum:
          - PayoutDate
          - PublisherID
          - CreatedAt
          examples:
          - PayoutDate
        examples:
          default:
            value: PayoutDate
      - name: PublisherID
        in: query
        description: Filters payouts by creator (publisher) id.
        required: false
        schema:
          type: integer
          minimum: 1
          examples:
          - 20985049
        examples:
          default:
            value: 20985049
      - name: DivisionID
        in: query
        description: Comma-separated list of division ids to filter by. Each entry must be a positive integer or the literal `null` (payouts with no division).
        required: false
        schema:
          type: string
          examples:
          - 12,34
        examples:
          default:
            value: 12,34
      - name: DateStart
        in: query
        description: Returns payouts with a payout date on or after this ISO 8601 UTC timestamp.
        required: false
        schema:
          type: string
          format: date-time
          examples:
          - '2026-05-01T00:00:00Z'
        examples:
          default:
            value: '2026-05-01T00:00:00Z'
      - name: DateEnd
        in: query
        description: Returns payouts with a payout date on or before this ISO 8601 UTC timestamp.
        required: false
        schema:
          type: string
          format: date-time
          examples:
          - '2026-06-01T00:00:00Z'
        examples:
          default:
            value: '2026-06-01T00:00:00Z'
      - name: IncludePayoutStatus
        in: query
        description: 'Comma-separated list of payout statuses to include. Mutually exclusive with `ExcludePayoutStatus`. `NO ACCOUNT` is not accepted as a filter value. Valid values: READY, UNPAYABLE, BELOW MINIMUM, SUBMITTED, PROCESSING, SENT, SUBMISSION FAILED, PAID, CANCELLED, FAILED.'
        required: false
        schema:
          type: string
          examples:
          - READY,PAID
        examples:
          default:
            value: READY,PAID
      - name: ExcludePayoutStatus
        in: query
        description: Comma-separated list of payout statuses to exclude. Mutually exclusive with `IncludePayoutStatus`. `NO ACCOUNT` is not accepted as a filter value.
        required: false
        schema:
          type: string
          examples:
          - CANCELLED,FAILED
        examples:
          default:
            value: CANCELLED,FAILED
      - name: Currency
        in: query
        description: Comma-separated list of ISO 4217 currency codes to filter by.
        required: false
        schema:
          type: string
          examples:
          - USD,EUR
        examples:
          default:
            value: USD,EUR
      - name: PublisherIsPayable
        in: query
        description: Filters by whether the creator is currently payable.
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          examples:
          - 'true'
        examples:
          default:
            value: 'true'
      - name: ExcludeCancelledPayouts
        in: query
        description: When `true`, cancelled payouts are omitted from the response.
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          examples:
          - 'true'
        examples:
          default:
            value: 'true'
      responses:
        '200':
          description: A paginated list of payouts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutsCollectionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
      - apiKey: []
      servers:
      - url: https://apis.creatoriq.com
        description: Live
components:
  responses:
    ForbiddenError:
      description: Forbidden - the API key is missing, invalid or lacks access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequestError:
      description: Bad Request - invalid or missing query parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CollectionMetadata:
      type: object
      description: Metadata wrapper carrying pagination details.
      properties:
        Pagination:
          $ref: '#/components/schemas/PaginationResponse'
      required:
      - Pagination
    PaginationResponse:
      type: object
      description: Keyset pagination metadata.
      properties:
        StartCursor:
          type:
          - string
          - 'null'
          description: Cursor pointing at the first row of the current page. Pass it with `Direction=backward` to page back.
          examples:
          - cGF5b3V0X2RhdGU7OzEyMzQ1
        EndCursor:
          type:
          - string
          - 'null'
          description: Cursor pointing at the last row of the current page. Pass it with `Direction=forward` to page ahead.
          examples:
          - cGF5b3V0X2RhdGU7OzEyMzk5
        HasNextPage:
          type: boolean
          description: Whether more items are available after the current page.
          examples:
          - true
        HasPreviousPage:
          type: boolean
          description: Whether items are available before the current page.
          examples:
          - false
        PageSize:
          type: integer
          description: Number of items returned in the current page.
          examples:
          - 50
      required:
      - StartCursor
      - EndCursor
      - HasNextPage
      - HasPreviousPage
      - PageSize
    Amount:
      type: object
      description: A monetary amount with its currency.
      properties:
        Value:
          type: string
          description: Decimal amount, serialized as a string to preserve precision.
          examples:
          - '1250.00'
        Currency:
          type: string
          description: ISO 4217 currency code.
          examples:
          - USD
      required:
      - Value
      - Currency
    ErrorResponse:
      type: object
      description: Standard error response body.
      properties:
        ErrorMessage:
          type: string
          description: Human-readable error message.
          examples:
          - 'Invalid SortField, need one of: PayoutDate, PublisherID, CreatedAt'
        Type:
          type: string
          description: Error type identifier.
          examples:
          - InvalidPayoutFiltersError
        Details:
          type: array
          description: Additional error details.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        Context:
          type: object
          description: Additional error context.
      required:
      - ErrorMessage
    Payout:
      type: object
      description: A payout in the creator view.
      properties:
        PayoutID:
          type:
          - string
          - 'null'
          description: Customer-facing payout identifier.
          examples:
          - PO-2026-000123
        HasRetries:
          type: boolean
          description: Whether the payout has been retried.
          examples:
          - false
        PayoutDate:
          type:
          - string
          - 'null'
          description: When the payout was (or is scheduled to be) paid.
          format: date-time
          examples:
          - '2026-05-19T07:00:00Z'
        PublisherID:
          type: integer
          description: Creator (publisher) id.
          examples:
          - 20985049
        DivisionID:
          type:
          - integer
          - 'null'
          description: Division the payout belongs to.
          examples:
          - 12
        DivisionName:
          type:
          - string
          - 'null'
          description: Division name.
          examples:
          - North America
        PublisherName:
          type: string
          description: Creator name.
          examples:
          - Jordan Lee
        ProfilePictureURL:
          type:
          - string
          - 'null'
          description: Creator profile picture URL.
          examples:
          - https://static-resources.creatoriq.com/avatars/20985049.jpg
        PrimaryNetwork:
          type:
          - string
          - 'null'
          description: Creator's primary social network.
          examples:
          - instagram
        PrimarySocialUsername:
          type:
          - string
          - 'null'
          description: Creator's primary social username.
          examples:
          - jordanlee
        PublisherIsPayable:
          type: boolean
          description: Whether the creator is currently payable.
          default: false
          examples:
          - true
        PayoutMethod:
          type:
          - string
          - 'null'
          description: Method used for the payout.
          examples:
          - bank_transfer
        PayoutStatus:
          type: string
          enum:
          - READY
          - UNPAYABLE
          - BELOW MINIMUM
          - NO ACCOUNT
          - SUBMITTED
          - PROCESSING
          - SENT
          - SUBMISSION FAILED
          - PAID
          - CANCELLED
          - FAILED
          description: Current payout status.
          examples:
          - PAID
        ErrorMessage:
          type:
          - string
          - 'null'
          description: Error message when the payout failed.
          examples:
          - null
        CancellationReason:
          type:
          - string
          - 'null'
          description: Reason the payout was cancelled, if applicable.
          examples:
          - null
        PayoutAmount:
          $ref: '#/components/schemas/Amount'
        CreatedAt:
          type:
          - string
          - 'null'
          description: When the payout was created.
          format: date-time
          examples:
          - '2026-05-01T09:15:00Z'
        UpdatedAt:
          type:
          - string
          - 'null'
          description: When the payout was last updated.
          format: date-time
          examples:
          - '2026-05-19T07:00:00Z'
      required:
      - PayoutID
      - HasRetries
      - PublisherID
      - PublisherName
      - PublisherIsPayable
      - PayoutStatus
      - PayoutAmount
    PayoutsCollectionResponse:
      type: object
      description: A page of payouts with pagination metadata.
      properties:
        Data:
          type: array
          description: Payouts in this page.
          items:
            $ref: '#/components/schemas/Payout'
        Metadata:
          $ref: '#/components/schemas/CollectionMetadata'
      required:
      - Data
      - Metadata
    ErrorDetail:
      type: object
      description: A single error detail entry.
      properties:
        Type:
          type: string
          description: Detail type.
          examples:
          - validation
        Message:
          type: string
          description: Detail message.
          examples:
          - PageSize must not exceed 200
        Context:
          type: object
          description: Detail context.
      required:
      - Type
  parameters:
    SortOrder:
      name: SortOrder
      in: query
      description: Sort order for the selected `SortField`.
      required: true
      schema:
        type: string
        enum:
        - asc
        - desc
        examples:
        - desc
      examples:
        default:
          value: desc
    Cursor:
      name: Cursor
      in: query
      description: Base64 keyset pagination cursor. Pass the `EndCursor` (forward) or `StartCursor` (backward) from the previous response's `Metadata.Pagination`. Omit on the first request.
      required: false
      schema:
        type: string
        examples:
        - cGF5b3V0X2RhdGU7OzEyMzQ1
      examples:
        default:
          value: cGF5b3V0X2RhdGU7OzEyMzQ1
    PageSize:
      name: PageSize
      in: query
      description: Number of items to return per page. Must be a positive integer, capped at 200.
      required: true
      schema:
        type: integer
        minimum: 1
        maximum: 200
        examples:
        - 50
      examples:
        default:
          value: 50
    Direction:
      name: Direction
      in: query
      description: Pagination direction relative to the supplied cursor.
      required: true
      schema:
        type: string
        enum:
        - forward
        - backward
        examples:
        - forward
      examples:
        default:
          value: forward
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-KEY
      in: header