Skip to main content

​
Invoice

The Invoice interface represents a complete invoice document with customer information, line items, and metadata.
​
id
string
required
Unique identifier for the invoice
​
invoiceNumber
string
required
Human-readable invoice number (e.g., “INV-001”)
​
date
string
required
Invoice issue date in ISO 8601 format
​
dueDate
string
required
Payment due date in ISO 8601 format
​
status
InvoiceStatus
required
Current status of the invoice. One of:
  • draft - Invoice is being prepared
  • sent - Invoice has been sent to customer
  • paid - Payment has been received
  • cancelled - Invoice has been cancelled
​
customer
Customer
required
​
items
InvoiceItem[]
required
​
notes
string
Optional notes or terms to display on the invoice
​
taxRate
number
Optional global tax rate as a percentage (e.g., 10 for 10%)
​
currency
string
required
Three-letter ISO 4217 currency code (e.g., “USD”, “EUR”, “GBP”)
​
createdAt
string
required
Timestamp when the invoice was created in ISO 8601 format
​
updatedAt
string
required
Timestamp when the invoice was last updated in ISO 8601 format

​
TypeScript definition

export type InvoiceStatus = "draft" | "sent" | "paid" | "cancelled";

export interface Invoice {
  id: string;
  invoiceNumber: string;
  date: string;
  dueDate: string;
  status: InvoiceStatus;
  customer: Customer;
  items: InvoiceItem[];
  notes?: string;
  taxRate?: number;
  currency: string;
  createdAt: string;
  updatedAt: string;
}

​
Example

const invoice: Invoice = {
  id: "inv_123",
  invoiceNumber: "INV-2026-001",
  date: "2026-03-03T00:00:00Z",
  dueDate: "2026-04-03T00:00:00Z",
  status: "sent",
  customer: {
    id: "cust_456",
    name: "Acme Corporation",
    email: "[email protected]",
    address: "123 Business St",
    city: "San Francisco",
    state: "CA",
    zipCode: "94105",
    country: "United States"
  },
  items: [
    {
      id: "item_1",
      description: "Web Development Services",
      quantity: 40,
      rate: 150,
      taxRate: 10
    },
    {
      id: "item_2",
      description: "Design Consultation",
      quantity: 8,
      rate: 200,
      discount: 5
    }
  ],
  notes: "Payment due within 30 days. Thank you for your business!",
  currency: "USD",
  createdAt: "2026-03-03T10:00:00Z",
  updatedAt: "2026-03-03T10:00:00Z"
};

​
InvoiceItem

The InvoiceItem interface represents a single line item on an invoice.
​
id
string
required
Unique identifier for the line item
​
description
string
required
Description of the product or service
​
quantity
number
required
Quantity of items or hours worked
​
rate
number
required
Price per unit in the invoice’s currency
​
discount
number
Optional discount percentage (e.g., 5 for 5% off)
​
taxRate
number
Optional tax rate specific to this item as a percentage (e.g., 10 for 10%)

​
TypeScript definition

export interface InvoiceItem {
  id: string;
  description: string;
  quantity: number;
  rate: number;
  discount?: number;
  taxRate?: number;
}

​
Example

const item: InvoiceItem = {
  id: "item_789",
  description: "Premium Support Package",
  quantity: 1,
  rate: 999,
  discount: 10,
  taxRate: 8.5
};

​
Calculations

Line item calculations are performed as follows:
  1. Line total = quantity × rate
  2. After discount = Line total × (1 - discount / 100)
  3. Tax amount = After discount × (taxRate / 100)
  4. Final amount = After discount + Tax amount

Build docs developers (and LLMs) love

Get started for freeTalk to us