JSON To PDF - Invoice Tutorial

JSON data for an invoice, converted to a fully customisable PDF in seconds.

Getting started

Register and install an evaluation copy of ReportLab PLUS

This tutorial is aimed at showing the use of Report Markup Language (RML), which is a component of our commercial tool-kit. Here you can get a basic introduction to a common application architecture and start experimenting with some fundamental ReportLab technologies. If you have any problems or questions, please email enquiries@reportlab.com.

All you need to do to download a full evaluation copy is sign in or register on our site; then, follow the installation instructions to get yourself set up. Once these are completed, you're ready to go.

To check that all the dependencies are in place, start Python up (inside your virtual environment, if you are using one) and check these imports all work:

>>> import reportlab
>>> import rlextra

Download and install tutorial pack

You have two options, either download the partial tutorial pack, which means you will need to finish to the code changes listed below or download the completed tutorial pack, which means you will not need to make the changes listed below.

Take a look at the directory structure:

  • data/ will hold our JSON data
  • rml/ will hold the fonts, images, and templates for constructing the documents 
  • output/ will hold the generated PDFs
  • gen_invoice.py will be the script which ties it all together

Making your first document in Report Markup Language

python gen_invoice.py  data/invoice.json

You should now see a file output/invoice.pdf, which should look like:

It is not much to look at in its current state, but we will make some improvements along the way.

Code Walk Though

We open and process the JSON data in jsondict.py, which lets us iterate over child nodes and access elements with a dot-notation. The PDF template is rml/invoice.prep, open that file in an editor.

We define the frame(sections) on the page in the pagetemplate tag. During development, setting showBoundary can help be a visual guide to getting frames in the right place. Change the value from 0 to 1

Now generate the PDF again & you should see the the outline of the frames.  Change showBoundary back to 0.

In the rlextra package, we can include other PDFs, so if you have stock PDF assests/templates already, we can draw over the top of them.  We can achive this in a pageGraphics tags. Here we specify the path and dimensions of the PDF, add this at line 8:

Now generate to PDF again.

We can add some further enhancements to the style & make it a bit more colourful. In the stylesheet we can change the style. Now we add a blue background with white text:

We can define styles in the stylesheet tags, including paragraph styles: We can use the dot notation that jsondict.py allows.

In the template we can use a for loop to display the order:


Now generate the PDF again. The ouput should look like this:

Finally, a crude example of including Python code directly in the template. The script tag allows us to embed Python code. Lets say we plan to double check that the totals in the data match a computed value:

We can now add a call verify_totals() & print an error if accordingly. However, rather than display a warning on the PDF itself, a better approach might be to call any data validation code alot ealier & raise an error so that the PDF does not get generated.

Now look at line 21 in data/invoice.json change

       "price": "£1300.00",


       "price": "£1000.00",

Now save data.json and re-run the script and check the output.

Further examples of the huge range of chart types available with ReportLab can be found in our chart gallery which included details of the main parameters of each style. Go and experiment!