API Reference: Invoices

Service: Ledgerly Billing API (fictional, api.ledgerly.example) Base URL: https://api.ledgerly.example/v1 Generated from: src/routes/invoices.ts and src/schemas/invoice.ts

The Invoices endpoint lets you create, read, list and void invoices for a customer. All requests need a bearer token in the Authorization header. All amounts are integers in the smallest currency unit (cents, paise).

Authentication

Authorization: Bearer <api_key>

Requests without a valid key return 401 unauthorized.

The invoice object

Field	Type	Description
`id`	string	Unique ID, prefixed `inv_`
`customer_id`	string	The customer this invoice belongs to
`status`	string	`draft`, `open`, `paid` or `void`
`currency`	string	Three-letter ISO code, lowercase
`line_items`	array	Each item has `description`, `quantity`, `unit_amount`
`total`	integer	Sum of line items, computed by the server
`due_date`	string	ISO 8601 date
`created_at`	string	ISO 8601 timestamp

Create an invoice

POST /invoices

Request body:

{
  "customer_id": "cus_8f2k1",
  "currency": "usd",
  "due_date": "2026-11-30",
  "line_items": [
    { "description": "Pro plan, November", "quantity": 1, "unit_amount": 4900 }
  ]
}

Returns 201 with the invoice object in draft status. total is computed from line_items; any total you send is ignored.

Retrieve an invoice

GET /invoices/{id}

Returns 200 with the invoice object, or 404 not_found if the ID does not exist or belongs to another account.

List invoices

GET /invoices

Query param	Type	Description
`customer_id`	string	Filter by customer
`status`	string	Filter by status
`limit`	integer	1 to 100, default 20
`starting_after`	string	Invoice ID to start after, for pagination

Response:

{ "data": [ /* invoice objects */ ], "has_more": true }

Results are sorted by created_at, newest first.

Finalize an invoice

POST /invoices/{id}/finalize

Moves a draft invoice to open and locks its line items. Returns 409 invalid_state if the invoice is not a draft.

Void an invoice

POST /invoices/{id}/void

Marks an open invoice as void. Paid invoices cannot be voided; issue a refund instead. Returns 409 invalid_state otherwise.

Errors

All errors share one shape:

{ "error": { "code": "validation_error", "message": "line_items must not be empty", "field": "line_items" } }

Status	Code	When
400	`validation_error`	Body fails schema validation
401	`unauthorized`	Missing or bad API key
404	`not_found`	Invoice not found
409	`invalid_state`	Action not allowed in the current status
429	`rate_limited`	More than 100 requests per minute per key

Idempotency

Send an Idempotency-Key header on POST requests. Repeating a request with the same key within 24 hours returns the original response instead of creating a second invoice.