Invoices API

The Invoices module handles accounts receivable — creating invoices from orders, sending them to customers, recording payments, and issuing credit notes. PDFs are generated server-side and delivered via email or direct download.

---

Endpoints

Method	Path	Description
GET	/api/invoices	List invoices (paginated)
POST	/api/invoices	Create a standalone invoice
GET	/api/invoices/:id	Get an invoice
PATCH	/api/invoices/:id	Update a draft invoice
DELETE	/api/invoices/:id	Delete a draft invoice
POST	/api/invoices/:id/send	Send invoice to customer by email
POST	/api/invoices/:id/pay	Record a manual payment
POST	/api/invoices/:id/credit-note	Issue a credit note
GET	/api/invoices/:id/pdf	Download PDF (binary)

---

Invoice Status Workflow

draft → sent → partial_paid → paid
                    ↘
                  overdue

Status	Description
draft	Not yet sent to customer
sent	Emailed to customer, awaiting payment
partial_paid	Part payment received
paid	Fully paid
overdue	Past due date, unpaid
cancelled	Voided (credit note issued or manually cancelled)

---

List Invoices

GET /api/invoices?page=1&limit=20&status=sent&contactId=018e...&from=2026-01-01&to=2026-03-31

Query Parameters

Parameter	Type	Description
page	number	Page number
limit	number	Items per page (max: 100)
status	string	Filter by invoice status
contactId	string	Filter by contact UUID
orderId	string	Filter by source order UUID
from	ISO 8601	Invoice date from
to	ISO 8601	Invoice date to
sortBy	string	amount, dueDate, status, createdAt

Response

{
  "data": [
    {
      "id": "018ebbbb-abcd-7000-8000-000000000001",
      "number": "INV/2026/0042",
      "status": "sent",
      "contact": {
        "id": "018e1234-abcd-7000-8000-000000000001",
        "name": "Acme Corporation",
        "email": "[email protected]"
      },
      "orderId": "018eaaaa-abcd-7000-8000-000000000001",
      "lineItems": [
        {
          "description": "ECOSIRE Shopify Connector",
          "quantity": 1,
          "unitPrice": 49900,
          "total": 49900
        }
      ],
      "subtotal": 49900,
      "taxAmount": 0,
      "total": 49900,
      "amountPaid": 0,
      "amountDue": 49900,
      "currency": "usd",
      "invoiceDate": "2026-03-15T00:00:00Z",
      "dueDate": "2026-04-14T00:00:00Z",
      "createdAt": "2026-03-15T10:10:00Z"
    }
  ],
  "meta": { "total": 89, "page": 1, "limit": 20, "totalPages": 5 }
}

---

Create an Invoice

Create a standalone invoice not linked to an order. (Invoices created from orders use POST /orders/:id/invoice — see Orders API.)

POST /api/invoices
Content-Type: application/json
Authorization: Bearer eco_live_...

Request Body

{
  "contactId": "018e1234-abcd-7000-8000-000000000001",
  "lineItems": [
    {
      "description": "Custom Odoo development — March 2026",
      "quantity": 20,
      "unitPrice": 15000
    }
  ],
  "currency": "usd",
  "invoiceDate": "2026-03-20T00:00:00Z",
  "dueDate": "2026-04-19T00:00:00Z",
  "notes": "Payment via bank transfer — see details below."
}

Response: 201 Created with the invoice in draft status.

---

Send Invoice

Emails the invoice PDF to the contact's email address and transitions status to sent.

POST /api/invoices/018ebbbb-abcd-7000-8000-000000000001/send
Content-Type: application/json

{
  "subject": "Invoice INV/2026/0042 from ECOSIRE",
  "message": "Please find your invoice attached. Thank you for your business."
}

Response:

{
  "sent": true,
  "to": "[email protected]",
  "sentAt": "2026-03-20T12:05:00Z"
}

---

Record a Payment

POST /api/invoices/018ebbbb-abcd-7000-8000-000000000001/pay
Content-Type: application/json

{
  "amount": 49900,
  "currency": "usd",
  "paymentDate": "2026-03-22T00:00:00Z",
  "method": "bank_transfer",
  "reference": "WIRE-2026-0042"
}

Response:

{
  "invoiceId": "018ebbbb-abcd-7000-8000-000000000001",
  "status": "paid",
  "amountPaid": 49900,
  "amountDue": 0,
  "paidAt": "2026-03-22T00:00:00Z"
}

---

Issue a Credit Note

POST /api/invoices/018ebbbb-abcd-7000-8000-000000000001/credit-note
Content-Type: application/json

{
  "amount": 49900,
  "reason": "Refund — product not compatible with customer environment"
}

Response: 201 Created with the new credit note document.

---

Download PDF

GET /api/invoices/018ebbbb-abcd-7000-8000-000000000001/pdf
Authorization: Bearer eco_live_...

Returns a binary PDF stream (Content-Type: application/pdf). Save with:

curl -o invoice_042.pdf \
  -H "Authorization: Bearer eco_live_..." \
  https://api.ecosire.com/api/invoices/018ebbbb-abcd-7000-8000-000000000001/pdf

---

Status Codes

Code	Scenario
200	Get, send, pay succeeded
201	Invoice or credit note created
204	Draft invoice deleted
400	Attempting to send or pay a cancelled invoice
404	Invoice not found
422	Payment amount exceeds amount due