Invoices API

Use the Invoices API to create and manage billing records for customers.

Invoice object

Field	Type	Description
id	string	Invoice ID with the inv_ prefix.
invoice_number	string	Human-readable invoice number.
customer_id	string	Customer associated with the invoice.
status	string	draft, pending, partially_paid, paid, overdue, or cancelled.
currency	string	ISO 4217 currency code.
subtotal	integer	Sum before tax and discount.
tax	integer	Tax amount.
discount	integer	Discount amount.
total	integer	Final invoice total.
amount_paid	integer	Completed payment total.
amount_due	integer	Remaining balance.
issue_date	string	YYYY-MM-DD.
due_date	string	YYYY-MM-DD.
notes	string | null	Optional notes.
items	array	Invoice line items.
created_at	string	ISO 8601 timestamp.
updated_at	string	ISO 8601 timestamp.

List invoices

GET /invoices

Supported query parameters: page, limit, status, customer_id, from, to, sort, order.

curl "https://api.cedius.app/v1/invoices?status=pending&customer_id=cus_4d7c21"   -H "Authorization: Bearer cedius_test_sk_example"

Create an invoice

POST /invoices

Required: customer_id, items, due_date.

Each item requires description, quantity, unit_price.

curl -X POST https://api.cedius.app/v1/invoices   -H "Authorization: Bearer cedius_test_sk_example"   -H "Content-Type: application/json"   -d '{
    "customer_id": "cus_4d7c21",
    "due_date": "2026-09-20",
    "tax": 11250,
    "items": [
      {
        "description": "Website maintenance",
        "quantity": 1,
        "unit_price": 150000
      }
    ]
  }'

201 Created

{
  "data": {
    "id": "inv_91ac20",
    "invoice_number": "INV-2026-0042",
    "customer_id": "cus_4d7c21",
    "status": "draft",
    "currency": "NGN",
    "subtotal": 150000,
    "tax": 11250,
    "discount": 0,
    "total": 161250,
    "amount_paid": 0,
    "amount_due": 161250,
    "issue_date": "2026-09-09",
    "due_date": "2026-09-20",
    "items": [
      {
        "id": "itm_21fd91",
        "description": "Website maintenance",
        "quantity": 1,
        "unit_price": 150000,
        "total": 150000
      }
    ],
    "created_at": "2026-09-09T12:00:00Z",
    "updated_at": "2026-09-09T12:00:00Z"
  }
}

Retrieve an invoice

GET /invoices/{invoice_id}

Returns 200 OK or 404 resource_not_found.

Update an invoice

PATCH /invoices/{invoice_id}

Draft and pending invoices may update due_date, notes, items, tax, discount, and status.

Paid invoices cannot be freely edited. Invalid state transitions return 409 Conflict.

Delete an invoice

DELETE /invoices/{invoice_id}

Deletion is allowed only for draft or cancelled invoices.

Successful deletion returns 204 No Content.