Hlix Client Invoices API

openapi: 3.2.0
info:
  description: Explore the Hlix API for projects, agent teams, and delivery workflows. Authenticate with `x-api-key` and select a Workspace with `X-Organization-Id`. Session-only operations require a signed-in user session. Authentication setup.
  title: reference Client Invoices API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- name: client-invoices
paths:
  /v1/api/client-billing/invoices:
    get:
      operationId: listClientInvoices
      parameters:
      - description: Only this customer's invoices.
        in: query
        name: clientAccountId
        required: false
        schema:
          type: string
      - description: One of `draft`, `final`, `void`, `paid`.
        in: query
        name: status
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/ClientPortal'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ClientInvoice'
                type: array
          description: Invoice headers, newest first. `lines` is empty on this projection — read one invoice to get them.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a `client` collaborator. Invoices are agency-only, reads included.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: List invoices
      tags:
      - client-invoices
    post:
      operationId: createClientInvoiceDraft
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceDraft'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvoice'
          description: The draft, with its lines snapshotted from the ledger and its totals computed once and stored.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a `client` collaborator. Invoices are agency-only, reads included.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: A named billable or the client account is not this workspace's.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'The set cannot be invoiced: it spans two customers or two currencies, a charge nets to zero, a tax class has no rate, a correction''s charge was never invoiced, or the total would exceed what an invoice can represent. The message names which.'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: A database constraint refused the draft.
      summary: Assemble a draft invoice from billables
      tags:
      - client-invoices
  /v1/api/client-billing/invoices/{id}:
    get:
      operationId: getClientInvoice
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/ClientPortal'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvoice'
          description: The invoice and every line it was built from.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a `client` collaborator. Invoices are agency-only, reads included.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such invoice in this workspace. Never a 403 — 'forbidden' would confirm that an invoice exists for a customer the caller was never shown.
      summary: Get one invoice with its lines
      tags:
      - client-invoices
  /v1/api/client-billing/invoices/{id}/issue:
    post:
      operationId: issueClientInvoice
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueInvoice'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvoice'
          description: The issued invoice. `invoiceNumber` and `invoiceSequence` are assigned by the database at this moment and are gapless per workspace.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a `client` collaborator. Invoices are agency-only, reads included.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such invoice in this workspace. Never a 403 — 'forbidden' would confirm that an invoice exists for a customer the caller was never shown.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'Not issuable: already issued, no lines, the header does not reconcile with its lines, a charge on it is already invoiced, or a correction of one is missing from it.'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: A database constraint refused the issue.
      summary: Issue a draft, assigning its number
      tags:
      - client-invoices
  /v1/api/client-billing/invoices/{id}/logo:
    get:
      operationId: getClientInvoiceLogo
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/ClientPortal'
      responses:
        '200':
          content:
            image/png:
              schema:
                format: binary
                type: string
          description: 'The agency logo frozen when the invoice was issued. `Content-Type` matches the format recorded on the invoice, with `X-Content-Type-Options: nosniff`.'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a `client` collaborator. Invoices are agency-only, reads included.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such invoice, or it carries no logo.
      summary: Download the logo frozen onto this invoice
      tags:
      - client-invoices
  /v1/api/client-billing/invoices/{id}/pay:
    post:
      operationId: payClientInvoice
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayInvoice'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvoice'
          description: The invoice settled through an audited out-of-band payment recorded by an agency member. This is separate from provider-verified payment. Any open hosted checkout is cancelled to prevent a second payment through the provider.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a `client` collaborator. Invoices are agency-only, reads included.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such invoice in this workspace. Never a 403 — 'forbidden' would confirm that an invoice exists for a customer the caller was never shown.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Only an issued, unpaid invoice can be settled.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: A database constraint refused the payment.
      summary: Record an out-of-band settlement (bank transfer, cheque)
      tags:
      - client-invoices
  /v1/api/client-billing/invoices/{id}/payment-link:
    post:
      operationId: createClientInvoicePaymentLink
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/ClientPortal'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentLink'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientPaymentLink'
          description: A provider-hosted checkout URL and its payment reference. Payment details are entered on the provider's page and are not returned by this endpoint. Creating a checkout does not mark the invoice paid. Provider payments settle only after a signed webhook is reconciled against the invoice ID, amount and currency. An agency member can separately record an audited out-of-band settlement through `POST /v1/api/client-billing/invoices/{id}/pay`.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a `client` collaborator attempting something other than reading or paying its own invoice.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such invoice in this workspace. Never a 403 — 'forbidden' would confirm that an invoice exists for a customer the caller was never shown.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'Not payable: the invoice is a draft, void or already paid, it already has a checkout open with a different provider, or its total is above what the provider will take in one payment.'
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No payment provider is connected for this deployment. The invoice can still be issued, sent and paid outside hlix.
      summary: Open a provider-hosted checkout for an issued invoice
      tags:
      - client-invoices
  /v1/api/client-billing/invoices/{id}/pdf:
    get:
      operationId: getClientInvoicePdf
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/ClientPortal'
      responses:
        '200':
          content:
            application/pdf:
              schema:
                format: binary
                type: string
          description: The rendered invoice, every line included.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a `client` collaborator. Invoices are agency-only, reads included.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such invoice in this workspace. Never a 403 — 'forbidden' would confirm that an invoice exists for a customer the caller was never shown.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The invoice is a draft, or its stored totals no longer reconcile with its stored lines. Rendering a document that does not add up is refused rather than attempted.
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The invoice is valid but this renderer cannot encode it — a party name or line description outside Latin-1. Retrying will not help; read the invoice through `getClientInvoice` instead.
      summary: Download the invoice as a PDF
      tags:
      - client-invoices
  /v1/api/client-billing/invoices/{id}/void:
    post:
      operationId: voidClientInvoice
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoidInvoice'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInvoice'
          description: The voided invoice. An issued invoice retains its number. To correct it, issue a replacement invoice referencing the original.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a `client` collaborator. Invoices are agency-only, reads included.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such invoice in this workspace. Never a 403 — 'forbidden' would confirm that an invoice exists for a customer the caller was never shown.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The invoice is already void.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: A database constraint refused the void.
      summary: Withdraw an invoice, or discard a draft
      tags:
      - client-invoices
components:
  schemas:
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    ClientPaymentLink:
      properties:
        checkoutUrl:
          type: string
        provider:
          type: string
        providerReference:
          type: string
      required:
      - provider
      - providerReference
      - checkoutUrl
      type: object
    IssueInvoice:
      additionalProperties: false
      properties: {}
      type: object
    CreateInvoiceDraft:
      additionalProperties: false
      properties:
        billableIds:
          items:
            minLength: 1
            type: string
          maxItems: 500
          minItems: 1
          type: array
        buyerAddress:
          maxLength: 500
          minLength: 1
          type: string
        buyerBillingEmail:
          anyOf:
          - format: email
            maxLength: 320
            pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
            type: string
          - type: 'null'
        buyerLegalName:
          maxLength: 200
          minLength: 1
          type: string
        dueAt:
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          type: string
        paymentTerms:
          maxLength: 200
          minLength: 1
          type: string
        replacesInvoiceId:
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
        sellerAddress:
          maxLength: 500
          minLength: 1
          type: string
        sellerLegalName:
          maxLength: 200
          minLength: 1
          type: string
        taxRatesBps:
          additionalProperties: false
          default: {}
          properties:
            reduced:
              maximum: 10000
              minimum: 0
              type: integer
            standard:
              maximum: 10000
              minimum: 0
              type: integer
          type: object
      required:
      - billableIds
      - buyerAddress
      - dueAt
      type: object
    PayInvoice:
      additionalProperties: false
      properties: {}
      type: object
    VoidInvoice:
      additionalProperties: false
      properties:
        reason:
          maxLength: 500
          minLength: 1
          type: string
      required:
      - reason
      type: object
    PaymentLink:
      additionalProperties: false
      properties:
        successUrl:
          format: uri
          maxLength: 2000
          type: string
      type: object
    ValidationError:
      properties:
        error:
          properties:
            message:
              type: string
            name:
              type: string
          required:
          - name
          - message
          type: object
        success:
          const: false
          type: boolean
      required:
      - success
      - error
      type: object
    ClientInvoice:
      properties:
        buyerAddress:
          type:
          - string
          - 'null'
        buyerBillingEmail:
          type:
          - string
          - 'null'
        buyerLegalName:
          type:
          - string
          - 'null'
        clientAccountId:
          type: string
        collectorLegalName:
          type:
          - string
          - 'null'
        createdAt:
          type: string
        createdBy:
          type: string
        currency:
          type: string
        dueAt:
          type:
          - string
          - 'null'
        id:
          type: string
        invoiceFooter:
          type:
          - string
          - 'null'
        invoiceNumber:
          type:
          - string
          - 'null'
        invoiceSequence:
          type:
          - number
          - 'null'
        issuedAt:
          type:
          - string
          - 'null'
        lines:
          items:
            properties:
              amountMicros:
                format: int64
                maximum: 9007199254740991
                minimum: -9007199254740991
                type: integer
              billableId:
                type: string
              createdAt:
                type: string
              description:
                type: string
              id:
                type: string
              invoiceId:
                type: string
              organizationId:
                type: string
              position:
                type: number
              quantity:
                type: string
              taxClass:
                enum:
                - standard
                - reduced
                - zero
                - exempt
                - reverse_charge
                type: string
              taxMicros:
                format: int64
                maximum: 9007199254740991
                minimum: -9007199254740991
                type: integer
              taxRateBps:
                type: number
              unit:
                type: string
              unitPriceMicros:
                format: int64
                maximum: 9007199254740991
                minimum: -9007199254740991
                type: integer
            required:
            - id
            - organizationId
            - invoiceId
            - billableId
            - description
            - quantity
            - unit
            - unitPriceMicros
            - amountMicros
            - taxClass
            - taxRateBps
            - taxMicros
            - position
            - createdAt
            type: object
          type: array
        minorUnitExponent:
          type: number
        organizationId:
          type: string
        paidAt:
          type:
          - string
          - 'null'
        paymentDescriptor:
          type:
          - string
          - 'null'
        paymentProvider:
          type:
          - string
          - 'null'
        paymentProviderReference:
          type:
          - string
          - 'null'
        paymentTerms:
          type:
          - string
          - 'null'
        replacesInvoiceId:
          type:
          - string
          - 'null'
        sellerAddress:
          type:
          - string
          - 'null'
        sellerBrandColor:
          type:
          - string
          - 'null'
        sellerContactEmail:
          type:
          - string
          - 'null'
        sellerLegalName:
          type:
          - string
          - 'null'
        sellerLogoMediaType:
          type:
          - string
          - 'null'
        sellerTaxId:
          type:
          - string
          - 'null'
        status:
          enum:
          - draft
          - final
          - void
          - paid
          type: string
        subtotalMicros:
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        taxMicros:
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        totalMicros:
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        totalMinorUnits:
          type: number
        voidReason:
          type:
          - string
          - 'null'
        voidedAt:
          type:
          - string
          - 'null'
      required:
      - id
      - organizationId
      - clientAccountId
      - status
      - invoiceNumber
      - invoiceSequence
      - currency
      - replacesInvoiceId
      - paymentProvider
      - paymentProviderReference
      - sellerLegalName
      - sellerAddress
      - sellerTaxId
      - sellerContactEmail
      - sellerLogoMediaType
      - sellerBrandColor
      - invoiceFooter
      - collectorLegalName
      - paymentDescriptor
      - buyerLegalName
      - buyerAddress
      - buyerBillingEmail
      - paymentTerms
      - dueAt
      - subtotalMicros
      - taxMicros
      - totalMicros
      - minorUnitExponent
      - totalMinorUnits
      - issuedAt
      - paidAt
      - voidedAt
      - voidReason
      - createdBy
      - createdAt
      - lines
      type: object
  parameters:
    ClientPortal:
      description: The agency Workspace ID for a signed-in client's portal requests. A verified user session and portal membership are required; API keys cannot authenticate portal access. This header does not grant agency administration access.
      in: header
      name: X-Client-Portal
      required: false
      schema:
        type: string
    OrganizationId:
      description: The workspace (organization) to act in. Omitted, the session's active organization is used.
      in: header
      name: X-Organization-Id
      required: false
      schema:
        type: string
      example: YOUR_WORKSPACE_ID
  securitySchemes:
    apiKey:
      description: An API key issued through `/v1/api/auth/api-key/*`. Browser clients can use their session cookie instead.
      in: header
      name: x-api-key
      type: apiKey
    sessionCookie:
      description: The complete session Cookie header issued by sign-in at the selected API host. Cookie names vary by hosting region and environment; preserve the issued name and value. Browsers send these HTTP-only cookies automatically. Session-only operations require this user session and do not accept an API key.
      in: header
      name: Cookie
      type: apiKey