Invoice Generation API — Typed Line Items & Tax Support

Released in v1.0.13

Calmony Pay now supports a first-class invoice generation API. You can create invoices against a customer with structured line items, track their payment status through a defined lifecycle, and rely on them being auto-generated for subscription billing.

---

Creating an Invoice

Use POST /v1/invoices to create a new invoice. Invoices are created in draft status by default.

Request

POST /v1/invoices
Authorization: Bearer <your_secret_key>
Content-Type: application/json

{
  "customerId": "cus_abc123",
  "lineItems": [
    {
      "description": "Pro Plan — Monthly",
      "amount": 2900,
      "quantity": 1
    },
    {
      "description": "Additional Seat",
      "amount": 500,
      "quantity": 3
    }
  ]
}

Line Item Fields

Field	Type	Description
description	string	Human-readable label for the line item
amount	integer	Unit price in the smallest currency unit (e.g. pence for GBP)
quantity	integer	Number of units for this line item

Response

{
  "id": "inv_xxxxxxxxxxx",
  "customerId": "cus_abc123",
  "status": "draft",
  "amountDue": 4400,
  "amountPaid": 0,
  "currency": "gbp",
  "lineItems": [
    {
      "description": "Pro Plan — Monthly",
      "amount": 2900,
      "quantity": 1
    },
    {
      "description": "Additional Seat",
      "amount": 500,
      "quantity": 3
    }
  ]
}

---

Invoice Lifecycle

Invoices follow a strict, linear status progression:

draft → open → paid
                 └→ void
                 └→ uncollectible

Status	Meaning
draft	Invoice has been created but not yet finalised or sent
open	Invoice has been finalised and is awaiting payment
paid	Payment has been successfully collected
void	Invoice was cancelled before payment was collected
uncollectible	Payment collection failed and the invoice is written off

---

Financial Fields

Every invoice object exposes the following financial tracking fields:

Field	Type	Description
amountDue	integer	Total amount owed, in smallest currency unit
amountPaid	integer	Amount already collected
currency	string	ISO 4217 currency code (e.g. gbp)

---

Invoice IDs

All invoice objects are assigned a unique identifier prefixed with inv_ (e.g. inv_xxxxxxxxxxx). Use this ID when retrieving, updating, or referencing an invoice in other API calls.

---

Subscription Billing Integration

Invoices are automatically created by the subscription billing cron job at the start of each billing cycle. Each automatically generated invoice follows the same lifecycle and structure as a manually created invoice. You do not need to call POST /v1/invoices for subscription renewals — this is handled for you.