openapi: 3.0.3
info:
  title: Everflow Network API - Billing (Affiliate Invoices)
  description: >
    Endpoints for managing affiliate/partner invoices and payments.
    For billing workflows, see the [Partner Invoices guide](https://helpdesk.everflow.io/customer/processing-partner-invoices).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Billing
paths:
  /networks/billings/affiliates/invoicestable:
    post:
      summary: Find Partner Invoices (Advanced)
      tags:
        - Billing
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number (1-based).
        - in: query
          name: page_size
          schema:
            type: integer
            default: 50
          description: Number of results per page.
      requestBody:
        content:
          application/json:
            example:
              search_terms: []
              filters:
                status: "unpaid"
            schema:
              type: object
              properties:
                search_terms:
                  type: array
                  description: >
                    Search terms are optional but can be used to look for specific words.
                  items:
                    type: object
                    required:
                      - search_type
                      - value
                    properties:
                      search_type:
                        type: string
                        enum:
                          - name
                        description: >
                          The name of the field used for search. On this endpoint, it can
                          only be "name". Searching by name will search the invoice ID,
                          the partner ID, and the partner name.
                      value:
                        type: string
                        description: The value to search.
                filters:
                  type: object
                  description: >
                    Filters are optional but are usually used to narrow down the set
                    of invoices returned. They can be used individually or combined in
                    a single request.
                  properties:
                    network_affiliate_ids:
                      type: array
                      items:
                        type: integer
                      description: One or multiple partner IDs for which the invoices will be returned.
                    network_affiliate_invoice_ids:
                      type: array
                      items:
                        type: integer
                      description: Return a specific set of invoice IDs.
                    account_manager_ids:
                      type: array
                      items:
                        type: integer
                      description: One or multiple account manager IDs for which the invoices will be returned.
                    min_start_time:
                      type: string
                      description: Only return invoices with a start date greater or equal to this value. Takes a date in the YYYY-MM-DD format.
                    max_end_time:
                      type: string
                      description: Only return invoices with an end date smaller or equal to this value. Takes a date in the YYYY-MM-DD format.
                    min_balance:
                      type: number
                      format: double
                      description: Only return invoices with an invoice balance greater than this value.
                    max_balance:
                      type: number
                      format: double
                      description: Only return invoices with an invoice balance smaller than this value.
                    affiliate_invoice_status:
                      type: string
                      enum:
                        - paid
                        - unpaid
                        - deleted
                      description: Only return invoices with this status.
                    is_hidden_affiliate:
                      type: string
                      enum:
                        - visible
                        - hidden
                      description: Filters based on whether the invoice is visible to the partner or not.
                    payment_terms:
                      type: array
                      items:
                        type: integer
                      description: Only return invoices for which the payment terms is a number of days contained in this array.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      type: object
                      properties:
                        network_affiliate_invoice_id:
                          type: integer
                          description: Unique invoice ID.
                        network_id:
                          type: integer
                          description: Network ID.
                        network_affiliate_id:
                          type: integer
                          description: The ID of the partner that was invoiced.
                        network_affiliate_name:
                          type: string
                          description: Name of the invoiced partner.
                        affiliate_invoice_status:
                          type: string
                          enum:
                            - paid
                            - unpaid
                            - deleted
                          description: Invoice status.
                        start_time:
                          type: string
                          description: Invoice period start date.
                        end_time:
                          type: string
                          description: Invoice period end date.
                        timezone_id:
                          type: integer
                          description: Timezone ID for the invoice period.
                        balance:
                          type: number
                          format: double
                          description: Outstanding balance.
                        billed:
                          type: number
                          format: double
                          description: Total billed amount.
                        paid:
                          type: number
                          format: double
                          description: Total paid amount.
                        currency_id:
                          type: string
                          description: Currency code (e.g. USD).
                        payment_terms:
                          type: integer
                          description: Number of days for the affiliate payment term (e.g. 20 for NET 20).
                        is_hidden_affiliate:
                          type: boolean
                          description: Whether the invoice is visible to the partner or not.
                        public_notes:
                          type: string
                          description: Notes visible to both network employees and the invoiced partner.
                        internal_notes:
                          type: string
                          description: Notes visible to network employees but not the invoiced partner.
                        payment_type:
                          type: string
                          description: Payment method type for this invoice.
                        is_payable:
                          type: boolean
                          description: Whether this invoice can be paid.
                        payment_status:
                          type: string
                          description: Payment processing status.
                        paid_date:
                          type: integer
                          description: Unix timestamp of when the invoice was paid. 0 if not yet paid.
                        time_created:
                          type: integer
                          example: 1734455015
                          description: Unix timestamp of creation.
                        time_saved:
                          type: integer
                          example: 1734455015
                          description: Unix timestamp of last update.
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total_count:
                        type: integer
      security:
        - API Key: []
  /networks/billings/affiliates/summary:
    post:
      summary: Get Invoice Summary
      tags:
        - Billing
      requestBody:
        content:
          application/json:
            example:
              filters:
                status: "unpaid"
            schema:
              type: object
              properties:
                search_terms:
                  type: array
                  description: Text search filters (same as the invoicestable endpoint).
                  items:
                    type: object
                    required:
                      - search_type
                      - value
                    properties:
                      search_type:
                        type: string
                        enum:
                          - name
                        description: The field to search on.
                      value:
                        type: string
                        description: The value to search.
                filters:
                  type: object
                  description: Filters (same as the invoicestable endpoint).
                  properties:
                    network_affiliate_ids:
                      type: array
                      items:
                        type: integer
                      description: Partner IDs to filter by.
                    network_affiliate_invoice_ids:
                      type: array
                      items:
                        type: integer
                      description: Specific invoice IDs to include.
                    account_manager_ids:
                      type: array
                      items:
                        type: integer
                      description: Account manager IDs to filter by.
                    min_start_time:
                      type: string
                      description: Start date filter (YYYY-MM-DD).
                    max_end_time:
                      type: string
                      description: End date filter (YYYY-MM-DD).
                    min_balance:
                      type: number
                      format: double
                      description: Minimum balance filter.
                    max_balance:
                      type: number
                      format: double
                      description: Maximum balance filter.
                    affiliate_invoice_status:
                      type: string
                      enum:
                        - paid
                        - unpaid
                        - deleted
                      description: Filter by invoice status.
                    is_hidden_affiliate:
                      type: string
                      enum:
                        - visible
                        - hidden
                      description: Filter by visibility to partner.
                    payment_terms:
                      type: array
                      items:
                        type: integer
                      description: Filter by payment terms (days).
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                    description: Total number of matching invoices.
                  balance:
                    type: number
                    format: double
                    description: Total outstanding balance.
                  billed:
                    type: number
                    format: double
                    description: Total billed amount.
                  paid:
                    type: number
                    format: double
                    description: Total paid amount.
      security:
        - API Key: []
  /networks/billings/affiliates/invoices/{invoiceId}:
    get:
      summary: Get Partner Invoice
      tags:
        - Billing
      parameters:
        - in: path
          name: invoiceId
          required: true
          schema:
            type: integer
          description: The unique invoice ID.
        - in: query
          name: relationship
          schema:
            type: string
            enum:
              - affiliate
              - all
          description: >
            Include additional related data in the response. The `details`
            and `payments` relationships are always returned. Use `affiliate`
            to add the affiliate object, or `all` to include everything.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        "404":
          description: Invoice not found.
      security:
        - API Key: []
    put:
      summary: Update Partner Invoice
      tags:
        - Billing
      parameters:
        - in: path
          name: invoiceId
          required: true
          schema:
            type: integer
          description: The unique invoice ID to update.
      requestBody:
        required: true
        content:
          application/json:
            example:
              invoice:
                network_affiliate_id: 7
                status: "unpaid"
                start_time: "2026-01-01"
                end_time: "2026-01-31"
                public_notes: "January 2026 earnings"
                internal_notes: "Includes bonus for Q4 performance"
                is_hidden_affiliate: false
                payment_terms: 30
              auto_correct: false
            schema:
              type: object
              properties:
                invoice:
                  type: object
                  description: The invoice object to update.
                  properties:
                    network_affiliate_id:
                      type: integer
                    status:
                      type: string
                      enum: [unpaid, paid, deleted]
                    start_time:
                      type: string
                    end_time:
                      type: string
                    public_notes:
                      type: string
                    internal_notes:
                      type: string
                    is_hidden_affiliate:
                      type: boolean
                    payment_terms:
                      type: integer
                auto_correct:
                  type: boolean
                  description: Whether to auto-correct the invoice.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
        "404":
          description: Invoice not found.
      security:
        - API Key: []
  /networks/billings/affiliates/invoices:
    post:
      summary: Create Partner Invoice
      tags:
        - Billing
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_affiliate_id: 7
              start_time: "2026-01-01"
              end_time: "2026-01-31"
              is_hidden_affiliate: false
              payment_terms: 30
              public_notes: "public note visible to affiliate"
              internal_notes: "internal note not visible to affiliate"
              details: []
              extra_periods: []
            schema:
              type: object
              properties:
                network_affiliate_id:
                  type: integer
                  description: The ID of the partner that will be invoiced.
                start_time:
                  type: string
                  description: Invoice start date in the YYYY-MM-DD format.
                end_time:
                  type: string
                  description: Invoice end date in the YYYY-MM-DD format.
                public_notes:
                  type: string
                  description: Notes that will be visible to both network employees and the invoiced partner.
                internal_notes:
                  type: string
                  description: Notes that will be visible to network employees but not the invoiced partner.
                is_hidden_affiliate:
                  type: boolean
                  description: Determines whether the invoice is visible to the partner or not.
                payment_terms:
                  type: integer
                  description: Number of days for the affiliate payment term (e.g. pass 20 for NET 20).
                details:
                  type: array
                  description: Invoice line items to include.
                  items:
                    type: object
                extra_periods:
                  type: array
                  description: Additional billing periods to include.
                  items:
                    type: object
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invoice"
      security:
        - API Key: []
    patch:
      summary: Batch Update Invoices
      tags:
        - Billing
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_affiliate_invoice_ids:
                - 1
                - 2
                - 3
              fields:
                - field_type: "status"
                  field_value: "unpaid"
                  operator: "overwrite"
            schema:
              type: object
              required:
                - network_affiliate_invoice_ids
                - fields
              properties:
                network_affiliate_invoice_ids:
                  type: array
                  items:
                    type: integer
                  description: Array of invoice IDs to update.
                fields:
                  type: array
                  description: >
                    Array of field changes to apply. Each item specifies a field
                    type, the new value, and how to apply it.
                  items:
                    type: object
                    required:
                      - field_type
                      - field_value
                      - operator
                    properties:
                      field_type:
                        type: string
                        description: The field to change (e.g. "status").
                      field_value:
                        description: The new value for the field.
                      operator:
                        type: string
                        description: How to apply the value.
                        enum:
                          - overwrite
                          - append
                          - delete
                          - clear
      responses:
        "200":
          description: Invoices updated successfully.
      security:
        - API Key: []
  /networks/billings/affiliates/payments:
    post:
      summary: Create Payment Batch
      tags:
        - Billing
      requestBody:
        required: true
        content:
          application/json:
            example:
              payments:
                - network_affiliate_invoice_id: 1
                  amount: 100.00
                  currency_id: "USD"
            schema:
              type: object
              required:
                - payments
              properties:
                payments:
                  type: array
                  description: Array of payment objects to process.
                  items:
                    type: object
                    required:
                      - network_affiliate_invoice_id
                      - amount
                      - currency_id
                    properties:
                      network_affiliate_invoice_id:
                        type: integer
                        description: The invoice ID to pay.
                      amount:
                        type: number
                        format: double
                        description: The payment amount.
                      currency_id:
                        type: string
                        description: The currency code (e.g. "USD").
      responses:
        "200":
          description: Payment batch created successfully.
      security:
        - API Key: []
components:
  schemas:
    Invoice:
      type: object
      properties:
        network_affiliate_invoice_id:
          type: integer
          description: Unique invoice ID.
        network_id:
          type: integer
          description: Network ID.
        network_affiliate_id:
          type: integer
          description: The ID of the partner that was invoiced.
        status:
          type: string
          enum:
            - paid
            - unpaid
            - deleted
          description: Invoice status.
        start_time:
          type: string
          description: Invoice period start date.
        end_time:
          type: string
          description: Invoice period end date.
        timezone_id:
          type: integer
          description: Timezone ID for the invoice period.
        balance:
          type: number
          format: double
          description: Outstanding balance.
        currency_id:
          type: string
          description: Currency code (e.g. USD).
        payment_terms:
          type: integer
          description: Number of days for the affiliate payment term (e.g. 20 for NET 20).
        is_hidden_affiliate:
          type: boolean
          description: Whether the invoice is visible to the partner or not.
        public_notes:
          type: string
          description: Notes visible to both network employees and the invoiced partner.
        internal_notes:
          type: string
          description: Notes visible to network employees but not the invoiced partner.
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
        relationship:
          type: object
          description: >
            Related data. The `details` and `payments` keys are always
            included. The `affiliate` key is included when
            `relationship=affiliate` or `relationship=all` is passed.
          properties:
            affiliate:
              type: object
              description: >
                The invoiced partner's details. Only included with
                `relationship=affiliate` or `relationship=all`.
            details:
              type: array
              description: Invoice line items.
              items:
                $ref: "#/components/schemas/InvoiceDetail"
            payments:
              type: array
              description: Payment history for this invoice.
              items:
                $ref: "#/components/schemas/InvoicePayment"
        details:
          type: array
          nullable: true
          description: Invoice line items (root-level, nullable).
          items:
            $ref: "#/components/schemas/InvoiceDetail"
        extra_periods:
          type: array
          nullable: true
          description: Additional billing periods associated with this invoice.
          items:
            type: object
    InvoiceDetail:
      type: object
      properties:
        network_affiliate_invoice_detail_id:
          type: integer
          description: Unique invoice detail ID.
        network_affiliate_invoice_id:
          type: integer
          description: Parent invoice ID.
        network_offer_id:
          type: integer
          description: Offer ID for this line item.
        network_offer_name:
          type: string
          description: Offer name for this line item.
        amount:
          type: number
          format: double
          description: Amount for this line item.
        invoice_currency_amount:
          type: number
          format: double
          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 for this line item.
        time_created:
          type: integer
          example: 1734455015
          description: Unix timestamp of creation.
        time_saved:
          type: integer
          example: 1734455015
          description: Unix timestamp of last update.
        referral_history_id:
          type: integer
          description: Referral history ID (0 if not a referral).
        type:
          type: string
          description: Line item type (e.g. offer_detail, vat).
    InvoicePayment:
      type: object
      properties:
        network_affiliate_payment_id:
          type: integer
          description: Unique payment ID.
        network_id:
          type: integer
          description: Network ID.
        network_affiliate_invoice_id:
          type: integer
          description: Invoice ID this payment belongs to.
        status:
          type: string
          description: Payment status.
        payment_type:
          type: string
          description: Payment method type.
        notes:
          type: string
          description: Payment notes.
        confirmation_code:
          type: string
          description: Payment confirmation code.
        amount:
          type: number
          format: double
          description: Payment amount.
        currency:
          type: string
          description: Payment currency code.
        unix_timestamp:
          type: integer
          example: 1734455015
          description: Unix timestamp of the payment.
        tax_id:
          type: string
          description: Tax ID associated with the payment.
        is_auto_generated:
          type: boolean
          description: Whether the payment was auto-generated.
        debug_info:
          type: string
          description: Debug information for the payment.
        relationship:
          type: object
          description: Related data for the payment.
          properties:
            employee:
              type: object
              description: Employee who created or processed the payment.
        payee_original_amount:
          type: number
          format: double
          description: Original amount to payee.
        payee_fee_amount:
          type: number
          format: double
          description: Fee amount charged to payee.
        payee_currency:
          type: string
          description: Payee's currency.
        time_approved:
          type: integer
          example: 1734455015
          description: Unix timestamp of approval.
        time_completed:
          type: integer
          example: 1734455015
          description: Unix timestamp of completion.
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey