Logo
Sign Up

Downstream Bills API

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

Downstream Bills API

Overview

The Downstream Bills 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 account_id (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:

  • account_id (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):

  • account_id (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:

  • account_id (uuid, required)

Response 200 — invoice object in data.

Errors

  • 400 Bad Request — invalid id or missing account_id
  • 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):

  • account_id (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:

  • account_id (uuid, required)

Response 204 / success envelope with no content.

Errors

  • 400 Bad Request — invalid id or missing account_id
  • 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: account_id 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.