CreatorIQ Payouts API

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.'
  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:
  schemas:
    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
    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
    CollectionMetadata:
      type: object
      description: Metadata wrapper carrying pagination details.
      properties:
        Pagination:
          $ref: '#/components/schemas/PaginationResponse'
      required:
      - Pagination
    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
    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
    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
    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
  parameters:
    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
    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
    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
  responses:
    ForbiddenError:
      description: Forbidden - the API key is missing, invalid or lacks access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal Server Error.
      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'
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-KEY
      in: header