Logo
Sign Up

Invoices API

Create and list invoices; read, update, and delete by id; list invoice items (read-only).

Invoices API

Overview

The Invoices API provides endpoints to manage invoices. Use the base route to list and create invoices. Use the id route to read, update, or delete a specific invoice. Invoice items are exposed as a read-only list under a nested route.

Base path: /api/v1/invoices

Authentication

All endpoints require authentication. Include a valid Bearer token in the Authorization header: Authorization: Bearer <access_token>.

Response Envelope

{
  "success": true,
  "message": "optional human readable message",
  "data": {},
  "count": 1,
  "error": "error text"
}

Account scoping

All operations are scoped by accountId (UUID). For list/read/delete, provide it as a query parameter. For create/update, include it in the request body.

Endpoints

List invoices

GET /api/v1/invoices

Query parameters:

  • accountId (uuid, required)
  • page, limit (pagination)
  • query (text search)
  • sortBy, sortOrder

Response 200 — data is an array of invoices with count for pagination.

Create invoice

POST /api/v1/invoices

Body (JSON):

  • accountId (uuid, required)
  • Other invoice fields as supported (e.g., customer_id, issue_date, due_date, status, notes) — subject to schema

Response 201 — created invoice object in data.

Errors

  • 400 Bad Request — invalid body
  • 401 Unauthorized

Get invoice

GET /api/v1/invoices/:id

Path parameters:

  • id (integer)

Query parameters:

  • accountId (uuid, required)

Response 200 — invoice object in data.

Errors

  • 400 Bad Request — invalid id or missing accountId
  • 401 Unauthorized
  • 403 Forbidden — invoice does not belong to the requested organization

Update invoice

PUT /api/v1/invoices/:id

Path parameters:

  • id (integer)

Body (JSON):

  • accountId (uuid, required)
  • Mutable invoice fields (e.g., status, notes, dates)

Response 200 — updated invoice object in data.

Errors

  • 400 Bad Request — invalid body or id
  • 401 Unauthorized
  • 403 Forbidden — invoice does not belong to the requested organization

Delete invoice

DELETE /api/v1/invoices/:id

Path parameters:

  • id (integer)

Query parameters:

  • accountId (uuid, required)

Response 204 / success envelope with no content.

Errors

  • 400 Bad Request — invalid id or missing accountId
  • 401 Unauthorized
  • 403 Forbidden — invoice does not belong to the requested organization

List invoice items (read-only)

GET /api/v1/invoices/:id/items

Path parameters:

  • id (integer) — invoice id

Query parameters:

  • page, limit, query, sortBy, sortOrder (optional pagination & filtering)
  • Note: accountId scoping is enforced server-side by ownership of the parent invoice

Response 200 — array of invoice line items in data with count.

Notes

  • This route is read-only. Create, update, or delete of invoice items is not supported at this endpoint.

Notes

  • All endpoints use a consistent response envelope as shown above.
  • Sorting and pagination follow the shared list conventions used across the API.