Examples¶

Worked examples of the document data for common scenarios. Invoices are the most common case and are covered in depth first; one example per document type for the other six follows. Set document_type to choose the type — it defaults to invoice. For the type model see Document Types; for every field see Document Features.

Standard Invoice¶

The most common type — a straightforward bill for goods or services.

{
  "number": "INV-2026-001",
  "issue_date": "2026-07-20",
  "due_date": "2026-08-19",
  "currency": "USD",
  "seller": {
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "address": {
      "line1": "1 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    }
  },
  "buyer": {
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "line_items": [
    {
      "name": "Web Development",
      "description": "Frontend redesign — July 2026",
      "quantity": "40",
      "unit_price": "150.00",
      "unit": "hours"
    }
  ]
}

Result: Subtotal $6,000.00 | Total $6,000.00

Service Invoice with Hourly Billing¶

For consulting, freelance, or professional services billed by the hour.

{
  "line_items": [
    {
      "name": "Senior Developer",
      "description": "Architecture review",
      "quantity": "8",
      "unit_price": "200.00",
      "unit": "hours"
    },
    {
      "name": "Junior Developer",
      "description": "Implementation",
      "quantity": "32",
      "unit_price": "120.00",
      "unit": "hours"
    },
    {
      "name": "QA Engineer",
      "description": "Testing and validation",
      "quantity": "12",
      "unit_price": "100.00",
      "unit": "hours"
    }
  ],
  "custom_fields": [
    { "label": "Project", "value": "Website Redesign Phase 2" },
    { "label": "Period", "value": "July 1–31, 2026" }
  ]
}

Product Invoice with SKUs¶

For e-commerce or product-based businesses.

{
  "line_items": [
    {
      "name": "Wireless Keyboard",
      "sku": "KB-WL-001",
      "quantity": "5",
      "unit_price": "79.99",
      "unit": "pcs"
    },
    {
      "name": "USB-C Hub",
      "sku": "HUB-UC-004",
      "quantity": "5",
      "unit_price": "49.99",
      "unit": "pcs"
    },
    {
      "name": "Monitor Stand",
      "sku": "MS-ALU-002",
      "quantity": "3",
      "unit_price": "129.00",
      "unit": "pcs"
    }
  ],
  "shipping": {
    "description": "Ground Shipping",
    "amount": "24.99"
  },
  "ship_to": {
    "name": "Warehouse B",
    "address": {
      "line1": "99 Dock Rd",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97201",
      "country": "US"
    }
  }
}

SaaS / Subscription Invoice¶

For recurring software subscriptions.

{
  "line_items": [
    {
      "name": "Pro Plan — Monthly",
      "description": "July 2026",
      "quantity": "1",
      "unit_price": "99.00"
    },
    {
      "name": "Additional Users",
      "description": "5 users @ $10/user/month",
      "quantity": "5",
      "unit_price": "10.00",
      "unit": "users"
    },
    {
      "name": "API Calls Overage",
      "description": "12,500 extra calls @ $0.002/call",
      "quantity": "12500",
      "unit_price": "0.002",
      "unit": "calls"
    }
  ],
  "custom_fields": [
    { "label": "Subscription ID", "value": "sub_01ABC" },
    { "label": "Billing Period", "value": "2026-07-01 to 2026-07-31" }
  ],
  "payment": {
    "instructions": "Auto-charged to card on file",
    "accepted_methods": ["credit_card"]
  }
}

Invoice with Tax (US Sales Tax)¶

Exclusive tax — added on top of the price.

{
  "line_items": [
    {
      "name": "Consulting Services",
      "quantity": "1",
      "unit_price": "5000.00",
      "taxes": [
        { "name": "NY State Tax", "rate": "4", "inclusive": false },
        { "name": "NYC Local Tax", "rate": "4.5", "inclusive": false }
      ]
    }
  ]
}

Result: Subtotal $5,000.00 | Tax $425.00 | Total $5,425.00

Invoice with VAT (EU Inclusive Tax)¶

Inclusive tax — the price already includes VAT.

{
  "currency": "EUR",
  "seller": {
    "name": "Beispiel GmbH",
    "tax_id": "DE123456789",
    "address": {
      "line1": "Hauptstrasse 1",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "DE"
    }
  },
  "buyer": {
    "name": "Acme France SARL",
    "tax_id": "FR12345678901"
  },
  "line_items": [
    {
      "name": "Software License — Annual",
      "quantity": "1",
      "unit_price": "1200.00",
      "taxes": [
        { "name": "VAT 19%", "rate": "19", "inclusive": true }
      ]
    }
  ]
}

Result: Net (subtotal) EUR 1,008.40 | VAT EUR 191.60 | Total EUR 1,200.00

Invoice with Discounts¶

Per-Line Discount + Document Discount¶

{
  "line_items": [
    {
      "name": "Annual Platform License",
      "quantity": "1",
      "unit_price": "12000.00",
      "discount": {
        "type": "percentage",
        "value": "15",
        "reason": "Annual commitment"
      }
    },
    {
      "name": "Implementation Services",
      "quantity": "20",
      "unit_price": "200.00",
      "unit": "hours"
    }
  ],
  "discounts": [
    {
      "type": "fixed",
      "value": "500.00",
      "reason": "Referral credit"
    }
  ]
}

Result:

Item	Gross	Discount	Net
Annual License	$12,000	-$1,800 (15%)	$10,200
Implementation	$4,000	—	$4,000
Subtotal			$14,200
Document discount		-$500
Total			$13,700

International Invoice with Multiple Currencies¶

{
  "currency": "GBP",
  "seller": {
    "name": "London Tech Ltd",
    "tax_id": "GB123456789",
    "registration_number": "12345678",
    "address": {
      "line1": "10 Downing Code",
      "city": "London",
      "postal_code": "SW1A 1AA",
      "country": "GB"
    },
    "bank_account": {
      "bank_name": "Barclays",
      "account_name": "London Tech Ltd",
      "account_number": "12345678",
      "swift": "BARCGB22",
      "iban": "GB82BARC20035312345678"
    }
  },
  "buyer": {
    "name": "Tokyo Systems K.K.",
    "address": {
      "line1": "1-1-1 Shibuya",
      "city": "Tokyo",
      "postal_code": "150-0002",
      "country": "JP"
    }
  },
  "line_items": [
    {
      "name": "API Integration Consulting",
      "quantity": "5",
      "unit_price": "800.00",
      "unit": "days",
      "taxes": [
        { "name": "VAT", "rate": "20", "inclusive": false }
      ]
    }
  ],
  "payment": {
    "instructions": "Wire transfer in GBP. Reference: INV-2026-042",
    "bank_account": {
      "bank_name": "Barclays",
      "iban": "GB82BARC20035312345678",
      "swift": "BARCGB22"
    }
  }
}

Branded Invoice with Logo¶

{
  "branding": {
    "logo_file_id": "fil_01ABC",
    "primary_color": "#1a365d",
    "accent_color": "#2b6cb0",
    "font_family": "Inter",
    "footer_text": "Thank you for choosing Acme Corp! Questions? billing@acme.com"
  },
  "line_items": [
    { "name": "Premium Support — Q3 2026", "quantity": "1", "unit_price": "2500.00" }
  ]
}

Upload your logo first

Use POST /api/v1/files to upload an image, then reference the returned id as logo_file_id.

Other document types¶

Everything above uses invoices. The same request works for the other six document types — change document_type (and the number prefix). Each is described in full in Document Types; here is one worked example of each.

Pro-forma invoice¶

A preliminary bill sent before the final invoice (deposits, customs, budgeting). Shares the invoice's full payable lifecycle.

{
  "document_type": "proforma",
  "number": "PF-2026-001",
  "currency": "USD",
  "line_items": [
    { "name": "Project Estimate — Phase 1", "quantity": "1", "unit_price": "25000.00" }
  ],
  "notes": [
    { "type": "note", "content": "Pro-forma for budgeting. A final invoice follows on completion." }
  ]
}

Credit note¶

Refunds or adjusts a finalized invoice. Reference the original with source_document_id and explain it with reason; list the credited amounts as normal (positive) line items.

{
  "document_type": "credit_note",
  "number": "CN-2026-004",
  "currency": "USD",
  "source_document_id": "inv_01ABC",
  "reason": "Partial refund for overpayment on INV-2026-015",
  "line_items": [
    { "name": "Refund: Consulting overcharge", "quantity": "1", "unit_price": "350.00" }
  ]
}

Quote¶

A price estimate offered before work is agreed. Simple lifecycle — finalized and sent for approval, not paid. On acceptance, create a separate invoice.

{
  "document_type": "quote",
  "number": "QUO-2026-014",
  "currency": "USD",
  "line_items": [
    { "name": "Website redesign", "quantity": "1", "unit_price": "8000.00" }
  ],
  "custom_fields": [
    { "label": "Valid Until", "value": "2026-09-01" }
  ]
}

Receipt¶

Proof that a payment was received — often issued after an invoice is marked paid.

{
  "document_type": "receipt",
  "number": "RCP-2026-088",
  "currency": "USD",
  "line_items": [
    { "name": "Pro Plan — July 2026", "quantity": "1", "unit_price": "99.00" }
  ],
  "payment": {
    "instructions": "Paid in full — thank you.",
    "accepted_methods": ["credit_card"]
  }
}

Purchase order¶

An order you place with a supplier (the buyer-side counterpart of an invoice).

{
  "document_type": "purchase_order",
  "number": "PO-2026-231",
  "currency": "USD",
  "line_items": [
    { "name": "Standing Desk", "sku": "DSK-STD-004", "quantity": "6", "unit_price": "420.00", "unit": "pcs" }
  ],
  "custom_fields": [
    { "label": "Vendor", "value": "Office Supplies Co." },
    { "label": "Deliver By", "value": "2026-08-20" }
  ]
}

Delivery note¶

A packing slip that travels with a shipment. Line items carry no prices — just what shipped (name, sku, quantity, unit). Totals are zero.

{
  "document_type": "delivery_note",
  "number": "DN-2026-021",
  "currency": "USD",
  "line_items": [
    { "name": "Wireless Keyboard", "sku": "KB-WL-001", "quantity": "5", "unit": "pcs" },
    { "name": "USB-C Hub", "sku": "HUB-UC-004", "quantity": "5", "unit": "pcs" }
  ]
}

Choosing the Right Approach¶

Scenario	Recommended API
One-off PDF generation	Documents API (stateless)
Recurring invoices with tracking	Recurring Invoices API
Preview before creating	`POST /api/v1/documents/calculate`
Template comparison	`POST /api/v1/templates/{id}/preview`