openapi: 3.0.3
info:
  title: Everflow Affiliate API - Invoices
  description: >
    Invoice endpoints for the Everflow Affiliate API. Affiliates can view their
    billing invoices, including line item details and payment history.
    For more detail, see [Processing Partner Invoices](https://helpdesk.everflow.io/customer/processing-partner-invoices) in the Help Center.
  version: 1.0.0
servers:
  - description: Production Server
    url: https://api.eflow.team/v1
tags:
  - name: Affiliate Invoices
    description: Endpoints for viewing affiliate invoices and billing details.
paths:
  /affiliates/billings/affiliates/invoicestable:
    post:
      summary: Find Invoices (Advanced)
      tags:
        - Affiliate Invoices
      parameters:
        - in: query
          name: page
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: The page of results to retrieve.
        - in: query
          name: page_size
          required: false
          schema:
            type: integer
            minimum: 1
            default: 50
          description: The number of results to return per page.
      requestBody:
        required: true
        content:
          application/json:
            example:
              filters:
                affiliate_invoice_status: "unpaid"
              page: 1
              page_size: 50
            schema:
              type: object
              properties:
                filters:
                  type: object
                  description: Filter criteria for invoices.
                  properties:
                    affiliate_invoice_status:
                      type: string
                      enum:
                        - paid
                        - unpaid
                        - deleted
                      description: Filter by invoice payment status.
                    min_start_time:
                      type: string
                      format: date-time
                      description: Minimum start date for the invoice period.
                    max_end_time:
                      type: string
                      format: date-time
                      description: Maximum end date for the invoice period.
                    min_balance:
                      type: number
                      description: Minimum invoice balance to include.
                    max_balance:
                      type: number
                      description: Maximum invoice balance to include.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    description: Array of invoices.
                    items:
                      $ref: "#/components/schemas/InvoiceTableItem"
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total_count:
                        type: integer
      security:
        - API Key: []

  /affiliates/billings/affiliates/invoices/{invoiceId}:
    get:
      summary: Get Invoice By ID
      tags:
        - Affiliate Invoices
      parameters:
        - name: invoiceId
          in: path
          required: true
          description: The numeric ID of the invoice.
          schema:
            type: integer
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  network_affiliate_invoice_id:
                    type: integer
                    description: Unique identifier for the invoice.
                  network_id:
                    type: integer
                    description: The network ID.
                  network_affiliate_id:
                    type: integer
                    description: The affiliate ID.
                  status:
                    type: string
                    description: Payment status of the invoice (paid, unpaid).
                  start_time:
                    type: string
                    format: date-time
                    description: Start of the billing period.
                  end_time:
                    type: string
                    format: date-time
                    description: End of the billing period.
                  notes:
                    type: string
                    description: Notes on the invoice.
                  balance:
                    type: number
                    description: Outstanding balance on the invoice.
                  timezone_id:
                    type: integer
                    description: Timezone ID for the invoice period.
                  currency_id:
                    type: string
                    description: Currency code for the invoice (e.g. "USD").
                  time_created:
                    type: integer
                    example: 1734455015
                    description: Unix timestamp of when the invoice was created.
                  time_saved:
                    type: integer
                    example: 1734455015
                    description: Unix timestamp of when the invoice was last saved.
                  relationship:
                    type: object
                    description: Related data for the invoice.
                    properties:
                      details:
                        type: array
                        description: Line item breakdown for the invoice.
                        items:
                          $ref: "#/components/schemas/InvoiceDetail"
                      payments:
                        type: array
                        description: Payment records for the invoice.
                        items:
                          $ref: "#/components/schemas/InvoicePayment"
                      extra_periods:
                        type: array
                        description: Additional billing periods included in the invoice.
                        items:
                          type: object
                          properties:
                            network_affiliate_invoice_extra_period_id:
                              type: integer
                              description: Unique identifier for the extra period.
                            network_affiliate_invoice_id:
                              type: integer
                              description: The parent invoice ID.
                            start_time:
                              type: string
                              format: date-time
                              description: Start of the extra period.
                            end_time:
                              type: string
                              format: date-time
                              description: End of the extra period.
                            timezone_id:
                              type: integer
                              description: Timezone ID for the extra period.
                            time_created:
                              type: integer
                              example: 1734455015
                              description: Unix timestamp of when the extra period was created.
                            time_saved:
                              type: integer
                              example: 1734455015
                              description: Unix timestamp of when the extra period was last saved.
                            relationship:
                              type: object
                              properties:
                                associated_details:
                                  type: array
                                  description: Line items associated with this extra period.
                                  items:
                                    allOf:
                                      - $ref: "#/components/schemas/InvoiceDetail"
                                      - type: object
                                        properties:
                                          relationship:
                                            type: object
                                            properties:
                                              extra_period_id:
                                                type: integer
                                                description: The extra period ID this detail belongs to.
        "404":
          description: Invoice not found or does not belong to the authenticated affiliate.
      security:
        - API Key: []

components:
  schemas:
    InvoiceTableItem:
      type: object
      properties:
        network_affiliate_invoice_id:
          type: integer
          description: Unique identifier for the invoice.
        network_id:
          type: integer
          description: The network ID.
        affiliate_invoice_status:
          type: string
          description: Payment status of the invoice (paid, unpaid).
        start_time:
          type: string
          format: date-time
          description: Start of the billing period.
        end_time:
          type: string
          format: date-time
          description: End of the billing period.
        timezone_id:
          type: integer
          description: Timezone ID for the invoice period.
        balance:
          type: number
          description: Outstanding balance on the invoice.
        billed:
          type: number
          description: Total amount billed.
        paid:
          type: number
          description: Total amount paid.
        payment_terms:
          type: string
          description: Payment terms for the invoice (e.g. Net 30, Net 60).
        currency_id:
          type: string
          description: Currency code for the invoice (e.g. "USD").
        notes:
          type: string
          description: Notes on the invoice.
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of when the invoice was created.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of when the invoice was last saved.

    InvoiceDetail:
      type: object
      properties:
        network_affiliate_invoice_detail_id:
          type: integer
          description: Unique identifier for the line item.
        network_affiliate_invoice_id:
          type: integer
          description: The parent invoice ID.
        network_offer_id:
          type: integer
          description: Associated offer ID (0 if not applicable).
        network_offer_name:
          type: string
          description: Name of the associated offer.
        amount:
          type: number
          description: Amount for this line item.
        invoice_currency_amount:
          type: number
          description: Amount in the invoice currency.
        currency_id:
          type: string
          description: Currency code for this line item.
        notes:
          type: string
          description: Notes for this line item.
        quantity:
          type: integer
          description: Quantity of items (e.g. number of conversions).
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of when the detail was created.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of when the detail was last saved.
        referral_history_id:
          type: integer
          description: Associated referral history ID (0 if not applicable).
        type:
          type: string
          enum:
            - referral
            - offer_detail
            - vat
            - adjustment
          description: >
            Type of line item. "referral" for referral commissions,
            "offer_detail" for offer-level earnings, "vat" for
            tax entries, "adjustment" for manual adjustments.

    InvoicePayment:
      type: object
      properties:
        network_affiliate_payment_id:
          type: integer
          description: Unique identifier for the payment.
        network_id:
          type: integer
          description: The network ID.
        network_affiliate_invoice_id:
          type: integer
          description: The parent invoice ID.
        status:
          type: string
          description: Payment status (e.g. pending, approved, rejected, completed).
        notes:
          type: string
          description: Notes for this payment.
        amount:
          type: number
          description: Payment amount.
        currency:
          type: string
          description: Currency code for the payment.
        unix_timestamp:
          type: integer
          description: Unix timestamp of the payment.
        payment_type:
          type: string
          description: Type of payment (e.g. pay).
        payee_original_amount:
          type: number
          description: Original amount in the payee's currency.
        payee_fee_amount:
          type: number
          description: Fee amount charged to the payee.
        payee_currency:
          type: string
          description: Currency code for the payee.
        time_approved:
          type: integer
          example: 1734455015
          description: Unix timestamp of when the payment was approved (0 if not approved).
        time_completed:
          type: integer
          example: 1734455015
          description: Unix timestamp of when the payment was completed (0 if not completed).

  securitySchemes:
    API Key:
      description: >
        The affiliate's API key generated from the Affiliate Portal.
        Uses the X-Eflow-Api-Key header.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey