API Documentation
Navigation

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

POST/v1/invoices

Create a new invoice. The invoice will be created in draft status unless specified otherwise.

Request Body

ParameterTypeDescription
document_type*stringMust be "invoice"Example: "invoice"
document_numberstringCustom invoice number. Auto-generated if not provided.
statusstringInitial status: "draft" or "final"Example: "draft"
issue_datestringInvoice date (YYYY-MM-DD). Defaults to today.
due_datestringPayment due date (YYYY-MM-DD)
from_details*objectYour company/sender details
to_details*objectCustomer/recipient details
line_items*arrayArray of line items (at least one required)
currencystringISO 4217 currency codeExample: "USD"
tax_regimestringTax regime to apply
notesstringNotes to display on invoice
termsstringPayment terms
template_idstringCustom template ID
metadataobjectCustom key-value metadata
GET/v1/invoices

Retrieve a list of invoices. Results are paginated and sorted by creation date (newest first).

Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 1)Example: 1
limitintegerItems per page (default: 20, max: 100)Example: 20
statusstringFilter by status: draft, final, sent, paid, void
issue_date_fromstringFilter by minimum issue date (YYYY-MM-DD)
issue_date_tostringFilter by maximum issue date (YYYY-MM-DD)
searchstringSearch in document number and customer name
sort_bystringSort field: created_at, issue_date, due_date, total
sort_orderstringSort order: asc or descExample: "desc"
GET/v1/invoices/:id

Retrieve a single invoice by its ID.

Path Parameters

ParameterTypeDescription
id*stringThe invoice IDExample: "inv_abc123xyz"
PATCH/v1/invoices/:id

Update an existing invoice. Only draft invoices can be fully updated. Finalized invoices have limited editable fields.

Path Parameters

ParameterTypeDescription
id*stringThe invoice ID

Request Body

ParameterTypeDescription
statusstringNew status
due_datestringUpdated due date
line_itemsarrayUpdated line items (replaces existing)
notesstringUpdated notes
amount_paidnumberRecord a payment amount
DELETE/v1/invoices/:id

Delete an invoice. Only draft invoices can be deleted. Finalized invoices must be voided instead.

Path Parameters

ParameterTypeDescription
id*stringThe invoice ID
POST/v1/invoices/:id/send

Send an invoice via email. This will finalize the invoice if it's still in draft status.

Path Parameters

ParameterTypeDescription
id*stringThe invoice ID

Request Body

ParameterTypeDescription
to_email*stringRecipient email address
cc_emailsarrayCC email addresses
bcc_emailsarrayBCC email addresses
subjectstringCustom email subject
messagestringCustom email message
attach_pdfbooleanAttach PDF (default: true)

Line Item Object

Each line item in an invoice has the following structure:

FieldTypeRequiredDescription
descriptionstringYesItem description
quantitynumberYesQuantity of items
unit_pricenumberYesPrice per unit
unitstringNoUnit of measurement (e.g., "hours", "pieces")
tax_ratenumberNoTax rate percentage (e.g., 19 for 19%)
discountnumberNoDiscount amount or percentage
discount_typestringNo"percentage" or "fixed"
skustringNoProduct SKU or code

Invoice Statuses

StatusDescriptionEditable
draftInvoice is being preparedYes
finalInvoice is finalized and ready to sendLimited
sentInvoice has been sent to customerLimited
paidInvoice has been fully paidNo
voidInvoice has been voided/cancelledNo

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