Invoices

Create invoices programmatically, send them to clients, and track payment status. Each invoice gets a unique payment URL you can share directly.

Endpoints

GEThttps://api.tryesperworks.com/api/v1/invoicesinvoices:read

List invoices. Supports ?status=, ?client_id=, ?per_page=.

GEThttps://api.tryesperworks.com/api/v1/invoices/:idinvoices:read

Get a single invoice with line items and payments.

POSThttps://api.tryesperworks.com/api/v1/invoicesinvoices:write

Create a draft invoice.

PATCHhttps://api.tryesperworks.com/api/v1/invoices/:idinvoices:write

Update a draft invoice (notes, due_date).

POSThttps://api.tryesperworks.com/api/v1/invoices/:id/sendinvoices:write

Send the invoice to the client by email.

GEThttps://api.tryesperworks.com/api/v1/invoices/:id/payment-statusinvoices:read

Get payment status for an invoice.

DELETEhttps://api.tryesperworks.com/api/v1/invoices/:idinvoices:write

Delete a draft invoice.

Create an invoice

curl -X POST https://api.tryesperworks.com/api/v1/invoices \
  -H "Authorization: Bearer ew_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 42,
    "issue_date": "2026-05-01",
    "due_date": "2026-05-15",
    "currency": "GHS",
    "notes": "Thank you for your business.",
    "items": [
      { "description": "Web design", "quantity": 1, "rate": 2500 },
      { "description": "Hosting setup", "quantity": 1, "rate": 500 }
    ]
  }'

Response

{
  "invoice": {
    "id": 101,
    "invoice_number": "INV-0042",
    "status": "draft",
    "total": 3000,
    "amount_paid": 0,
    "currency": "GHS",
    "issue_date": "2026-05-01",
    "due_date": "2026-05-15",
    "client": { "id": 42, "name": "Kofi Mensah", "email": "kofi@example.com" },
    "items": [
      { "description": "Web design", "quantity": 1, "rate": 2500, "amount": 2500 },
      { "description": "Hosting setup", "quantity": 1, "rate": 500, "amount": 500 }
    ],
    "created_at": "2026-05-01T12:00:00Z"
  },
  "payment_url": "https://tryesperworks.com/invoices/pay/tok_xxxx"
}

The payment_url is a public link you can send to your client. They can pay via Paystack, Flutterwave, or Mobile Money, no EsperWorks account required.

Invoice statuses

Status	Description
`draft`	Created but not yet sent to the client.
`sent`	Emailed to the client.
`viewed`	Client has opened the invoice.
`partial`	Partially paid.
`paid`	Fully paid.
`overdue`	Past due date and unpaid.
`cancelled`	Cancelled by the business.