LuniPay Docs

API Reference

Invoices

Invoices are itemized bills you send to a customer. Each one has line items, tax, payment terms, an optional installment plan, and a public hosted URL your customer pays at.

LuniPay renders invoices as a hosted page and a matching PDF. Invoices transition through a state machine — DRAFT → OPEN → PAID (or VOID) — and every transition fires a webhook. Payments against an invoice append to an immutable ledger; the invoice itself stores projections.

The invoice object

idstring

Unique identifier, prefixed with `inv_`.

objectstring

Always `"invoice"`.

livemodeboolean

True if created with a live-mode key.

customer_idstring

Customer this invoice is billed to.

invoice_numberstring

Human-readable number, auto-assigned per organization.

statusstring

Lifecycle state. DRAFT until sent, OPEN once delivered, PAID when fully settled, VOID if cancelled.

Values: DRAFT OPEN PAID VOID UNCOLLECTIBLE

currencystring

Lowercase 3-letter ISO 4217 code.

subtotal_centsinteger

Sum of line items before tax.

tax_rate_bpsinteger

Tax rate in basis points (1500 = 15%).

tax_amount_centsinteger

Computed tax amount.

total_centsinteger

Subtotal + tax. What the customer owes.

amount_paid_centsinteger

Projection over the ledger of payments received.

amount_due_centsinteger

Remaining balance. Zero for PAID invoices.

payment_termsstring

Grace period label shown on the invoice PDF.

Values: due_on_receipt net_7 net_15 net_30 net_60 net_90

due_datestringnullable

ISO date when payment is due.

notesstringnullable

Free-form note shown to the customer.

line_itemsarray

Itemized breakdown. Each item has `description`, `quantity`, `unit_price_cents`, `total_cents`.

installment_enabledboolean

True if the invoice is being paid via an installment plan.

installment_countintegernullable

Number of installments, if enabled.

hosted_invoice_urlstring

Public URL where the customer can view and pay the invoice.

metadataobjectnullable

Up to 20 arbitrary key/value pairs.

sent_atintegernullable

Unix timestamp when the invoice was delivered to the customer.

paid_atintegernullable

Unix timestamp when the invoice was fully paid.

createdinteger

Creation timestamp (unix).

updatedinteger

Last-updated timestamp (unix).

{
  "id": "inv_01JRZK7T9A3BXCZV2QKH5E8RMP",
  "object": "invoice",
  "livemode": false,
  "customer_id": "cus_01JRZK2Q4T9ZS0VCNA3HX7W9EY",
  "invoice_number": "INV-0042",
  "status": "OPEN",
  "currency": "usd",
  "subtotal_cents": 10000,
  "tax_rate_bps": 1500,
  "tax_amount_cents": 1500,
  "total_cents": 11500,
  "amount_paid_cents": 0,
  "amount_due_cents": 11500,
  "payment_terms": "net_30",
  "due_date": "2026-05-14",
  "notes": "Thanks for your business.",
  "line_items": [
    {
      "description": "Consulting — April 2026",
      "quantity": 10,
      "unit_price_cents": 1000,
      "total_cents": 10000
    }
  ],
  "installment_enabled": false,
  "installment_count": null,
  "hosted_invoice_url": "https://lunipay.io/pay/inv_01JRZK7T9A3BXCZV2QKH5E8RMP",
  "metadata": null,
  "sent_at": null,
  "paid_at": null,
  "created": 1713100800,
  "updated": 1713100800
}

Endpoints