REST API · v1

BuildInvoice API

Generate professional PDF invoices from structured JSON with a single API call. No dashboard, no setup — clean endpoints, instant PDFs.

API live
🔒 HTTPS only
📄 JSON request / base64 PDF response
🌍 Global CDN

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.

1

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.

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", "email": "billing@acme.com" },
    "to":   { "name": "Jane Smith" },
    "items": [
      { "description": "Website Design", "quantity": 1, "rate": 2500 }
    ],
    "tax_rate": 8.25
  }'
3

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

POST

/api/v1/generate

Generate a PDF invoice from JSON. Returns a base64-encoded PDF and computed totals.

POST

/api/v1/register

Create a free API key. Send {"email": "you@example.com"} — no authentication required.

GET

/api/v1/usage

Returns your current usage and remaining quota for the billing period. Requires API key.

GET

/api/v1/health

Health check — returns service status and version. No authentication required.


📋 Request Schema — /generate

required from
FieldTypeRequiredDescription
namestringYesYour company or personal name
addressstringNoStreet address, city, state
emailstringNoContact email shown on invoice
phonestringNoPhone number
logostringNoURL to logo image — Starter+ only
required to
FieldTypeRequiredDescription
namestringYesClient / recipient name
addressstringNoClient billing address
emailstringNoClient email
required items array

At least one item is required. Each entry in the array represents a line item on the invoice.

FieldTypeRequiredDescription
descriptionstringYesLine item description
quantitynumberNoQuantity — defaults to 1
ratenumberYesUnit price in your chosen currency
optional invoice
FieldTypeDefaultDescription
numberstring"INV-001"Invoice number displayed on document
datestringTodayInvoice date — format YYYY-MM-DD
due_datestringPayment due date — format YYYY-MM-DD
currencystringCurrency label (display only, e.g. "USD")
optional top-level fields
FieldTypeDefaultDescription
tax_ratenumber0Tax percentage — e.g. 8.25 for 8.25%
discountnumber0Flat discount amount (subtracted before tax)
notesstringNotes shown at the bottom of the invoice
termsstringTerms & conditions text
optional options
FieldTypeDefaultDescription
templatestring"modern"Invoice style — "modern", "classic", "minimal"
colorstring"#4F46E5"Accent hex color for headers and table rows
pageSizestring"letter""letter", "a4", "a3", "legal"
currency_symbolstring"$"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.

StatusMeaningCommon Cause
400Bad RequestMissing from.name, invalid items array, malformed JSON
401UnauthorizedMissing or invalid X-API-Key
403ForbiddenFeature requires a higher tier (e.g., logo on Free tier)
429Rate LimitedMonthly quota exceeded or per-minute limit hit
500Server ErrorPDF 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

$0
/ month
  • 50 invoices / month
  • All templates
  • Watermark on PDF
  • No logo embedding

Pro

$29
/ month
  • 5,000 invoices / month
  • No watermark
  • Logo embedding
  • 150 req / min

Business

$79
/ month
  • 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.

🔗 Direct API
Use buildinvoice.co/api/v1/... with your binv_ key directly. Best for production apps, server-side code, or if you want full control.
⚡ RapidAPI Hub
Use your 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 '{ ... }'
⚡ View BuildInvoice on RapidAPI →