openapi: 3.2.0
info:
  version: 1.0.0
  title: CreatorIQ Payments Payables 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: Payables
  description: Creator payables
paths:
  /payments/v1/payables:
    get:
      tags:
      - Payables
      summary: List payables
      description: 'Returns a paginated list of the authenticated partner''s payables.

        Payables are referenced by their customer-facing `PayableID`;

        the internal payable identifier is never exposed. Filters are additive

        (combined with AND).

        '
      operationId: listPayables
      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: CampaignID, CreatedAt.'
        required: true
        schema:
          type: string
          enum:
          - CampaignID
          - CreatedAt
          examples:
          - CreatedAt
        examples:
          default:
            value: CreatedAt
      - name: PublisherID
        in: query
        description: Filters payables by creator (publisher) id.
        required: false
        schema:
          type: integer
          minimum: 1
          examples:
          - 20985049
        examples:
          default:
            value: 20985049
      - name: CampaignID
        in: query
        description: Filters payables by campaign id.
        required: false
        schema:
          type: integer
          minimum: 1
          examples:
          - 1205052
        examples:
          default:
            value: 1205052
      - name: PayoutID
        in: query
        description: Id of the payout the payable is currently assigned to.
        required: false
        schema:
          type: string
          examples:
          - PO-2026-000123
        examples:
          default:
            value: PO-2026-000123
      - name: PayableStatus
        in: query
        description: 'Comma-separated list of payable statuses to filter by. `NO ACCOUNT` is not accepted as a filter value. Valid values: IN_REVIEW, REJECTED, READY, UNPAYABLE, BELOW MINIMUM, SUBMITTED, PROCESSING, SENT, SUBMISSION FAILED, PAID, CANCELLED, FAILED.'
        required: false
        schema:
          type: string
          examples:
          - READY,IN_REVIEW
        examples:
          default:
            value: READY,IN_REVIEW
      - 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: CompletedAtStart
        in: query
        description: Returns payables completed 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: CompletedAtEnd
        in: query
        description: Returns payables completed 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'
      responses:
        '200':
          description: A paginated list of payables.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayablesCollectionResponse'
        '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
    Payable:
      type: object
      description: A single payable.
      properties:
        PayableID:
          type:
          - string
          - 'null'
          description: Customer-facing payable identifier.
          examples:
          - PA-2026-000987
        PublisherID:
          type: integer
          description: Creator (publisher) id.
          examples:
          - 20985049
        PayoutID:
          type:
          - string
          - 'null'
          description: Id of the payout the payable is assigned to, if any.
          examples:
          - PO-2026-000123
        CampaignID:
          type:
          - integer
          - 'null'
          description: Campaign the payable belongs to.
          examples:
          - 1205052
        CampaignExternalName:
          type:
          - string
          - 'null'
          description: External campaign name.
          examples:
          - Summer 2026 Launch
        CampaignInternalName:
          type:
          - string
          - 'null'
          description: Internal campaign name.
          examples:
          - SUM26-US
        CompletedAt:
          type:
          - string
          - 'null'
          description: When the payable was completed.
          format: date-time
          examples:
          - '2026-05-18T12:00:00Z'
        DueDate:
          type:
          - string
          - 'null'
          description: When the payable is due.
          format: date-time
          examples:
          - '2026-06-01T00:00:00Z'
        PayableStatus:
          type: string
          enum:
          - IN_REVIEW
          - REJECTED
          - READY
          - UNPAYABLE
          - BELOW MINIMUM
          - NO ACCOUNT
          - SUBMITTED
          - PROCESSING
          - SENT
          - SUBMISSION FAILED
          - PAID
          - CANCELLED
          - FAILED
          description: Current payable status.
          examples:
          - READY
        RequirementID:
          type:
          - string
          - 'null'
          description: Campaign requirement the payable originates from.
          examples:
          - req_88231
        TransactionID:
          type:
          - string
          - 'null'
          description: Associated transaction id.
          examples:
          - txn_55120
        PayableAmount:
          $ref: '#/components/schemas/Amount'
        NetworkCampaignID:
          type:
          - string
          - 'null'
          description: Network campaign id.
          examples:
          - nc_4471
        PONumber:
          type: string
          description: Purchase order number.
          examples:
          - PO-4471
        CreatedAt:
          type: string
          description: When the payable was created.
          format: date-time
          examples:
          - '2026-05-01T09:15:00Z'
        UpdatedAt:
          type: string
          description: When the payable was last updated.
          format: date-time
          examples:
          - '2026-05-18T12:00:00Z'
      required:
      - PayableID
      - PublisherID
      - PayableStatus
      - PayableAmount
      - PONumber
      - CreatedAt
      - UpdatedAt
    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
    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
    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
    PayablesCollectionResponse:
      type: object
      description: A page of payables with pagination metadata.
      properties:
        Data:
          type: array
          description: Payables in this page.
          items:
            $ref: '#/components/schemas/Payable'
        Metadata:
          $ref: '#/components/schemas/CollectionMetadata'
      required:
      - Data
      - Metadata
  parameters:
    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
    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
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-KEY
      in: header