Generate a PDF invoice from JSON in PHP

What you need

• An API key. Create one in the app under API keys and export it as FORMFEED_API_KEY. A test key (ff_test_…) is right for trying things out. See the quick start.
• PHP. You need PHP 8 with the curl and json extensions, which almost every installation has.
• The template. invoice-de from the invoice example: copy it into your workspace from the example’s page, which keeps the name invoice-de and publishes the copy, or push the folder with the CLI (formfeed templates push --publish). A render uses the published version.
• The data. The example’s data.json next to the program. It holds the company, the customer and two invoice lines, and no totals.

The program

The program reads data.json, posts it with the template’s name and a file name built from the invoice number, waits for the result when the API answers 202, stops with the API’s message when something is wrong, and saves the PDF.

<?php
$data = json_decode(file_get_contents('data.json'), true);
$body = [
    'template' => 'invoice-de',
    'data' => $data,
    'filename' => 'invoice-' . $data['invoice']['number'] . '.pdf',
];

// one call with the key: the decoded answer (a render or a problem document) and its status code
function api(string $url, ?array $body = null): array {
    $curl = curl_init($url);
    curl_setopt_array($curl, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('FORMFEED_API_KEY'),
            'Content-Type: application/json',
        ],
    ] + ($body === null ? [] : [CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($body)]));
    $answer = curl_exec($curl);
    // a connection that never got an answer: no status code to look at
    if ($answer === false) {
        fwrite(STDERR, curl_error($curl) . PHP_EOL);
        exit(1);
    }
    return [json_decode($answer, true), curl_getinfo($curl, CURLINFO_RESPONSE_CODE)];
}

[$render, $status] = api('https://api-eu.formfeed.dev/v1/renders', $body);

// not done within 60 seconds: the answer is 202 and the render goes on in the background;
// its result answers the same way until the render has finished
while ($status === 202) {
    sleep(2);
    [$render, $status] = api('https://api-eu.formfeed.dev/v1/renders/' . $render['id'] . '/result');
}

// every error is a problem document (RFC 9457) with a title and a detail
if ($status >= 400) {
    fwrite(STDERR, $render['title'] . ': ' . ($render['detail'] ?? '') . PHP_EOL);
    exit(1);
}

file_put_contents('invoice.pdf', file_get_contents($render['download_url']));
echo $render['id'], ' ', $render['page_count'], ' page(s), ', $render['units'], ' unit(s)', PHP_EOL;

Run it

It prints the render’s id, the page count and the units it cost, and invoice.pdf lies next to the program. With a key that starts with ff_test_ the render is not metered; on the Free plan it carries a small watermark.

export FORMFEED_API_KEY=ff_test_...
php render.php

What is particular about PHP

• Arrays become JSON. json_encode turns the nested array into the request body; json_decode(…, true) gives the sample data and the answer back as arrays.
• The download. file_get_contents on the download_url needs allow_url_fopen. Where that is off, fetch the URL with a second cURL handle; it is signed, so it needs no Authorization header.
• No SDK needed. There is no PHP package to install or keep up to date: the API is one POST with a JSON body.

What the template does with the JSON

The request carries no derived numbers, which is the point of rendering from a template:

• Totals. invoice.lines | sum('total') adds the lines, and VAT and gross follow from invoice.vat_rate.
• Formats. With the template’s locale de-DE, money prints 3.760,40 € and date('dd.MM.yyyy') prints 10.09.2026; dateAdd(14, 'days') sets the due date.
• GiroCode. epcQr draws the SEPA payment code from name, IBAN, BIC, amount and reference.
• File name. is not the template’s job. The API takes filename as written and fills in no template expressions, so the program builds invoice-2026-0042.pdf from the invoice number, and the download carries that name. Characters outside A–Z, a–z, 0–9, ., -, _, (, ) and the space become _.

From one invoice to many

An invoice run is a batch: one request with up to 1,000 documents, one zip at the end, and a webhook when it is done. See batches. For documents that take longer than a few seconds, render asynchronously and let a webhook report back.

When the API says no

• One shape for every error. Errors are problem documents (RFC 9457) with type, title, status, detail, a stable code and the request_id to quote to support; the type URL leads to a page about that error. The list is in the error reference.
• The usual ones. 401 unauthorized for a missing or revoked key, 404 template_not_found for a wrong template name, 422 template_runtime_error when the template fails on the data, 429 rate_limited above the plan’s requests per second, 402 quota_exceeded when the Free plan’s units are used up (a paid plan bills extra units up to its hard cap).
• Retry safely. Send an Idempotency-Key header with the POST, and repeat the request with the same key when you do not know whether the first attempt arrived: for 24 hours the key returns the first answer instead of rendering and billing again. The answer is stored once the first attempt has been answered, so do not retry while it may still run; and problems below 500 are stored too, so a corrected request needs a new key.

The job around this program

This guide is one program. What the job needs around it, from the template to the limits and the price, is on the page Invoice PDF API.

More PHP guides

• Create a ZUGFeRD / Factur-X e-invoice in PHP
• Convert HTML to PDF in PHP
• Generate Open Graph images in PHP
• Generate PDFs from a CSV in PHP
• Merge PDFs and add a password in PHP
• Async PDF rendering with a verified webhook in PHP

FAQ

Can I send the invoice HTML instead of using a stored template?

Yes, put it in html and leave template out; the HTML-to-PDF guide of this language shows it. A stored template adds versions, a preview with your sample data and release channels.

How long is the download URL valid?

A signed link is valid for at most seven days and never longer than the file is kept, which your plan’s retention decides (a workspace setting or expires_in can only shorten it). GET /renders/{id} issues a fresh link at any time, so store the render’s id, not the URL. With access: "public" the link lasts as long as the file. Details in the rendering docs.

What does a render cost?

One unit for every started five pages of a PDF, so one to five pages cost one unit and six to ten cost two. Test renders are free. See pricing.

PDF invoice from JSON in other languages

• Node.js (TypeScript)
• Python
• Go
• C# (.NET)
• Java
• Ruby
• curl