> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List invoices

> Returns a list of invoices for the authenticated tenant, with optional accounting export.

```http theme={null}
GET /v1/billing/invoices
```

Returns invoices for your tenant's billing history. Each invoice includes the amount, currency, payment status, and links to download the PDF or receipt.

## Query parameters

<ParamField query="start" type="string">
  Filter invoices created on or after this date (ISO 8601, e.g. `2026-01-01`).
</ParamField>

<ParamField query="end" type="string">
  Filter invoices created on or before this date (ISO 8601, e.g. `2026-06-30`).
</ParamField>

## Export invoices

```http theme={null}
GET /v1/billing/exports/accounting
```

Enterprise tenants can export invoices as CSV or JSON for accounting and reconciliation. The export includes invoice number, status, issue and due dates, amounts, tax, currency, and PO references. If no date range is provided, the export defaults to the last 30 days.

<ParamField query="format" type="string">
  Export format: `csv` or `json`. Defaults to `csv`.
</ParamField>

<ParamField query="from" type="string">
  Start of the date range (`YYYY-MM-DD`, e.g. `2026-01-01`). Defaults to 30 days ago.
</ParamField>

<ParamField query="to" type="string">
  End of the date range (`YYYY-MM-DD`, e.g. `2026-06-30`). Defaults to today.
</ParamField>

## Response

Returns an array of invoice objects.

<ResponseField name="id" type="string">
  Invoice identifier.
</ResponseField>

<ResponseField name="invoice_number" type="string">
  Human-readable invoice number.
</ResponseField>

<ResponseField name="status" type="string">
  Payment status: `paid`, `open`, `void`, or `uncollectible`.
</ResponseField>

<ResponseField name="total" type="integer">
  Total amount in the smallest currency unit (e.g., cents for USD).
</ResponseField>

<ResponseField name="amount" type="integer">
  Amount due in the smallest currency unit.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code (e.g., `usd`, `ngn`).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the invoice was created.
</ResponseField>

<ResponseField name="issued_at" type="string">
  ISO 8601 timestamp when the invoice was finalized and sent.
</ResponseField>

<ResponseField name="due_at" type="string">
  ISO 8601 timestamp for the payment due date.
</ResponseField>

<ResponseField name="full_pdf_url" type="string">
  URL to download the full invoice PDF.
</ResponseField>

<ResponseField name="receipt_url" type="string">
  URL to view the payment receipt (available for paid invoices).
</ResponseField>


## OpenAPI

````yaml mint-openapi.yaml GET /v1/billing/invoices
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks is a universal verification infrastructure for documents,
    credentials, and digital assets.

    This specification defines the canonical API for interacting with Truthlocks
    services.


    ## Base URLs

    - **Production**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Authentication

    - **API Keys**: Use `X-API-Key` header for machine-to-machine operations

    - **Bearer Tokens**: Use `Authorization: Bearer <jwt>` for user-initiated
    operations


    ## Tenant Identity

    In production, tenant identity is derived from the authenticated context
    (API key or JWT).

    The `X-Tenant-ID` header is ignored in production to prevent spoofing.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: Production API
  - url: https://sandbox-api.truthlocks.com
    description: Sandbox Environment
security:
  - APIKey: []
tags:
  - name: Authentication
    description: API key and token management
  - name: Issuers
    description: Issuer registration and trust management
  - name: Keys
    description: Cryptographic key management for issuers
  - name: Attestations
    description: Attestation lifecycle (mint, revoke, supersede)
  - name: Verification
    description: Attestation verification and proof bundles
  - name: Governance
    description: Issuer governance workflows (admin only)
  - name: Identity
    description: Organization, user, and role management
  - name: Audit
    description: Audit event queries
  - name: Platform
    description: Platform administration (super admin only)
  - name: Platform Review
    description: Staff review workflows for issuer applications
  - name: Tenant Console
    description: Tenant profile and lifecycle endpoints
  - name: Health
    description: Service health and readiness endpoints
  - name: Risk
    description: Risk signal ingestion and fraud detection
  - name: Risk Enforcement
    description: Risk enforcement actions — block, challenge, quarantine, and configuration
  - name: Billing
    description: Billing, subscription, and addon management
  - name: Machine Identity
    description: >-
      Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
      trust, witness, compliance, orchestration, and observability
externalDocs:
  description: Transparency read-only API (separate service spec)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/billing/invoices:
    get:
      tags:
        - Billing
      summary: List invoices
      description: Returns a paginated list of invoices for the authenticated tenant.
      operationId: billing.invoices
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
          description: Maximum number of invoices to return
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor
      responses:
        '200':
          description: Invoice list
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        amount:
                          type: number
                        currency:
                          type: string
                        status:
                          type: string
                        created_at:
                          type: string
                  cursor:
                    type: string
                    nullable: true
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Machine-readable error code
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Human-readable error message
        http_status:
          type: integer
          description: HTTP status code
        retry_after_ms:
          type: integer
          description: Milliseconds to wait before retrying (for rate limits)
        details:
          type: object
          description: Additional error context
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for machine-to-machine authentication

````