openapi: 3.0.3
info:
  title: Everflow Network API - Billing (Advertiser Invoices)
  description: >
    Endpoints for managing advertiser invoices.
    For billing workflows, see the [Advertiser Invoices guide](https://helpdesk.everflow.io/customer/managing-advertiser-invoices).
  version: 1.0.0
servers:
  - url: https://api.eflow.team/v1
tags:
  - name: Advertiser Billing
paths:
  /networks/billings/advertisers/invoicestable:
    post:
      summary: Find Advertiser Invoices (Advanced)
      tags:
        - Advertiser 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
                  items:
                    type: object
                filters:
                  type: object
                  properties:
                    advertiser_ids:
                      type: array
                      items:
                        type: integer
                      description: Filter by advertiser IDs.
                    invoice_ids:
                      type: array
                      items:
                        type: integer
                      description: Filter by specific invoice IDs.
                    date_from:
                      type: string
                      description: Start date filter (YYYY-MM-DD).
                    date_to:
                      type: string
                      description: End date filter (YYYY-MM-DD).
                    balance_from:
                      type: number
                      format: double
                      description: Minimum balance filter.
                    balance_to:
                      type: number
                      format: double
                      description: Maximum balance filter.
                    status:
                      type: string
                      enum:
                        - paid
                        - unpaid
                        - deleted
                      description: Filter by invoice status.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: "#/components/schemas/AdvertiserInvoice"
                  paging:
                    type: object
                    properties:
                      page:
                        type: integer
                      page_size:
                        type: integer
                      total_count:
                        type: integer
      security:
        - API Key: []
  /networks/billings/advertisers/invoices/{invoiceId}:
    get:
      summary: Get Advertiser Invoice
      tags:
        - Advertiser Billing
      parameters:
        - in: path
          name: invoiceId
          required: true
          schema:
            type: integer
          description: The unique invoice ID.
        - in: query
          name: relationship
          schema:
            type: string
          description: Include related data such as line items.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdvertiserInvoice"
        "404":
          description: Invoice not found.
      security:
        - API Key: []
  /networks/billings/advertisers/invoices:
    post:
      summary: Create Advertiser Invoice
      tags:
        - Advertiser Billing
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_advertiser_id: 13
              status: "unpaid"
              start_time: "2026-01-01"
              end_time: "2026-01-31"
            schema:
              type: object
              required:
                - network_advertiser_id
                - status
                - start_time
                - end_time
              properties:
                network_advertiser_id:
                  type: integer
                  description: The advertiser ID to create the invoice for.
                status:
                  type: string
                  enum:
                    - paid
                    - unpaid
                  description: Initial invoice status.
                start_time:
                  type: string
                  description: Invoice period start date (YYYY-MM-DD).
                end_time:
                  type: string
                  description: Invoice period end date (YYYY-MM-DD).
                public_notes:
                  type: string
                  description: Notes visible to the advertiser.
                internal_notes:
                  type: string
                  description: Internal notes visible only to network users.
                is_hidden_advertiser:
                  type: boolean
                  description: Whether the invoice is hidden from the advertiser.
                payment_terms:
                  type: integer
                  description: Payment terms in days.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdvertiserInvoice"
      security:
        - API Key: []
    patch:
      summary: Batch Update Advertiser Invoices
      tags:
        - Advertiser Billing
      requestBody:
        required: true
        content:
          application/json:
            example:
              network_advertiser_invoice_ids:
                - 1
                - 2
                - 3
              fields:
                - field_type: "status"
                  field_value: "paid"
                  operator: "overwrite"
            schema:
              type: object
              required:
                - network_advertiser_invoice_ids
                - fields
              properties:
                network_advertiser_invoice_ids:
                  type: array
                  items:
                    type: integer
                  description: Array of advertiser 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: []
components:
  schemas:
    AdvertiserInvoice:
      type: object
      properties:
        network_advertiser_invoice_id:
          type: integer
          description: Unique invoice ID.
        network_id:
          type: integer
          description: Network ID.
        network_advertiser_id:
          type: integer
          description: Advertiser ID this invoice belongs to.
        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.
        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.
        public_notes:
          type: string
          description: Notes visible to the advertiser.
        internal_notes:
          type: string
          description: Internal notes visible only to network users.
        is_hidden_advertiser:
          type: boolean
          description: Whether the invoice is hidden from the advertiser.
        payment_terms:
          type: integer
          description: Payment terms in days.
        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 such as line items (when requested).
  securitySchemes:
    API Key:
      description: The Everflow API key generated from the Control Center > Security.
      in: header
      name: X-Eflow-Api-Key
      type: apiKey