Invoices

Invoices allow you to bill customers for goods or services. Create an invoice with line items, send it via email, and track payment status automatically.

Invoice lifecycle

Status flowtext

DRAFT → OPEN → PAID
        ↘ VOID

Create an invoice

POST/invoices

Request body

Parameter	Type	Required	Description
`appId`	`string`	Yes	Your app UUID
`customerAccountId`	`string`	Yes	Customer UUID to bill
`items`	`InvoiceItem[]`	Yes	Line items (min 1)
`currency`	`string`	No	Currency code (default: "USD")
`dueDate`	`string`	No	Due date (ISO 8601)
`memo`	`string`	No	Memo or notes (max 2000)
`taxRateId`	`string`	No	Apply a tax rate
`allowedChains`	`"ALL" \| number[]`	No	Allowed blockchain chain IDs
`allowedTokens`	`"ALL" \| string[]`	No	Allowed token identifiers
`subscriptionId`	`string`	No	Link to a subscription
`periodStart`	`string`	No	Billing period start (ISO 8601)
`periodEnd`	`string`	No	Billing period end (ISO 8601)
`metadata`	`object`	No	Arbitrary key-value metadata

InvoiceItem

Field	Type	Required	Description
`description`	`string`	Yes	Line item description (1–500 chars)
`amount`	`string`	Yes	Price per unit (decimal string)
`quantity`	`number`	No	Quantity (default: 1)
`currency`	`string`	No	Item currency (max 10)
`productPlanId`	`string`	No	Link to product plan
`productPlanPriceId`	`string`	No	Specific price option
`taxRateId`	`string`	No	Per-item tax rate

SDK exampletypescript

const invoice = await noderails.invoices.create({
  customerAccountId: 'cust_abc123',
  currency: 'USD',
  dueDate: '2025-02-01',
  memo: 'January 2025 services',
  items: [
    {
      description: 'API usage — 10,000 requests',
      amount: '49.99',
      quantity: 1,
    },
    {
      description: 'Premium support',
      amount: '19.99',
      quantity: 1,
    },
  ],
});

console.log(invoice.id);     // "inv_abc123"
console.log(invoice.status); // "DRAFT"

List invoices

GET/invoices

Query parameters

Parameter	Type	Description
`appId`	`string`	Filter by app UUID
`status`	`string`	Filter by status (DRAFT, OPEN, PAID, VOID)
`page`	`number`	Page number (default: 1)
`pageSize`	`number`	Items per page (max 100)

SDK exampletypescript

const result = await noderails.invoices.list({
  status: 'OPEN',
  page: 1,
});

for (const inv of result.data) {
  console.log(inv.id, inv.totalAmount, inv.status);
}

Retrieve an invoice

GET/invoices/:id

SDK exampletypescript

const invoice = await noderails.invoices.retrieve('inv_abc123');
console.log(invoice.items);      // InvoiceItem[]
console.log(invoice.totalAmount); // "69.98"

Open an invoice

POST/invoices/:id/open

Transitions a draft invoice to OPEN status, making it payable by the customer.

SDK exampletypescript

const opened = await noderails.invoices.open('inv_abc123');
console.log(opened.status); // "OPEN"

Void an invoice

POST/invoices/:id/void

Voids an invoice, preventing it from being paid.

SDK exampletypescript

const voided = await noderails.invoices.void('inv_abc123');
    console.log(voided.status); // "VOID"

Send an invoice

POST/invoices/:id/send

Sends the invoice to the customer via email. The email includes a link to the hosted payment page.

SDK exampletypescript

const result = await noderails.invoices.send('inv_abc123');
      console.log(result.sent); // true

💡

Auto-open on send

Sending a DRAFT invoice will automatically transition it to OPEN status.

Response object

All responses are wrapped in { "success": true, "data": ... }. List endpoints add pagination.

Invoice object (create)json

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "appId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "customerAccountId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "subscriptionId": null,
    "paymentIntentId": null,
    "invoiceNumber": "INV-0001",
    "status": "DRAFT",
    "subtotal": "69.98",
    "taxAmount": "0",
    "total": "69.98",
    "currency": "USD",
    "taxRateId": null,
    "dueDate": "2025-02-01T00:00:00.000Z",
    "paidAt": null,
    "voidedAt": null,
    "periodStart": null,
    "periodEnd": null,
    "allowedChains": "ALL",
    "allowedTokens": "ALL",
    "memo": "January 2025 services",
    "metadata": {},
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z",
    "items": [
      {
        "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
        "invoiceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "productPlanId": null,
        "productPlanPriceId": null,
        "taxRateId": null,
        "description": "API usage — 10,000 requests",
        "amount": "49.99",
        "currency": "USD",
        "quantity": 1,
        "taxAmount": "0",
        "createdAt": "2025-01-15T10:30:00.000Z"
      }
    ],
    "customerAccount": {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "email": "alice@example.com",
      "name": "Alice Johnson"
    },
    "taxRate": null
  }
}

Invoice fields

idstringUnique invoice UUID

appIdstringApp this invoice belongs to

customerAccountIdstringCustomer being billed

subscriptionIdstring | nullLinked subscription UUID (for recurring invoices)

paymentIntentIdstring | nullAssociated payment intent once payment starts

invoiceNumberstringAuto-generated invoice number (e.g. INV-0001)

statusstringDRAFT, OPEN, PAID, or VOID

subtotalstringTotal before tax as decimal string

taxAmountstringCalculated tax amount

totalstringFinal total (subtotal + tax)

currencystringCurrency code

taxRateIdstring | nullApplied tax rate UUID

dueDatestring | nullISO 8601 due date

paidAtstring | nullISO 8601 payment timestamp

voidedAtstring | nullISO 8601 void timestamp

periodStartstring | nullBilling period start (for subscriptions)

periodEndstring | nullBilling period end (for subscriptions)

allowedChains'ALL' | number[]Permitted blockchain chain IDs

allowedTokens'ALL' | string[]Permitted token identifiers

memostring | nullInvoice notes or memo

metadataobjectArbitrary key-value pairs

createdAtstringISO 8601 creation timestamp

updatedAtstringISO 8601 last-update timestamp

InvoiceItem fields

idstringItem UUID

invoiceIdstringParent invoice UUID

productPlanIdstring | nullLinked product plan UUID

productPlanPriceIdstring | nullLinked price UUID

taxRateIdstring | nullPer-item tax rate UUID

descriptionstringLine item description

amountstringPrice per unit as decimal string

currencystringCurrency code

quantitynumberItem quantity

taxAmountstringCalculated tax for this item

createdAtstringISO 8601 creation timestamp

💡

Endpoint variations

Create includes items, customerAccount, and taxRate. Retrieve adds app, paymentIntent (with transactions), and each item's taxRate. List includes all retrieve relations except app. Open/void include items only. Send returns { "sent": true }.