Invoices

Prefix: /api/v1/external/invoices

See Overview for authentication, pagination, and errors.

Read-only access to billing Invoice records (header plus line items) and the stored invoice PDF. Invoices are produced by billing runs; this API does not create or edit them.

Picklists (invoiceStatus, invoiceType, paymentStatus, approvalStatus, and similar) and currency are returned as names / ISO codes, not UUIDs.

Endpoint summary

Method	Path
GET	`/invoices`
GET	`/invoices/{invoiceId}`
GET	`/invoices/{invoiceId}/pdf`

List invoices

GET /api/v1/external/invoices?page=0&size=20&q=INV-10&accountId=11111111-1111-1111-1111-111111111111&fromDate=2026-08-01&toDate=2026-08-31
Authorization: Bearer YOUR_API_TOKEN

Query	Description
`page`	0-based page index (default `0`)
`size`	Page size (default 20, max 20)
`q`	Optional search on `invoiceNo`
`accountId`	Optional billing account UUID
`fromDate`	Optional inclusive start of invoice date (`YYYY-MM-DD`)
`toDate`	Optional inclusive end of invoice date (`YYYY-MM-DD`)

Either date bound may be omitted. If both are sent, fromDate must be on or before toDate (400 otherwise). List rows are invoice headers only (no items). Envelope: Overview.

Response 200

{
  "requestId": "req-1",
  "success": true,
  "status": 200,
  "errors": [],
  "data": {
    "content": [
      {
        "__type__": "Invoice",
        "Id": "55555555-5555-5555-5555-555555555555",
        "InvoiceNo": "INV-1001",
        "AccountId": "11111111-1111-1111-1111-111111111111",
        "ApprovalStatus": "fe07e71d-cba4-4316-9c7c-4935c3adec34",
        "ApprovalStatus__r": { "Name": "Approved" }
      }
    ],
    "totalElements": 1,
    "size": 20,
    "number": 0
  }
}

Response 400 when the date range is inverted.

{
  "status": 400,
  "error": "Validation Error",
  "message": "fromDate must be on or before toDate",
  "path": "uri=/api/v1/external/invoices"
}

Get invoice

GET /api/v1/external/invoices/{invoiceId}
Authorization: Bearer YOUR_API_TOKEN

Returns the same PascalCase + __r header row as list, plus nested Items (camelCase invoice-item DTOs). Extra MObject fields on the row are also returned.

Response 200

{
  "requestId": "req-1",
  "success": true,
  "status": 200,
  "errors": [],
  "data": {
    "__type__": "Invoice",
    "Id": "55555555-5555-5555-5555-555555555555",
    "InvoiceNo": "INV-1001",
    "AccountId": "11111111-1111-1111-1111-111111111111",
    "ApprovalStatus": "fe07e71d-cba4-4316-9c7c-4935c3adec34",
    "ApprovalStatus__r": { "Name": "Approved" },
    "Items": [
      {
        "id": "66666666-6666-6666-6666-666666666666",
        "invoiceId": "55555555-5555-5555-5555-555555555555",
        "serviceId": "e6cbd28a-f34c-482e-8da5-34e21dbd5eb7",
        "description": "Usage",
        "volume": 16000,
        "ratePerUnit": 0.0025,
        "amount": 40.0,
        "tax": 4.0,
        "balance": 44.0,
        "chargeType": "Usage",
        "priceMethodType": "QUANTITY",
        "billStartDate": "2026-08-01",
        "billEndDate": "2026-08-31",
        "serviceName": "gpt-4o",
        "serviceCode": "MODEL-GPT-4O",
        "currency": "USD"
      }
    ]
  }
}

Response 404 when the invoice does not exist.

{
  "status": 404,
  "error": "Not Found",
  "message": "Invoice not found",
  "path": "uri=/api/v1/external/invoices/55555555-5555-5555-5555-555555555555"
}

Download invoice PDF

GET /api/v1/external/invoices/{invoiceId}/pdf
Authorization: Bearer YOUR_API_TOKEN

curl -sS -L \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o INV-1001.pdf \
  "https://YOUR_TENANT_HOST/api/v1/external/invoices/55555555-5555-5555-5555-555555555555/pdf"

Response 200 — binary body with PDF headers.

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="INV-1001.pdf"

The PDF is the file already stored for that invoice (from invoice PDF generation).

Response 404 when no PDF has been generated yet.

{
  "status": 404,
  "error": "Not Found",
  "message": "Invoice PDF has not been generated",
  "path": "uri=/api/v1/external/invoices/55555555-5555-5555-5555-555555555555/pdf"
}

Invoices

Invoices

Endpoint summary

List invoices

Get invoice

Download invoice PDF

On this page