Invoices

Invoices are itemized bills you send to a buyer with a due date — either to be paid online (charge_automatically) or via the hosted invoice page (send_invoice). The SDK covers the full lifecycle: create, list, send, charge, remind, void, and pull the data you'd need to render the PDF yourself.

Methods

easy.createInvoice(body);                  // POST   /invoices
easy.listInvoices(query?);                 // GET    /invoices
easy.getInvoice(invoiceId);                // GET    /invoices/:id
easy.updateInvoice(invoiceId, body);       // PATCH  /invoices/:id
easy.sendInvoice(invoiceId, body?);        // POST   /invoices/:id/send
easy.payInvoice(invoiceId, body?);         // POST   /invoices/:id/pay
easy.remindInvoice(invoiceId);             // POST   /invoices/:id/remind
easy.voidInvoice(invoiceId);               // POST   /invoices/:id/void
easy.getInvoicePdfData(invoiceId);         // GET    /invoices/:id/pdf

Create

const invoice = await easy.createInvoice({
  to_email: "ada@example.com",
  to_company_name: "Analytical Engines Co.",
  collection_method: "send_invoice",
  currency: "USD",
  due_date: "2026-06-15",
  issue_date: "2026-05-15",
  items: [
    { description: "Consulting (May)", quantity: 20, unit_price: 25000 }, // $250/hr × 20
  ],
  tax_rate: 8.5,                       // percentage
  notes: "Net-30, thanks!",
  terms: "Pay by ACH or card.",
  attach_pdf: true,
});

List with filters

const overdue = await easy.listInvoices({
  status: "OVERDUE",
  collection_method: "send_invoice",
  due_date_to: new Date().toISOString(),
  limit: 100,
});

Send

await easy.sendInvoice(invoice.data.id, {
  cc_recipients: ["billing@example.com"],
  attach_pdf: true,
});

Charge an open invoice

import { randomUUID } from "node:crypto";

await easy.payInvoice(invoice.data.id, {
  instrument_id: paymentInstrumentId, // omit to use the customer's default
  amount: 50000,                      // omit to charge full balance
  idempotency_key: randomUUID(),
});

Remind, void, or void-and-write-off

await easy.remindInvoice(invoiceId);    // sends reminder email
await easy.voidInvoice(invoiceId);      // marks VOID; cannot be undone

Object shape

InvoiceData (subset of the most-touched fields):

Field	Type	Notes
`id` / `invoice_number`	`string \| null`	Number assigned on finalization.
`status`	`InvoiceStatus`	`DRAFT`, `OPEN`, `SENT`, `VIEWED`, `OVERDUE`, `PARTIALLY_PAID`, `PAID`, `UNPAID`, `VOID`, `VOIDED`.
`collection_method`	`"charge_automatically" \| "send_invoice"`
`currency`	`string`
`to_email` / `to_company_name` / `to_contact_name` / `to_address`	various	Recipient.
`subtotal_amount` / `tax_amount` / `discount_amount` / `shipping_amount` / `total_amount`	`number`	Smallest currency unit.
`amount_paid` / `amount_due`	`number`	Running totals.
`due_date` / `issue_date` / `paid_at` / `voided_at` / `last_sent_at` / `last_viewed_at`	`string \| null`	ISO timestamps.
`items`	`InvoiceItem[]`	Line items.
`is_recurring` / `recurrence_interval` / `recurrence_end_date`	various	Recurring invoice config.
`auto_reminders`	`boolean`	Enable scheduled reminders.
`tax_ids` / `custom_fields` / `branding_overrides`	various
`pdf_storage_path`	`string \| null`	Where the rendered PDF lives.

Examples

Recurring monthly invoice

await easy.createInvoice({
  to_email: "ops@example.com",
  collection_method: "send_invoice",
  due_date: "2026-06-30",
  is_recurring: true,
  recurrence_interval: "MONTHLY",
  recurrence_end_date: "2027-05-31",
  recurrence_auto_send: true,
  items: [{ description: "Retainer", quantity: 1, unit_price: 500000 }],
});

Sweep all overdue invoices nightly

const overdue = await easy.listInvoices({ status: "OVERDUE", limit: 100 });
for (const inv of overdue.data) {
  if (inv.collection_method === "send_invoice") {
    await easy.remindInvoice(inv.id);
  } else {
    await easy.payInvoice(inv.id, { idempotency_key: `retry:${inv.id}:${new Date().toISOString().slice(0, 10)}` });
  }
}

Render the PDF yourself

getInvoicePdfData returns a normalized payload (currently typed as Record<string, unknown>) shaped for client-side PDF generation. Pipe it into your renderer of choice:

const { data } = await easy.getInvoicePdfData(invoiceId);
// hand `data` to your PDF template (e.g. react-pdf, puppeteer, weasyprint)

Invoices

On this page