BuildInvoice API

Generate professional PDF invoices from structured JSON with a single API call. No signup forms, no dashboard — just a clean REST endpoint.

⚡ Quick Start — Invoice in 30 Seconds

1. Get an API key

curl -X POST https://buildinvoice.co/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

2. Generate your first invoice

curl -X POST https://buildinvoice.co/api/v1/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: binv_YOUR_KEY_HERE" \
  -d '{
    "from": { "name": "Acme Corp" },
    "to": { "name": "Jane Smith" },
    "items": [
      { "description": "Website Design", "quantity": 1, "rate": 2500 }
    ]
  }'

3. Response

{
  "success": true,
  "pdf": "JVBERi0xLjM...",
  "pages": 1,
  "sizeBytes": 18432,
  "invoice_number": null,
  "totals": {
    "subtotal": 2500.00,
    "tax": 0,
    "discount": 0,
    "total": 2500.00
  },
  "watermark": true,
  "template": "modern"
}

Decode the pdf field from base64 to get your PDF file. That's it.

📡 Endpoints

📋 Request Schema — /generate

from (required)

Field	Type	Required	Description
name	string	✅	Your company or name
address	string	—	Street address, city, state
email	string	—	Contact email
phone	string	—	Phone number
logo	string	—	URL to logo image (Starter+ only)

to (required)

Field	Type	Required	Description
name	string	✅	Client / recipient name
address	string	—	Client address
email	string	—	Client email

items (required)

Field	Type	Required	Description
description	string	✅	Line item description
quantity	number	—	Quantity (default: 1)
rate	number	✅	Unit price

invoice (optional)

Field	Type	Default	Description
number	string	"INV-001"	Invoice number
date	string	—	Invoice date (YYYY-MM-DD)
due_date	string	—	Payment due date
currency	string	—	Currency name (display only)

Other fields

Field	Type	Default	Description
tax_rate	number	0	Tax percentage (e.g., 8.25 for 8.25%)
discount	number	0	Flat discount amount in dollars
notes	string	—	Notes shown at bottom of invoice
terms	string	—	Terms & conditions text

options (optional)

Field	Type	Default	Description
template	string	"modern"	Invoice template style
color	string	"#4F46E5"	Accent color (hex)
pageSize	string	"letter"	"letter", "a4", "a3", "legal"
currency_symbol	string	"$"	Prefix for monetary values

📦 Response Format

{
  "success": true,
  "pdf": "JVBERi0xLjM...",       // base64-encoded PDF
  "pages": 1,
  "sizeBytes": 18432,
  "invoice_number": "INV-001",
  "totals": {
    "subtotal": 2669.99,
    "tax": 220.27,
    "discount": 0,
    "total": 2890.26
  },
  "watermark": true,              // true on Free tier
  "template": "modern",
  "usage": {
    "used": 1,
    "limit": 50,
    "remaining": 49
  }
}

🔑 Authentication

All endpoints except /register and /health require an API key. Pass it via:

X-API-Key: binv_YOUR_KEY_HERE
// or
Authorization: Bearer binv_YOUR_KEY_HERE

⚠️ Error Responses

Status	Meaning	Example
400	Bad Request	Missing from.name, invalid items array
401	Unauthorized	Missing or invalid API key
403	Forbidden	Feature requires higher tier (e.g., logo)
429	Rate Limited	Quota exceeded or too many requests/min
500	Server Error	PDF generation failed

💎 Pricing

💻 Code Examples

JavaScript (Node.js)

const res = await fetch("https://buildinvoice.co/api/v1/generate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "binv_YOUR_KEY"
  },
  body: JSON.stringify({
    from: { name: "Acme Corp", email: "billing@acme.com" },
    to: { name: "Jane Smith" },
    items: [
      { description: "Consulting (10 hrs)", quantity: 10, rate: 150 },
      { description: "Travel expenses", quantity: 1, rate: 85 }
    ],
    tax_rate: 8.25,
    notes: "Payment due within 30 days."
  })
});

const { pdf } = await res.json();
// pdf is a base64 string — decode and save
fs.writeFileSync("invoice.pdf", Buffer.from(pdf, "base64"));

Python

import requests, base64

resp = requests.post(
    "https://buildinvoice.co/api/v1/generate",
    headers={"X-API-Key": "binv_YOUR_KEY"},
    json={
        "from": {"name": "Acme Corp"},
        "to": {"name": "Jane Smith"},
        "items": [
            {"description": "Website Design", "quantity": 1, "rate": 2500}
        ],
        "tax_rate": 8.25
    }
)

pdf_bytes = base64.b64decode(resp.json()["pdf"])
with open("invoice.pdf", "wb") as f:
    f.write(pdf_bytes)

PHP

$response = json_decode(file_get_contents(
    "https://buildinvoice.co/api/v1/generate",
    false,
    stream_context_create([
        "http" => [
            "method" => "POST",
            "header" => "Content-Type: application/json\r\nX-API-Key: binv_YOUR_KEY",
            "content" => json_encode([
                "from" => ["name" => "Acme Corp"],
                "to" => ["name" => "Jane Smith"],
                "items" => [["description" => "Service", "quantity" => 1, "rate" => 500]]
            ])
        ]
    ])
), true);

file_put_contents("invoice.pdf", base64_decode($response["pdf"]));