Skip to content

PDF layouts ​

Available from v4.0.0

The Store makes three PDF documents of an order: the invoice, the order confirmation and the packing slip. You download them from the order page in the CP, with the download tag, and Store Email can attach them to an email.

On the PDF layouts page in the CP you build each document yourself from blocks. Every document has its own layout.

PDF layouts

The page has its own permission: choose on the Permissions page which roles can open it. Without it, only a Super Admin can change the layouts.

Default layout

A document without a saved layout uses the default layout, which looks like the PDFs from before 4.0.0, with the Order custom fields block below the order lines. A saved layout doesn't get that block, add it yourself. The tabs show default for those documents. Reset to default removes the saved layout of a document.

The editor ​

The page has three columns:

  • Blocks: the blocks you can place. Drag a block to the page, or click it to add it to the body (or to the first zone it fits in, e.g. the footer for Page number). A greyed out block is already on the page, most blocks can be used once.
  • The page: an A4 (or US Letter) page with fixed zones. Drag a block to move it within a zone or to another zone; while dragging, the zones where the block fits light up. Click a block to change it, the cross removes it.
  • Settings: the Block tab shows the settings of the selected block, the Document tab the settings of the whole document.

Above the page you switch between Edit and Preview, and between a paid and a not paid test order. The preview is rendered by the same code as the PDF, with a test order. Download test PDF makes the real PDF of the layout on the page, also when it is not saved yet. Nothing changes for your customers until you click Save layout.

Zones ​

ZoneWhere
Header left, Header rightthe top of the first page
Address, Detailsthe row below the header, e.g. the billing address and the document details
Bodythe full width of the page, e.g. the title, the order lines and the totals
Footer left, Footer center, Footer rightthe bottom of every page (or of the last page, see Document settings)

Blocks ​

BlockZonesSettings
Logoallwidth, alignment. The image is the Logo on the Settings tab
Store addressallalignment. The text is the Store Address setting
Billing addressheader, address, bodyalignment, heading, company, VAT number, email, phone
Shipping addressheader, address, bodyalignment, heading, only when it differs from the billing address
Billing & shipping addressheader, address, bodyboth addresses next to each other: headings, company, VAT number, email and phone of the billing address, and the shipping address only when it differs. Instead of the separate address blocks: when one is on the page, the other is greyed out
Document titleheader, address, bodyown title (empty: Invoice, Order, Packing slip), size, alignment
Document detailsheader, address, bodydocument number, date, due date (invoice), customer number (members), payment method (packing slip: shipping method)
Order linesbodyprices incl. or excl. tax, "(incl. tax)" / "(excl. tax)" in the column headings, columns quantity, SKU, unit price, line total, tax % and tax amount, the old price of items on sale, custom fields, note and reorder or renewal. The packing slip has a checkbox column and no prices
Order custom fieldsallthe custom fields of the checkout (e.g. order notes), a line per field with a label made from its name (order_notes is Order notes): a heading, only these fields (e.g. order_notes|gift_message, in that order) and skip fields without a value. Shows nothing for an order without custom fields. Available from v4.0.0
Totalsbodyprices incl. or excl. tax, reverse charge note. The tax is shown per rate. Not on the packing slip
Payment statusalla text when paid (with a PAID stamp) and a text when not paid. Not on the packing slip
Textallfree text with HTML and order tags, text size, alignment, bold, italic, note style. The B and I buttons make the selected text bold or italic. Can be used more than once
Divider, Spacerallthe spacer has a height
Page numberfooteralignment, shows e.g. Page 1 / 2

Prices incl. or excl. tax ​

The Order lines and Totals blocks each have a Prices setting, so you choose per block whether the prices include tax. The tax lines of the totals show which one it is:

Excl. tax                              Incl. tax
Subtotal                  € 40,00      Subtotal                  € 48,40
Discount                 - € 4,00      Discount                 - € 4,84
Shipping                   € 5,00      Shipping                   € 6,05
21% tax over € 41,00       € 8,61      Total                     € 49,61
Total                     € 49,61      Including 21% tax          € 8,61

There is a tax line for every rate, with the amount the tax is calculated over (excl. tax), as an invoice in the EU needs. The discount is divided over the lines and the shipping has its own rate, like the order itself is calculated; the tax lines always add up to the tax of the order. The Order lines block can show "(incl. tax)" or "(excl. tax)" in its column headings.

Reorders and renewals ​

The Order lines block can show under the product name that a product reorders or renews an earlier order (see the reorder tag). Turn on Reorder or renewal, it is off by default. Only the products with an earlier order get the line, also on the packing slip.

The text is yours, {parent_order_id} is the id of the earlier order:

Reorder of order #{parent_order_id}
Renewal of order #{parent_order_id}

The line is not shown when the earlier order was deleted. HTML is not allowed in this text.

Order tags in a text ​

The Text and Payment status blocks parse the order tags of the order, without the order: prefix, and conditionals, e.g.:

Please pay {total_plus_tax:formatted} before {due_date}, stating {invoice_no}.
{if is_paid}Thank you for your payment.{/if}

Besides the single values of the order tag (e.g. {customer_first_name}, {total_plus_tax:formatted}, {gateway_label}), these tags are available:

TagExample
{invoice_no}INV-1042 (invoice prefix + order id)
{order_no}ORD-1042 (order prefix + order id)
{document_no}the invoice number on the invoice, the order number on the other documents
{order_date}, {invoice_date}the date of the order
{due_date}the order date plus the Invoice Due Days setting
{document_type}invoice, confirmation or shipping

Tag pairs such as {items} are not available, use the Order lines block for the items.

Document settings ​

  • Accent colour: the colour of the title, the lines of the tables and the total.
  • Font: Helvetica, DejaVu Sans or Times, the fonts of the PDF library. Use DejaVu Sans for characters outside Western Europe (e.g. Polish, Greek or Cyrillic).
  • Font size: 8 to 16 px.
  • Paper size: A4 or US Letter.
  • Show the footer on every page: on by default. When it is off, the footer follows the content on the last page.

Settings ​

The Settings tab, next to the documents, holds the settings of all documents (pdf_layouts/settings in the url):

Setting
LogoThe image of the Logo block.
Invoice due daysThe number of days after which the invoice is overdue, the {due_date} of the invoice.
Invoice prefixPut before the order id in the invoice number, e.g. INV-. Also in the file name of the invoice.
Order prefixPut before the order id in the order number, e.g. ORD-. Also in the file name of the order confirmation and the packing slip.

Upgrading from 3.x ​

See also Upgrading to 4.0. The Invoice footer, Order footer and Packing slip footer settings are no longer on the Settings page. Until you save a layout, the default layout shows the old footer in the Footer center zone; when you open the PDF layouts page it is a Text block there, which you can edit or move. A new line in a text is a line break in the PDF (unless the text has its own block HTML such as <p> or <br>), so an old footer with new lines but no HTML now shows those line breaks. The logo, the prefixes and the due days moved from the Settings page to the Settings tab of this page.

The text blocks know the same tags as the old footers, plus the formatted values of the order tag. One tag changed: {shipping_method} is the name of the carrier now (like {order:shipping_method}), before it was the add-on that handled the shipping. The footer has about 80 px at the bottom of the page; a long footer can overlap the content, keep it to a few lines.

In the editor preview, the HTML of a text block is cleaned (e.g. style attributes are removed), so it can look a bit different from the PDF. Use Download test PDF to see the real result.

Test checklist ​

  • Open each tab (invoice, order confirmation, packing slip) and check the preview with a paid and a not paid test order.
  • Download the test PDF of each document and compare it with the preview.
  • Save a layout, then download the PDF of a real order from the order page.
  • Check an order with many items: the table header and the footer repeat on every page and the page number shows the right total.