> ## 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.

# Accepted usage and monthly invoices

> Read your workspace's accepted usage classifications and monthly invoice settlements.

Requires authentication and returns only the caller's workspace records. This endpoint does not generate, approve, or pay invoices.

`usage` contains up to 500 grouped records. Read `environment`, `classification`, `quantity`, `currency`, and `amount_cents` together. `rated` means the pricing snapshot was preserved at billing acceptance. Sandbox, free plans, consumer plans, approved pilots, and historical mint retries are excluded from business usage charges. Unresolved core pricing or environment evidence holds the month for staff review.

`settlements` contains up to 200 monthly invoice records, newest first. A `DRAFT` is not payable. Staff must review the accepted commercial agreement, tax, and billing country before issue. `automatic_collection` is always `false` for this workflow: issuing an invoice does not charge a saved payment method.

The UTC billing month uses acceptance time. Existing aggregate counters are not retroactively invoiced. Continue using the same mint idempotency key if a mint reports that its billing receipt could not be confirmed.

Amounts ending in `_cents` are integer cents. The separately retrieved invoice uses currency units. For example, `amount_cents: 2500` corresponds to USD 25.00.


## OpenAPI

````yaml mint-openapi.yaml GET /v1/billing/usage-settlements
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: []
  - BearerAuth: []
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: 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/usage-settlements:
    get:
      tags:
        - Billing
      summary: Read accepted usage and monthly invoice settlements
      description: >-
        Returns only your workspace's accepted usage and latest monthly
        settlements. Does not generate invoices or charge payment methods.
      operationId: billing.usageSettlements
      responses:
        '200':
          description: Accepted usage and settlements
          content:
            application/json:
              schema:
                type: object
                properties:
                  settlements:
                    type: array
                    items:
                      type: object
                  usage:
                    type: array
                    items:
                      type: object
                  settlement_mode:
                    type: string
                    enum:
                      - draft_then_staff_review
                  automatic_collection:
                    type: boolean
                    enum:
                      - false
                  usage_limit:
                    type: integer
                    example: 500
                  settlement_limit:
                    type: integer
                    example: 200
        '401':
          description: Authentication required
        '503':
          description: Usage records are unavailable; retry later
      security:
        - APIKey: []
components:
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for machine-to-machine authentication
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT for user-initiated operations

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.