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

# Billing API

> Create Voyant invoices and retrieve provider-issued documents.

## Endpoints

| Method | Path                                   | Description                                         |
| ------ | -------------------------------------- | --------------------------------------------------- |
| POST   | `/v1/billing/invoices`                 | Create a draft invoice with line items.             |
| GET    | `/v1/billing/invoices/:invoiceId`      | Fetch invoice header + lines.                       |
| POST   | `/v1/billing/invoices/:invoiceId/send` | (Reserved) Trigger invoice delivery workflow.       |
| GET    | `/v1/billing/invoices/provider`        | Stream the provider-issued invoice PDF (SmartBill). |

<Info>
  Workspace-scoped API keys are required. Use `billing:write` to create or send invoices and `billing:read` to fetch invoices or provider PDFs. Provider exports rely on encrypted credentials (Google Cloud KMS).
</Info>

## Key concepts

* The create endpoint writes to the Voyant billing tables (`billing.invoices` + `billing.invoice_lines`) and returns the new invoice ID.
* Fetching provider PDFs uses configured accounting integrations (currently SmartBill). Ensure KMS env vars are set (`GCP_SERVICE_ACCOUNT_KEY` + `GCP_KMS_INTEGRATIONS_KEY_NAME`, or fallback KMS in controlled environments).
* Sending invoices is not yet implemented; the endpoint currently returns `501 Not Implemented` to preserve the contract for future workflows.
* All date parameters accept ISO strings; the API stores `issueDate`/`dueDate` as timestamp values when provided.