BuildInvoice API
Generate professional PDF invoices from structured JSON with a single API call. No dashboard, no setup — clean endpoints, instant PDFs.
Also available on RapidAPI Hub — test endpoints directly in the browser, explore code snippets in 10+ languages, and subscribe to a plan without leaving RapidAPI.
Quick Start
Get a PDF invoice in under 60 seconds — no credit card, no dashboard.
Get a free API key
curl -X POST https://buildinvoice.co/api/v1/register \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com"}'
Your key (binv_…) will be emailed instantly. No credit card required for the Free tier.
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", "email": "billing@acme.com" },
"to": { "name": "Jane Smith" },
"items": [
{ "description": "Website Design", "quantity": 1, "rate": 2500 }
],
"tax_rate": 8.25
}'
Decode and save your PDF
The pdf field in the response is a base64-encoded PDF. Decode it to get your file. That's all there is to it.
{
"success": true,
"pdf": "JVBERi0xLjM...", // base64-encoded PDF
"pages": 1,
"sizeBytes": 18432,
"invoice_number": "INV-001",
"totals": {
"subtotal": 2500.00,
"tax": 206.25,
"discount": 0,
"total": 2706.25
},
"watermark": true, // true on Free tier
"template": "modern",
"usage": { "used": 1, "limit": 50, "remaining": 49 }
}
Minimum required fields: from.name, to.name, and at least one item with description and rate. Everything else is optional with sensible defaults.
Authentication
Pass your API key on every request (except /register and /health) using either method:
Header — X-API-Key (recommended)
Add X-API-Key: binv_YOUR_KEY_HERE to the request headers.
Bearer Token
Alternatively use Authorization: Bearer binv_YOUR_KEY_HERE.
X-API-Key: binv_YOUR_KEY_HERE
# or
Authorization: Bearer binv_YOUR_KEY_HERE
Endpoints
Base URL: https://buildinvoice.co
/api/v1/generate
Generate a PDF invoice from JSON. Returns a base64-encoded PDF and computed totals.
/api/v1/register
Create a free API key. Send {"email": "you@example.com"} — no authentication required.
/api/v1/usage
Returns your current usage and remaining quota for the billing period. Requires API key.
/api/v1/health
Health check — returns service status and version. No authentication required.
Request Schema — /generate
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Your company or personal name |
address | string | No | Street address, city, state |
email | string | No | Contact email shown on invoice |
phone | string | No | Phone number |
logo | string | No | URL to logo image — Starter+ only |
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Client / recipient name |
address | string | No | Client billing address |
email | string | No | Client email |
At least one item is required. Each entry in the array represents a line item on the invoice.
| Field | Type | Required | Description |
|---|---|---|---|
description | string | Yes | Line item description |
quantity | number | No | Quantity — defaults to 1 |
rate | number | Yes | Unit price in your chosen currency |
| Field | Type | Default | Description |
|---|---|---|---|
number | string | "INV-001" | Invoice number displayed on document |
date | string | Today | Invoice date — format YYYY-MM-DD |
due_date | string | — | Payment due date — format YYYY-MM-DD |
currency | string | — | Currency label (display only, e.g. "USD") |
| Field | Type | Default | Description |
|---|---|---|---|
tax_rate | number | 0 | Tax percentage — e.g. 8.25 for 8.25% |
discount | number | 0 | Flat discount amount (subtracted before tax) |
notes | string | — | Notes shown at the bottom of the invoice |
terms | string | — | Terms & conditions text |
| Field | Type | Default | Description |
|---|---|---|---|
template | string | "modern" | Invoice style — "modern", "classic", "minimal" |
color | string | "#4F46E5" | Accent hex color for headers and table rows |
pageSize | string | "letter" | "letter", "a4", "a3", "legal" |
currency_symbol | string | "$" | Symbol prefixed to all monetary values |
Response Format
A successful 200 response from /generate returns:
{
"success": true,
"pdf": "JVBERi0xLjM...", // base64-encoded PDF
"pages": 1,
"sizeBytes": 18432,
"invoice_number": "INV-042",
"totals": {
"subtotal": 2669.99,
"tax": 220.27,
"discount": 0,
"total": 2890.26
},
"watermark": true, // true on Free tier
"template": "modern",
"usage": {
"used": 12,
"limit": 50,
"remaining": 38
}
}
To save the PDF, base64-decode the pdf field and write the bytes to a .pdf file. See the code examples below for language-specific implementations.
Error Codes
All errors return JSON with a success: false flag and a human-readable error message.
| Status | Meaning | Common Cause |
|---|---|---|
400 | Bad Request | Missing from.name, invalid items array, malformed JSON |
401 | Unauthorized | Missing or invalid X-API-Key |
403 | Forbidden | Feature requires a higher tier (e.g., logo on Free tier) |
429 | Rate Limited | Monthly quota exceeded or per-minute limit hit |
500 | Server Error | PDF generation failed — please retry or contact support |
429 Handling: When rate limited, check the Retry-After response header for the number of seconds to wait before retrying.
Pricing
Start for free — upgrade when you need higher volume or advanced features.
Free
- 50 invoices / month
- All templates
- Watermark on PDF
- No logo embedding
Starter
- 500 invoices / month
- No watermark
- Logo embedding
- 30 req / min
Pro
- 5,000 invoices / month
- No watermark
- Logo embedding
- 150 req / min
Business
- 25,000 invoices / month
- No watermark
- Logo embedding
- 500 req / min
Code Examples
Full working examples for the most common environments. All examples decode the base64 PDF and write it to disk.
import fs from "fs";
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", address: "123 Main St, NYC" },
to: { name: "Jane Smith", email: "jane@example.com" },
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. Thank you for your business!",
invoice: { number: "INV-042", due_date: "2026-05-16" }
})
});
const data = await res.json();
if (!data.success) throw new Error(data.error);
// Decode base64 and save PDF
fs.writeFileSync("invoice.pdf", Buffer.from(data.pdf, "base64"));
console.log(`✅ Saved invoice.pdf (${data.sizeBytes} bytes, total: $${data.totals.total})`);
import requests, base64
resp = requests.post(
"https://buildinvoice.co/api/v1/generate",
headers={"X-API-Key": "binv_YOUR_KEY"},
json={
"from": {"name": "Acme Corp", "email": "billing@acme.com"},
"to": {"name": "Jane Smith"},
"items": [
{"description": "Website Design", "quantity": 1, "rate": 2500},
{"description": "Hosting (1 yr)", "quantity": 1, "rate": 120},
],
"tax_rate": 8.25,
"notes": "Thank you for your business!",
"invoice": {"number": "INV-042", "due_date": "2026-05-16"},
}
)
data = resp.json()
if not data["success"]:
raise RuntimeError(data["error"])
pdf_bytes = base64.b64decode(data["pdf"])
with open("invoice.pdf", "wb") as f:
f.write(pdf_bytes)
print(f"✅ Saved invoice.pdf (total: ${data['totals']['total']})")
<?php
$payload = json_encode([
"from" => ["name" => "Acme Corp", "email" => "billing@acme.com"],
"to" => ["name" => "Jane Smith"],
"items" => [["description" => "Service Fee", "quantity" => 1, "rate" => 500]],
"tax_rate" => 8.25,
"invoice" => ["number" => "INV-042"],
]);
$ctx = stream_context_create(["http" => [
"method" => "POST",
"header" => "Content-Type: application/json\r\nX-API-Key: binv_YOUR_KEY",
"content" => $payload,
]]);
$response = json_decode(file_get_contents(
"https://buildinvoice.co/api/v1/generate", false, $ctx
), true);
if (!$response["success"]) die("Error: " . $response["error"]);
file_put_contents("invoice.pdf", base64_decode($response["pdf"]));
echo "✅ Saved invoice.pdf (total: $" . $response["totals"]["total"] . ")\n";
# Generate invoice and save the raw JSON response
curl -s -X POST https://buildinvoice.co/api/v1/generate \
-H "Content-Type: application/json" \
-H "X-API-Key: binv_YOUR_KEY" \
-d '{
"from": { "name": "Acme Corp", "email": "billing@acme.com" },
"to": { "name": "Jane Smith" },
"items": [
{ "description": "Consulting", "quantity": 5, "rate": 200 }
],
"tax_rate": 8.25,
"invoice": { "number": "INV-042" }
}' | jq -r '.pdf' | base64 --decode > invoice.pdf
echo "✅ invoice.pdf saved"
RapidAPI Hub
BuildInvoice is listed on the RapidAPI Marketplace. If you already have a RapidAPI account, you can subscribe, test endpoints, and explore auto-generated code snippets without leaving the platform.
buildinvoice.co/api/v1/... with your binv_ key directly. Best for production apps, server-side code, or if you want full control.
X-RapidAPI-Key via the RapidAPI proxy. Best for quick testing, browser-based playgrounds, or integrating alongside other RapidAPI services.
Same API, two entry points. Both routes hit the same BuildInvoice engine and return identical responses. Pricing plans and monthly quotas are managed separately per platform — a plan on RapidAPI does not share your quota with a direct binv_ key.
Using BuildInvoice through RapidAPI
When calling through RapidAPI, replace the auth header and base URL:
# Direct API (using your binv_ key)
curl -X POST https://buildinvoice.co/api/v1/generate \
-H "X-API-Key: binv_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ ... }'
# Via RapidAPI (using your RapidAPI key)
curl -X POST https://buildinvoice.p.rapidapi.com/api/v1/generate \
-H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
-H "X-RapidAPI-Host: buildinvoice.p.rapidapi.com" \
-H "Content-Type: application/json" \
-d '{ ... }'