Proforma PDF Invoices for WooCommerce — Documentation
Install, set up and use DataFirefly Pro Forma Invoices 2.0 for WooCommerce: designs and live preview, company and bank details, numbering, customer buttons, e-mails, orders and update from 1.x.
Overview
DataFirefly Pro Forma Invoices creates professional pro forma invoices in PDF for your WooCommerce orders and carts. You create them in one click from any order, attach them to WooCommerce e-mails, or let your customers download them from the cart, their account or the order confirmation page.
A pro forma invoice shows what the customer will pay before the order is paid: it lets a customer pay in advance by bank transfer, get a purchase approved by a purchasing department or prepare customs paperwork.
A pro forma invoice is not a tax invoice. The document says so by default; keep issuing your final invoices as usual.
Requirements and installation
Requirements
- WordPress 6.4 or later (tested up to 7.1)
- WooCommerce 8.2 or later (tested up to 11.2), with or without HPOS
- PHP 7.4 to 8.5 with the
domandmbstringextensions (present on almost every host). GD is used to flatten transparent logos.
The PDF engine (Dompdf) is included: there is nothing else to install.
Installation
- Go to Plugins > Add New > Upload Plugin, choose the
df-proforma-woo-2.0.0.zipfile and click Install Now. - Activate the plugin. WooCommerce must be active.
- Open WooCommerce > Pro forma.
Setup guide and overview
The Overview tab opens with a four-step guide: enter your company details, add your logo and choose a design, choose where customers get the document, open a test PDF. Each step is ticked automatically when it is done.
The overview then shows the number of pro formas issued (in total and this month), the next number, where customers can download the document, the e-mails it is attached to, the latest pro formas with a link to their PDF and the state of the system.

Document: design and live preview
The Document tab sets what the PDF looks like. The live preview next to the settings uses the same template and fonts as the PDF and changes as you type, before you save. Above the preview, choose sample data or one of your 12 latest orders; Open as PDF shows the real file. The preview never issues a number.

Design
- Template: Modern, Classic, Minimal or Bold.
- Brand colour: pick one of the suggested colours or your own. Text placed on this colour turns white or black automatically to stay readable.
- Font: sans serif or serif. Paper size: A4 or US Letter.
- Logo: chosen from the media library, in three sizes. Without a logo, your company name is shown instead.


Products and amounts
- Prices on the document: excluding tax (usual for professional customers, with the tax added at the end) or including tax. Lines and totals always use the same mode.
- Optional columns and blocks: SKU column, product images, tax rate column, tax summary by rate, shipping address (when different), payment method, note left by the customer.
Texts and legal mentions
- Document title: leave it empty to use “Pro forma invoice” in the language of each customer.
- Valid for (days): 0 hides the “Valid until” date.
- Introduction, Terms and conditions and Footer (shown at the bottom of every page, above your company identifiers).
- Mention that the document is not a tax invoice: recommended.
Texts accept the placeholders {customer_name}, {order_number}, {proforma_number}, {valid_until} and {site_title}.
Company and bank details
The Company tab fills in the issuer block of the document. Use the WooCommerce store address copies the address of your store in one click.
- Company name, address, postcode, city, country, phone, e-mail and website.
- Identifiers and legal mentions: VAT number, registration number with its local name (for example SIRET, Handelsregister, KvK, NIP, CIF, Codice fiscale) and other mentions, one per line.
- Bank details: account holder, bank, IBAN and BIC / SWIFT, shown on every document when the option is on. Without your own details, the accounts of the WooCommerce “Direct bank transfer” method are used.

Numbering
The Numbering tab shows the next number as you change the settings.
- Number based on: its own sequence (recommended: consecutive numbers without gaps, in the order documents are issued, even when two documents are issued at the same time) or the order number.
- Prefix and Suffix: click a tag to insert
{Y}(year),{y}(two-digit year),{m}(month),{d}(day) or{order_number}. - Digits, Restart the counter (every year or never) and Next counter value (change it only when you continue an existing sequence).
A number is issued the first time the document of an order is opened, downloaded, attached to an e-mail or sent. It is stored on the order and never changes.

Customers and e-mails
The Customers & e-mails tab chooses where your customers get the document. These buttons are off until you turn them on.
- Button in My Account > Orders (order list and order page) and Button on the order confirmation page, for the order statuses you choose. Shop managers can always open the document from the order.
- Cart: add a “Download a pro forma invoice” button to the cart, choose its text, make it available to all visitors or logged-in customers only, and ask for the name, company and address to print on the document.
- E-mails: attach the PDF to the WooCommerce e-mails you choose (“Order on hold”, used for bank transfers, by default) and enable the “Pro forma invoice” e-mail. Edit the e-mail opens it in WooCommerce > Settings > Emails, where you change its subject, heading and text.

The PDF document
Each document is created from the current order, so it always matches it:
- issuer and customer blocks, with the country name and the address format of the country;
- number, issue date, validity date, order number and payment method;
- product lines with their options (for example Color: Red), SKU, image and tax rate when these columns are on;
- subtotal, discounts with coupon codes, shipping, fees, total excluding tax, one line per tax rate, total, refunds and balance, in the order currency;
- tax summary by rate, bank details, terms and conditions, footer and page numbers.
Long orders continue on several pages, with the table header repeated and the footer on every page. Fonts cover the Latin, Greek and Cyrillic alphabets.

Working with orders
Pro forma invoice box
Every order has a Pro forma invoice box with the number and dates and the buttons View PDF, Download, Send the pro forma invoice to the customer and Date it today, which restarts the validity period. The box also tells you whether the customer can download the document, and why not.

Order list
The Pro forma column shows the number of each order (click to open the PDF) or Create. Two bulk actions are added: Download pro formas (PDF), which puts up to 50 orders in one PDF file, and Send pro formas by e-mail. A message confirms each action.

Pro forma from the cart
With the cart button on, customers can get a pro forma before ordering, in the classic cart and in the Cart block. A short form asks for the name, company, address, country, VAT number and e-mail to print, pre-filled for logged-in customers; nothing is saved in their account. The PDF downloads without leaving the cart.
Cart documents get a reference starting with C and do not use your numbering. To prevent abuse, a visitor can create 10 cart documents every 10 minutes.
To place the button elsewhere, use the Pro forma button block (text, style and alignment) or the [df_proforma_cart_button] shortcode.

My Account and order confirmation
For the statuses you chose, the customer finds a download button in My Account > Orders and on the order confirmation page, with classic themes and block themes. Links need the secret order key, and registered customers must be logged in.

Tools, languages and privacy
The Tools tab contains:
- Language of the documents: the customer’s language (account language, WPML or Polylang) or the site language.
- Privacy: documents are generated on demand and not stored on the server; e-mail attachments are temporary files in a private folder, deleted right after sending; no cookie and no external request. A suggested text for your privacy policy is added to the WordPress privacy policy guide.
- Files from version 1: delete the PDF files left by version 1.
- System: PDF engine, PHP extensions, private folder and fonts, with Delete temporary files and Show the setup guide again.
- When the plugin is deleted: choose Keep the settings to keep them after deleting the plugin. Pro forma numbers stay in your orders and the counters are always kept, so that a reinstall never issues a number twice.
The plugin is translated into English, French, Spanish, German, Portuguese (Portugal), Italian, Polish and Dutch.
Updating from version 1.x
Install version 2.0.0 over version 1.x (Plugins > Add New > Upload Plugin, then Replace current with uploaded). On the first load:
- company details, logo, colour, validity and e-mail settings are kept;
- the numbering is identical: same counter, same prefix, numbers already given to orders kept;
- the PDF files of version 1, which could be opened by their address, are moved to a private folder; you can delete them in Tools;
- the new customer buttons stay off until you turn them on, and a notice explains what is new.
TCPDF is no longer used: you can remove any TCPDF copy you installed for version 1.
For developers
Template
Copy templates/document.php to yourtheme/df-proforma-woo/document.php to change the layout.
Hooks
dfpw_order_data(array $doc, WC_Order $order) anddfpw_cart_data(array $doc, WC_Cart $cart, array $buyer): data of a document.dfpw_proforma_number(string $number, WC_Order $order): new number.dfpw_document_css,dfpw_template_file,dfpw_document_locale.dfpw_customer_can_download,dfpw_cart_allowed,dfpw_cart_rate_limit,dfpw_attach_to_email,dfpw_customer_vat_number.dfpw_capability(settings, defaultmanage_woocommerce) anddfpw_order_capability(documents of orders, defaultedit_shop_orders).- Actions:
dfpw_number_issued,dfpw_pdf_generated,dfpw_cart_document_created.
WP-CLI
wp dfpw statuswp dfpw generate <order>... [--output=<file>]orwp dfpw generate 0 --samplewp dfpw next-number [<value>]wp dfpw cleanup
Troubleshooting
The PDF is not created
Open Pro forma > Tools > System or Tools > Site Health: the PHP extensions dom and mbstring must be present and the private folder writable.
The customer does not see the download button
Check that the button is on in Customers & e-mails and that the order status is one of the chosen statuses. The Pro forma invoice box of the order explains why the customer cannot download it.
Some characters are missing
The fonts cover the Latin, Greek and Cyrillic alphabets. Chinese, Japanese, Korean, Arabic and Hebrew are not supported.
The amounts do not match the order
The document always mirrors the current order. If you changed the order after sending the pro forma, open the document again or send it again.