Invoices

Outcome: Create, finalize, render, and deliver an invoice.
Prerequisites: An entity and API key; customer and item data can be inline.
You'll use: Entity key, or account key plus entity_id.

Create

Use the standard Create Invoice API for normal invoice creation. It calculates totals and taxes from your line items and applies the regular document lifecycle. The /custom endpoint is only for imports or integrations that must preserve externally calculated totals exactly.

Minimal invoice with inline customer and one line item:

Create minimaltypescript

// title: Minimal invoice
const _invoice = await sdk.invoices.create({
  customer: { name: "Acme Corp" },
  items: [{ name: "Service", quantity: 1, price: 100 }],
});

Or reference saved data:

Create with refstypescript

// title: Invoice with saved references
const _invoice = await sdk.invoices.create({
  customer_id: "cus_abc123",
  items: [
    { item_id: "itm_xyz789", quantity: 5 },
    { name: "Custom service", quantity: 1, price: 250 },
  ],
});

If your rollout needs gross-discount consumer pricing instead of the default B2B flow, see Calculation Modes.

Finalize

Finalize a draft to assign its invoice number. A finalized document can still be updated with version history until it is fiscalized or voided:

Finalizetypescript

// title: Finalize invoice
// Finalize assigns a document number. Fiscalization, when enabled, is a separate lifecycle concern.
const _finalized = await sdk.documents.finalizeDocument(invoice.id);

Or pass is_draft: false when creating to finalize immediately.

Download PDF

Render pdftypescript

// title: Render PDF
const pdf = await sdk.invoices.renderPdf(invoice.id);

// Save to file
fs.writeFileSync("invoice.pdf", pdf);

// Or send as response
res.setHeader("Content-Type", "application/pdf");
res.send(pdf);

Send by Email

Send emailtypescript

// title: Send invoice
await sdk.email.sendEmail({
  document_id: invoice.id,
  to: invoice.customer.email,
  subject: "Your invoice #{document_number}",
  body_text: "Thank you for your business!",
});

Uses the entity’s default email template. See the Email guide for templates, attachments, and verified custom sender setup, or the Email API for request details.

Optional Invoice Configuration

For revenue categorization and recognition over a billing period, see Service-Period Invoices.