Skip to content

Document Features

A complete guide to all the data you can include in a document — line items, taxes, discounts, shipping, custom fields, payment info, branding, and more. These fields apply to every priced document type, not just invoices (the examples below use invoices for concreteness).

Line Items

Every invoice must have at least one line item:

{
  "line_items": [
    {
      "name": "Web Development",
      "description": "Frontend redesign project",
      "quantity": "10",
      "unit_price": "150.00",
      "unit": "hours",
      "sku": "SVC-WEB-001"
    }
  ]
}
Field Required Description
name Yes Item name displayed on the invoice
description No Additional detail shown below the name
quantity Yes Decimal string (e.g. "2.5")
unit_price Yes Price per unit as decimal string
unit No Unit label (e.g. "hours", "pcs", "kg")
sku No SKU or product code

Taxes

Taxes are applied per line item. Each item can have multiple tax rates.

Exclusive Tax (added on top)

The most common type — tax is added to the item price:

{
  "name": "Platform subscription",
  "quantity": "1",
  "unit_price": "49.00",
  "taxes": [
    { "name": "Sales Tax", "rate": "8.875", "inclusive": false }
  ]
}

Result: Subtotal $49.00 + Tax $4.35 = Total $53.35

Inclusive Tax (already included in price)

Common in EU/UK — the price already includes tax:

{
  "name": "Software License",
  "quantity": "1",
  "unit_price": "120.00",
  "taxes": [
    { "name": "VAT", "rate": "20", "inclusive": true }
  ]
}

Result: Subtotal $100.00 + VAT $20.00 = Total $120.00

Multiple Tax Rates

{
  "taxes": [
    { "name": "State Tax", "rate": "6.25", "inclusive": false },
    { "name": "County Tax", "rate": "1.5", "inclusive": false }
  ]
}

Discounts

Per-Line Discounts

Applied to a specific line item before taxes:

{
  "name": "Annual Plan",
  "quantity": "1",
  "unit_price": "1200.00",
  "discount": {
    "type": "percentage",
    "value": "20",
    "reason": "Annual commitment discount"
  }
}

Gross $1,200 → Discount $240 → Net $960

{
  "name": "Annual Plan",
  "quantity": "1",
  "unit_price": "1200.00",
  "discount": {
    "type": "fixed",
    "value": "200.00",
    "reason": "Coupon SAVE200"
  }
}

Gross $1,200 → Discount $200 → Net $1,000

Document-Level Discounts

Applied to the entire invoice subtotal, after all line items:

{
  "discounts": [
    { "type": "percentage", "value": "5", "reason": "Loyalty discount" },
    { "type": "fixed", "value": "10.00", "reason": "Referral credit" }
  ]
}

Discount ordering

  1. Per-line discounts reduce each line item's gross amount
  2. Document-level discounts are apportioned back across the lines, pro-rata by what each line is taxed on
  3. Taxes are calculated on what remains

Both kinds of discount reduce the taxable amount. Where you write a discount changes nothing about what is owed — 10% off a line and 10% off the invoice produce the same total. A discount granted at the time of supply is excluded from the taxable amount (EU VAT Directive Art. 79, CGST s.15(3)(a)), and the invoice shows the taxable value net of it (CGST Rule 46).

Discounts are bounded

A discount cannot exceed what it discounts: a percentage above 100, a fixed line discount above the line amount, or document discounts above the subtotal are rejected with 422 unprocessable_entity. A discount equal to the amount is fine — 100% off is a real thing. To refund more than an invoice was worth, issue a credit note.

Shipping

Add a shipping charge to the invoice:

{
  "shipping": {
    "description": "Express Delivery",
    "amount": "15.00"
  }
}

By default shipping is added to the total without being taxed.

Taxable shipping

Where transport charged by the supplier forms part of the taxable amount — EU VAT Directive Art. 78, CGST s.15(2)(c) — set taxable:

{
  "shipping": {
    "description": "Express Delivery",
    "amount": "200.00",
    "taxable": true
  }
}

The freight is then apportioned across the line items pro-rata by what each is taxed on, so it picks up the rates the goods carry rather than needing a rate of its own. On a 1,000.00 line at 18%:

taxable Tax Total
false (default) 180.00 — 18% of the goods 1,380.00
true 216.00 — 18% of goods and freight 1,416.00

Why it is not the default

Turning it on changes the total. Invoices already issued without it were sent at the untaxed figure, so the flag is opt-in rather than a behaviour that would silently move historical documents on re-render.

Custom Fields

Add arbitrary key-value pairs displayed on the invoice:

{
  "custom_fields": [
    { "label": "PO Number", "value": "PO-2026-042" },
    { "label": "Project", "value": "Website Redesign" },
    { "label": "Contract", "value": "MSA-2025-001" }
  ]
}

Payment Information

Include payment instructions on the invoice:

{
  "payment": {
    "instructions": "Please pay within 30 days via wire transfer",
    "payment_url": "https://pay.acme.com/inv-001",
    "accepted_methods": ["bank_transfer", "credit_card", "check"],
    "bank_account": {
      "bank_name": "First National Bank",
      "account_name": "Acme Corp",
      "account_number": "1234567890",
      "routing_number": "021000021",
      "swift": "FNBKUS33",
      "iban": "US82FNBK0000001234567890"
    }
  }
}

Branding

Customize the look of your invoice:

{
  "branding": {
    "logo_file_id": "fil_01ABC",
    "primary_color": "#0066CC",
    "accent_color": "#003366",
    "font_family": "Inter",
    "footer_text": "Thank you for choosing Acme Corp!"
  }
}
Field Default Description
logo_file_id — File ID from the Files API
primary_color #111827 Main text and heading color
accent_color #111827 Accent/highlight color
font_family System font Custom font family
footer_text Generated by InvoicePDFs Footer message

Adding a logo

  1. Upload your logo: POST /api/v1/files with the image
  2. Note the returned id (e.g. fil_01ABC)
  3. Pass it as branding.logo_file_id in your invoice data
  4. The logo appears in the top-left of the rendered PDF

Ship To

Add a separate shipping address when it differs from the billing address:

{
  "ship_to": {
    "name": "Warehouse West",
    "address": {
      "line1": "99 Dock Rd",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97201",
      "country": "US"
    }
  }
}

Rich Seller/Buyer Details

Both the seller and buyer support extensive detail:

{
  "seller": {
    "name": "Acme Corp",
    "legal_name": "Acme Corp Inc.",
    "email": "billing@acme.com",
    "phone": "+1-555-123-4567",
    "website": "https://acme.com",
    "tax_id": "US-EIN-12-3456789",
    "registration_number": "REG-2024-00123",
    "address": {
      "line1": "1 Main St",
      "line2": "Suite 200",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "bank_account": {
      "bank_name": "First National Bank",
      "iban": "US82FNBK0000001234567890"
    }
  }
}

Supported Currencies

Invoices support any 3-letter ISO 4217 currency code. These currencies get native symbol formatting in rendered PDFs:

Currency Symbol Example
USD $ $1,500.00
EUR € €1,500.00
GBP £ £1,500.00
JPY ¥ ¥1,500.00
CAD CA$ CA$1,500.00
AUD A$ A$1,500.00
INR ₹ ₹1,500.00
BRL R$ R$1,500.00
CHF CHF CHF 1,500.00
SEK/NOK/DKK kr 1,500.00 kr

Other currencies use the ISO code as prefix (e.g. SGD 1,500.00).