Invoices API
The Invoices API allows you to create, retrieve, update, delete, and send professional invoices. Invoices can include multiple line items, tax calculations, and custom branding.
The Invoice Object
An invoice represents a billing document sent to a customer. Here's the complete structure:
{
"id": "inv_1234567890",
"document_type": "invoice",
"document_number": "INV-2024-0001",
"status": "draft",
"issue_date": "2024-01-15",
"due_date": "2024-02-14",
"from_details": {
"name": "Your Company",
"company_name": "Your Company Inc.",
"email": "billing@yourcompany.com",
"address_line1": "123 Business St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country_code": "US",
"vat_id": "US123456789"
},
"to_details": {
"name": "John Doe",
"company_name": "Acme Corp",
"email": "john@acme.com",
"address_line1": "456 Client Ave",
"city": "New York",
"state": "NY",
"postal_code": "10001",
"country_code": "US"
},
"line_items": [
{
"id": "li_001",
"description": "Consulting Services",
"quantity": 10,
"unit": "hours",
"unit_price": 150.00,
"tax_rate": 0,
"subtotal": "1500.00",
"total": "1500.00"
}
],
"currency": "USD",
"subtotal": "1500.00",
"discount_amount": "0.00",
"tax_amount": "0.00",
"total": "1500.00",
"amount_paid": "0.00",
"tax_regime": "standard",
"language": "en",
"notes": "Thank you for your business!",
"terms": "Net 30",
"payment_instructions": "Please pay via bank transfer.",
"pdf_url": "https://api.generateinvoice.com/v1/invoices/inv_1234567890/pdf",
"source": "api",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}Endpoints
/v1/invoicesCreate a new invoice. The invoice will be created in draft status unless specified otherwise.
Request Body
| Parameter | Type | Description |
|---|---|---|
document_type* | string | Must be "invoice"Example: "invoice" |
document_number | string | Custom invoice number. Auto-generated if not provided. |
status | string | Initial status: "draft" or "final"Example: "draft" |
issue_date | string | Invoice date (YYYY-MM-DD). Defaults to today. |
due_date | string | Payment due date (YYYY-MM-DD) |
from_details* | object | Your company/sender details |
to_details* | object | Customer/recipient details |
line_items* | array | Array of line items (at least one required) |
currency | string | ISO 4217 currency codeExample: "USD" |
tax_regime | string | Tax regime to apply |
notes | string | Notes to display on invoice |
terms | string | Payment terms |
template_id | string | Custom template ID |
metadata | object | Custom key-value metadata |
/v1/invoicesRetrieve a list of invoices. Results are paginated and sorted by creation date (newest first).
Query Parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1)Example: 1 |
limit | integer | Items per page (default: 20, max: 100)Example: 20 |
status | string | Filter by status: draft, final, sent, paid, void |
issue_date_from | string | Filter by minimum issue date (YYYY-MM-DD) |
issue_date_to | string | Filter by maximum issue date (YYYY-MM-DD) |
search | string | Search in document number and customer name |
sort_by | string | Sort field: created_at, issue_date, due_date, total |
sort_order | string | Sort order: asc or descExample: "desc" |
/v1/invoices/:idRetrieve a single invoice by its ID.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id* | string | The invoice IDExample: "inv_abc123xyz" |
/v1/invoices/:idUpdate an existing invoice. Only draft invoices can be fully updated. Finalized invoices have limited editable fields.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id* | string | The invoice ID |
Request Body
| Parameter | Type | Description |
|---|---|---|
status | string | New status |
due_date | string | Updated due date |
line_items | array | Updated line items (replaces existing) |
notes | string | Updated notes |
amount_paid | number | Record a payment amount |
/v1/invoices/:idDelete an invoice. Only draft invoices can be deleted. Finalized invoices must be voided instead.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id* | string | The invoice ID |
/v1/invoices/:id/sendSend an invoice via email. This will finalize the invoice if it's still in draft status.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id* | string | The invoice ID |
Request Body
| Parameter | Type | Description |
|---|---|---|
to_email* | string | Recipient email address |
cc_emails | array | CC email addresses |
bcc_emails | array | BCC email addresses |
subject | string | Custom email subject |
message | string | Custom email message |
attach_pdf | boolean | Attach PDF (default: true) |
Line Item Object
Each line item in an invoice has the following structure:
| Field | Type | Required | Description |
|---|---|---|---|
description | string | Yes | Item description |
quantity | number | Yes | Quantity of items |
unit_price | number | Yes | Price per unit |
unit | string | No | Unit of measurement (e.g., "hours", "pieces") |
tax_rate | number | No | Tax rate percentage (e.g., 19 for 19%) |
discount | number | No | Discount amount or percentage |
discount_type | string | No | "percentage" or "fixed" |
sku | string | No | Product SKU or code |
Invoice Statuses
| Status | Description | Editable |
|---|---|---|
draft | Invoice is being prepared | Yes |
final | Invoice is finalized and ready to send | Limited |
sent | Invoice has been sent to customer | Limited |
paid | Invoice has been fully paid | No |
void | Invoice has been voided/cancelled | No |
Code Examples
Create and Send an Invoice
const API_KEY = process.env.GENERATEINVOICE_API_KEY;
const BASE_URL = 'https://api.generateinvoice.com/v1';
async function createAndSendInvoice() {
// Create the invoice
const createResponse = await fetch(`${BASE_URL}/invoices`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
document_type: 'invoice',
from_details: {
name: 'Your Company',
email: 'billing@yourcompany.com',
address_line1: '123 Business St',
city: 'San Francisco',
country_code: 'US',
},
to_details: {
name: 'John Doe',
email: 'john@example.com',
company_name: 'Acme Corp',
},
line_items: [
{
description: 'Consulting Services',
quantity: 10,
unit: 'hours',
unit_price: 150.00,
},
],
currency: 'USD',
due_date: '2024-02-14',
}),
});
const { data: invoice } = await createResponse.json();
console.log('Created invoice:', invoice.id);
// Send the invoice
const sendResponse = await fetch(`${BASE_URL}/invoices/${invoice.id}/send`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to_email: 'john@example.com',
message: 'Please find your invoice attached.',
}),
});
const { data: sentInvoice } = await sendResponse.json();
console.log('Invoice sent at:', sentInvoice.sent_at);
}Related Endpoints
- Receipts API - Create payment receipts
- Quotes API - Create quotes that can be converted to invoices
- Credit Notes API - Create refund documents
- Bulk Generation - Create multiple invoices at once