--- title: "Invoice Image API: Render Invoices as PNG or PDF from JSON" description: "Render styled invoices as PNG images or paginated A4 PDFs with the Invoice Image API. Send line items, totals, and party data as JSON, get a hosted file." url: "https://html2img.com/templates/invoice-image/" --- # Invoice Image Generator API Send line items and totals as JSON, get back the printable invoice as a 1240x1754 PNG or a paginated A4 PDF. Finance teams and billing platforms use the Invoice Image API to turn database rows into styled invoice files without running their own headless browser. Customers want to see the invoice the moment a payment clears, and PNGs embed in email more reliably than PDFs across the major clients. You post party details, line items, and totals as JSON, and the endpoint returns a 1240x1754 PNG hosted on i.html2img.com. Add format: "pdf" to the same request and it returns the invoice as an A4 PDF with selectable text instead. ## At a glance - **Template slug:** `invoice-image` - **Category:** business - **Endpoint:** `POST https://app.html2img.com/api/v1/templates/invoice-image` - **Authentication:** `X-API-Key` header - **Cost:** one credit per render, PNG or PDF - **Page:** https://html2img.com/templates/invoice-image/ ## Fields | Field | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `invoice_number` | string | Yes | | INV-2026-0042 | | `issue_date` | string | No | | Apr 30, 2026 | | `due_date` | string | No | | May 30, 2026 | | `business_name` | string | Yes | | Northwind Studio Ltd | | `business_address` | string | No | | 12 Bishopsgate London EC2N 4AT United Kingdom | | `business_email` | string | No | | billing@northwind.studio | | `client_name` | string | Yes | | Linden & Co | | `client_address` | string | No | | 548 Market Street San Francisco, CA 94104 USA | | `client_email` | string | No | | ap@lindenco.com | | `items` | array | Yes | Object shape: description (string), quantity (string), unit_price (string), amount (string). | [{"description":"Brand identity design","quantity":"1","unit_price":"$4,800.00","amount":"$4,800.00"},{"description":"L… | | `subtotal` | string | No | | $10,520.00 | | `tax_label` | string | No | | VAT (20%) | | `tax_amount` | string | No | | $2,104.00 | | `total` | string | Yes | | $12,624.00 | | `notes` | string | No | | Payment due within 30 days. Wire transfer details on file. | | `logo_url` | url | No | | | | `accent_color` | string | No | | #0F766E | ## Defaults | Field | Default | | --- | --- | | `width` | 1240 | | `height` | 1754 | ## Example request ```bash curl -X POST https://app.html2img.com/api/v1/templates/invoice-image \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"invoice_number":"INV-2026-0042","issue_date":"Apr 30, 2026","due_date":"May 30, 2026","business_name":"Northwind Studio Ltd","business_address":"12 Bishopsgate\nLondon EC2N 4AT\nUnited Kingdom","business_email":"billing@northwind.studio","client_name":"Linden & Co","client_address":"548 Market Street\nSan Francisco, CA 94104\nUSA","client_email":"ap@lindenco.com","items":[{"description":"Brand identity design","quantity":"1","unit_price":"$4,800.00","amount":"$4,800.00"},{"description":"Landing page build (8 sections)","quantity":"1","unit_price":"$3,200.00","amount":"$3,200.00"},{"description":"Photography retainer","quantity":"6","unit_price":"$420.00","amount":"$2,520.00"}],"subtotal":"$10,520.00","tax_label":"VAT (20%)","tax_amount":"$2,104.00","total":"$12,624.00","notes":"Payment due within 30 days. Wire transfer details on file.","accent_color":"#0F766E"}' ``` ## In your language ### PHP ```php 'YOUR_API_KEY', ])->post('https://app.html2img.com/api/v1/templates/invoice-image', ['invoice_number' => 'INV-2026-0042', 'issue_date' => 'Apr 30, 2026', 'due_date' => 'May 30, 2026', 'business_name' => 'Northwind Studio Ltd', 'business_address' => '12 Bishopsgate London EC2N 4AT United Kingdom', 'business_email' => 'billing@northwind.studio', 'client_name' => 'Linden & Co', 'client_address' => '548 Market Street San Francisco, CA 94104 USA', 'client_email' => 'ap@lindenco.com', 'items' => ['0' => ['description' => 'Brand identity design', 'quantity' => '1', 'unit_price' => '$4,800.00', 'amount' => '$4,800.00'], '1' => ['description' => 'Landing page build (8 sections)', 'quantity' => '1', 'unit_price' => '$3,200.00', 'amount' => '$3,200.00'], '2' => ['description' => 'Photography retainer', 'quantity' => '6', 'unit_price' => '$420.00', 'amount' => '$2,520.00']], 'subtotal' => '$10,520.00', 'tax_label' => 'VAT (20%)', 'tax_amount' => '$2,104.00', 'total' => '$12,624.00', 'notes' => 'Payment due within 30 days. Wire transfer details on file.', 'accent_color' => '#0F766E']); $url = $response->json('url'); ``` ### Node.js ```javascript const response = await fetch('https://app.html2img.com/api/v1/templates/invoice-image', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ "invoice_number": "INV-2026-0042", "issue_date": "Apr 30, 2026", "due_date": "May 30, 2026", "business_name": "Northwind Studio Ltd", "business_address": "12 Bishopsgate\nLondon EC2N 4AT\nUnited Kingdom", "business_email": "billing@northwind.studio", "client_name": "Linden & Co", "client_address": "548 Market Street\nSan Francisco, CA 94104\nUSA", "client_email": "ap@lindenco.com", "items": [ { "description": "Brand identity design", "quantity": "1", "unit_price": "$4,800.00", "amount": "$4,800.00" }, { "description": "Landing page build (8 sections)", "quantity": "1", "unit_price": "$3,200.00", "amount": "$3,200.00" }, { "description": "Photography retainer", "quantity": "6", "unit_price": "$420.00", "amount": "$2,520.00" } ], "subtotal": "$10,520.00", "tax_label": "VAT (20%)", "tax_amount": "$2,104.00", "total": "$12,624.00", "notes": "Payment due within 30 days. Wire transfer details on file.", "accent_color": "#0F766E" }), }); const { url } = await response.json(); ``` ### Python ```python import requests response = requests.post( 'https://app.html2img.com/api/v1/templates/invoice-image', headers={'X-API-Key': 'YOUR_API_KEY'}, json={'invoice_number': 'INV-2026-0042', 'issue_date': 'Apr 30, 2026', 'due_date': 'May 30, 2026', 'business_name': 'Northwind Studio Ltd', 'business_address': '12 Bishopsgate London EC2N 4AT United Kingdom', 'business_email': 'billing@northwind.studio', 'client_name': 'Linden & Co', 'client_address': '548 Market Street San Francisco, CA 94104 USA', 'client_email': 'ap@lindenco.com', 'items': {'0': {'description': 'Brand identity design', 'quantity': '1', 'unit_price': '$4,800.00', 'amount': '$4,800.00'}, '1': {'description': 'Landing page build (8 sections)', 'quantity': '1', 'unit_price': '$3,200.00', 'amount': '$3,200.00'}, '2': {'description': 'Photography retainer', 'quantity': '6', 'unit_price': '$420.00', 'amount': '$2,520.00'}}, 'subtotal': '$10,520.00', 'tax_label': 'VAT (20%)', 'tax_amount': '$2,104.00', 'total': '$12,624.00', 'notes': 'Payment due within 30 days. Wire transfer details on file.', 'accent_color': '#0F766E'}, ) url = response.json()['url'] ``` ## What it is for ### Transactional email receipts at Northwind Studio When a customer card charges successfully, your billing service already holds the line items and totals. Post them to the endpoint and drop the returned URL into an tag in the receipt email. Customers see the styled invoice inline without downloading a PDF or waiting for an attachment to expand. Postmark, Resend, and Mailgun all accept remote PNG URLs, so the asset never touches your outbound mail server. Inbox open rates on receipt emails climb when the invoice renders without a click. ### Customer dashboard invoice previews Show the upcoming invoice on the billing tab of your dashboard before the renewal charges. Render the projected line items, plan amounts, and tax to a PNG, then drop the URL into the React component as an . The dashboard stays snappy because the browser is loading one cached image, not running a layout pass over a complex billing table. Riverside Bakery uses this pattern to give franchise owners a one-glance view of their March numbers without writing dashboard CSS. ### Accounting platform OCR ingestion Connector platforms that move data from a SaaS into Xero or QuickBooks need a stable image of the source invoice. Render the invoice once at issue time, store the PNG URL, and let the OCR job process it on a schedule. Because the layout is consistent across renders, the OCR confidence scores stay high and you avoid the manual matching queue. Halberd Software ships connectors for 14 SaaS tools using this exact flow, with one ingestion path that does not care which app produced the bill. ### Marketplace seller commission statements Two-sided marketplaces owe sellers detailed statements every payout cycle. Generate one styled PNG per seller per cycle from your already-computed payout rows. Sellers receive a single image that opens on mobile without zooming, embeds in WhatsApp without breaking, and prints to A4 if they need a physical copy for their accountant. Wren Analytics processes 8,400 seller statements monthly through this flow, replacing a queued PDF generator that often timed out. ### Subscription tools showing the next invoice Self-serve plan-change pages benefit from showing the prorated next invoice before the user clicks confirm. Build the line items in PHP, post to the endpoint, and embed the PNG above the confirm button. Conversion on plan upgrades climbs when buyers see exactly what they will be charged, with the same visual treatment as the receipts they already trust. The image takes around 1.4 seconds to render, well inside the page-load budget for an interactive flow. ## Output - **Dimensions:** 1240x1754 - **Colour space:** sRGB - **Transparency:** Not supported - **Typical file size:** 80 KB to 250 KB - **Platform specification:** [ISO 216 A4 portrait at 150 DPI](https://www.iso.org/standard/36631.html) ## Common mistakes ### VAT label localization A US merchant ships an invoice to a UK customer with a "Sales Tax" line, and the buyer files it as the wrong category. Send tax_label as a per-customer string ("VAT (20%)", "GST (10%)", "Sales Tax") so the rendered PNG matches the buyer's tax regime. ### Long line item descriptions wrap awkwardly A 180-character description of a custom service spills onto three lines and pushes the totals block off the page. Keep descriptions under 80 characters or split them across two adjacent rows so the PDF-style A4 layout holds together. ### Currency formatting drift across locales You save raw decimals in the database and let the renderer format them, then realize "1,290.00" displays where European customers expect "1.290,00". Pre-format every monetary string on your side using the buyer's locale before posting to the endpoint. ## Questions ### What size is the rendered invoice? The output is a 1240x1754 PNG, which is A4 portrait at 150 DPI. The file embeds in email at full width and prints clean to a physical A4 sheet without scaling artifacts. File size lands between 80 KB and 250 KB depending on logo and table density. ### Should I use a PDF or an image? The endpoint produces both from the same payload: the default output is a PNG, and format: "pdf" returns an A4 PDF with selectable text and embedded fonts. Use the PNG inline in email bodies, dashboards, and chat, where images display without a click. Send the PDF where the recipient will print, sign, search, or file the invoice. ### How are multiple currencies handled? You format every monetary string on your side before posting. The endpoint treats each amount as a string, so "$1,290.00", "€1.290,00", or "¥129,000" render exactly as written. This keeps the rendering layer free of currency logic and avoids drift between your billing system and the displayed invoice. ### How many line items can I include? In PNG output, invoices over 30 line items begin to overflow the single A4 page, so split very long bills if you need images. With format: "pdf" there is no practical ceiling: the line item table paginates across pages automatically and the totals block follows the final row. ### Can I add my company logo? Yes, pass logo_url with a public URL to a PNG or SVG. The renderer fetches the image during the layout pass and places it in the header block. Use a transparent PNG for cleanest results on the off-white invoice background. ### Does it support multi-page invoices? Yes, as a PDF. Pass format: "pdf" and a long invoice flows across as many A4 pages as its line items need, with no extra parameters. The PNG output remains a single page, so pick the PDF for bills that outgrow one sheet. ## Preview ![Invoice Image Generator API example render](https://i.html2img.com/image-1777560075359-294553.png) ## Related templates - [event-ticket](https://html2img.com/templates/event-ticket/) - [receipt-image](https://html2img.com/templates/receipt-image/) - [product-card](https://html2img.com/templates/product-card/) ## See also - [Every template](https://html2img.com/templates/) - [Templates API reference](https://html2img.com/docs/templates/) - [OpenAPI specification](https://html2img.com/openapi.json)