Invoices API

Create, search, retrieve, and update invoices programmatically.

Create invoice

POST /api/v1/invoices

Scope required: write

Request body

Field	Type	Required	Description
customer_id	string (UUID)	Yes	Customer ID (must belong to your business)
items	array	Yes	At least one line item
invoice_number	string	No	Auto-generated as INV-00001 if not provided
issue_date	string (YYYY-MM-DD)	No	Defaults to today
due_date	string (YYYY-MM-DD)	No
status	string	No	draft, sent, paid, overdue, cancelled. Default: draft
currency	string	No	ISO 4217 code. Default: USD
notes	string	No	Notes visible on the invoice
terms	string	No	Terms and conditions
template_type	string	No	Invoice template. Default: modern

Line item fields

Field	Type	Required	Description
description	string	Yes	Item description
quantity	number	Yes	Quantity
unit_price	number	Yes	Price per unit
tax_rate	number	No	Tax rate as percentage (e.g., 10 for 10%)
product_id	string (UUID)	No	Link to a saved product

Example request

curl -X POST https://onlineinvoicemaker.com/api/v1/invoices \
  -H "Authorization: Bearer oim_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "issue_date": "2026-04-01",
    "due_date": "2026-05-01",
    "currency": "USD",
    "notes": "Thank you for your business!",
    "items": [
      {
        "description": "Website Design",
        "quantity": 1,
        "unit_price": 2500,
        "tax_rate": 10
      },
      {
        "description": "Hosting (12 months)",
        "quantity": 12,
        "unit_price": 29.99
      }
    ]
  }'

Example response

{
  "id": "dad9a150-8bb6-4764-9a22-ac8b83734e24",
  "business_id": "cb21efb1-fa40-434f-a1d3-e17c0bdb9aa6",
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "invoice_number": "INV-00001",
  "issue_date": "2026-04-01",
  "due_date": "2026-05-01",
  "status": "draft",
  "subtotal": 2859.88,
  "tax_amount": 250.00,
  "total": 3109.88,
  "currency": "USD",
  "notes": "Thank you for your business!",
  "terms": null,
  "template_type": "modern",
  "created_at": "2026-04-01T10:30:00.000Z",
  "updated_at": "2026-04-01T10:30:00.000Z",
  "items": [
    {
      "description": "Website Design",
      "quantity": 1,
      "unit_price": 2500,
      "tax_rate": 10,
      "tax_amount": 250.00,
      "amount": 2750.00,
      "product_id": null
    },
    {
      "description": "Hosting (12 months)",
      "quantity": 12,
      "unit_price": 29.99,
      "tax_rate": 0,
      "tax_amount": 0,
      "amount": 359.88,
      "product_id": null
    }
  ]
}

Status: 201 Created

Webhook event

A invoice.created webhook event is emitted with the full invoice data after creation.

---

Search invoices

GET /api/v1/invoices

Scope required: read

Query parameters

Parameter	Type	Description
number	string	Filter by invoice number (partial match, case-insensitive)
status	string	Filter by status
customer_id	string (UUID)	Filter by customer
page	number	Page number. Default: 1
limit	number	Results per page. Default: 25, max: 100

Example request

curl -X GET "https://onlineinvoicemaker.com/api/v1/invoices?status=paid&limit=10" \
  -H "Authorization: Bearer oim_your_api_key"

Example response

{
  "data": [
    {
      "id": "dad9a150-8bb6-4764-9a22-ac8b83734e24",
      "invoice_number": "INV-00001",
      "status": "paid",
      "total": 3109.88,
      "currency": "USD",
      "created_at": "2026-04-01T10:30:00.000Z",
      "invoice_items": [
        {
          "id": "a1b2c3d4",
          "description": "Website Design",
          "quantity": 1,
          "unit_price": 2500,
          "amount": 2750.00
        }
      ],
      "customers": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Acme Corp",
        "email": "billing@acme.com"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "total_pages": 5
  }
}

---

Get invoice

GET /api/v1/invoices/:id

Scope required: read

Returns a single invoice with all line items and customer details.

Example request

curl -X GET https://onlineinvoicemaker.com/api/v1/invoices/dad9a150-8bb6-4764-9a22-ac8b83734e24 \
  -H "Authorization: Bearer oim_your_api_key"

Example response

{
  "id": "dad9a150-8bb6-4764-9a22-ac8b83734e24",
  "invoice_number": "INV-00001",
  "issue_date": "2026-04-01",
  "due_date": "2026-05-01",
  "status": "paid",
  "subtotal": 2859.88,
  "tax_amount": 250.00,
  "total": 3109.88,
  "currency": "USD",
  "invoice_items": [
    {
      "id": "a1b2c3d4",
      "invoice_id": "dad9a150-8bb6-4764-9a22-ac8b83734e24",
      "description": "Website Design",
      "quantity": 1,
      "unit_price": 2500,
      "tax_rate": 10,
      "tax_amount": 250.00,
      "amount": 2750.00
    }
  ],
  "customers": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corp",
    "email": "billing@acme.com"
  }
}

Errors:

• 404 — Invoice not found or does not belong to your business

---

Update invoice

PATCH /api/v1/invoices/:id

Scope required: write

Update an invoice's status or metadata. Only the provided fields are updated.

Request body

Field	Type	Description
status	string	draft, sent, paid, overdue, cancelled
notes	string	Invoice notes
terms	string	Terms and conditions
due_date	string (YYYY-MM-DD)	Due date

Auto-set fields

When you set status to paid, the amount_paid field is automatically set to the invoice total.

Example: Mark as paid

curl -X PATCH https://onlineinvoicemaker.com/api/v1/invoices/dad9a150-8bb6-4764-9a22-ac8b83734e24 \
  -H "Authorization: Bearer oim_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "paid"}'

Webhook events on status change

New Status	Event Emitted
sent	invoice.sent
paid	invoice.paid
cancelled	invoice.cancelled

Errors:

• 400 — No valid fields to update
• 404 — Invoice not found