VirtueMart has its own invoice system which does the following for you:
- creates order number and invoice number
- creates a pdf invoice
- stores the pdf invoice in the safe path
- sends the invoice either automatically according to the selected order status in configuration or manually
General handling
Invoices are stored in a subfolder "invoices" within the safepath. The order list provides icons for downloading or printing the invoice/delivery note manually. The icons give an hint, if the invoice was already sent, or will be created. An invoices once created cannot be deleted and is not updated automatically. This has legally reasons. But since vm3.0.10 it is possible to create an updated order by changing the orderstatus. Changing from one orderstatus to another which both create an invoice, then the old invoice is renamed and a new invoice will be created. A shopper can view his order and download an existing invoice, but cannot create it.
Configuration
The vm config has in the tab checkout own settings for the pdf and allows configuring of the order-statuses to sent and/or create the invoice.
Page layout
Header, footer and general settings can be configured in the shop edit view, respectively the user edit of the vendor. There it is possible to set the default font, font size, page format, page margins, orientation, vendor image and so on.
Customising the PDF
For completly customisation, it is possible to use the layout overrides as usual. If you want to view the invoice in non-pdf format, just use the print view (go to the backend orders list, use the print icon, copy paste the link of the popup). it should look like this:
/index.php?option=com_virtuemart&view=invoice&layout=invoice&format=pdf&tmpl=component&virtuemart_order_id=5
just remove the &format=pdf to display the view, instead of rendering it into a pdf. You can also customise the mail layout using &layout=mail, instead of &layout=invoice.
/index.php?option=com_virtuemart&view=invoice&layout=mail&tmpl=component&virtuemart_order_id=5
The name of the invoice "vminvoice" can be renamed using the langkey COM_VIRTUEMART_FILEPREFIX_INVOICE
The name of the delivery note can be renamed using the langkey COM_VIRTUEMART_FILEPREFIX_DELIVERYNOTE
Important to consider layouting the invoice
The invoice can be created from different locations on your page. That means a plugin may change the order status from frontend (FE), so the invoice is created by the frontend application. But the order status can also be changed in the backend (BE), when an orderstatus for an order is changed. Attention, the icon in the BE use the FE (it is a link). So the executing index.php is in case of the FE usually at the root and using just /, but the index.php executed for the BE is in /administrator/. So layouting the invoice should be handled as layouting emails. Similar to emails the layout should be written in xhtml1.0 strict.
Any URLs should be given as absolute URLs. In the layout overrides and CSS for the invoice. The standard layout uses the VirtueMart API and takes care of that.
- Product links should use a JUri::root() (or vUri::root() in VMF)
- furthermore it is important to ensure that the variable VirtueMartModelCustomfields::$useAbsUrls is correctly set (done in the standard layout). Maybe moved out of the layout.
- All images being set in the invoice layout must have the full URL, for example http:://mydomain.com/images/..., ensure that the editor keeps the absolute URL.
All images must be either jpg or gif. Tcpdf allows some kind of png, others not. In doubt, just use jpg or gif.
The TCPDF library uses by default the fonts: courier, freemono, helvetica.
To update your fonts in TCDPF please upload proper font files to your /libraries/tcpdf/fonts/ if a non existent font is used within your wysiwyg templates, you may receive a fatal error.
Format of order and invoice number
The requirements for the order numbers are
- create unique relation
- not guessable
- can inlcude consecutive number
The format for the order numbers is RRRR0C, where R represents random and C represents counter. The randoms are seperated from the counter by a 0. We do not use a simple counter in the order number, because it is too easy to guess for "hackers" and could be used in social engineering to get access to support, address of the actual customer and so on.
The requirements for the invoice numbers are
- create unique relation
- not guessable
- must include consecutive number
- can have randoms
- should be sortable
Therefore the format ist YYMMDDRRRR0C, YY stand for the year, MM for month, DD for day. The counter uses the invoice entries of all invoices. A lot of countries still insist on conseutive numbers without gaps, therefore if your shop is live, do not delete invoices! It is better to set them to "cancelled".
When an invoice is already created and set to a new order status, which also should create an invoice (for example from "confirmed" to "cancelled"), then the old invoice is renamed before the new invoice is created.
Troubleshooting
Tcpdf needs clean written html. It is very handy to use the tips given in "Customising the PDF" to ensure that the html itself has no errors. Check in special for missing images and icons. JS is not rendered for pdfs so long as any involved js is set with the virtuemart js handler.
In general the tcpdf library is not very good in using png with alpha channels. If you get errors when using images, check if you use any gif or png image and replace it with a jpg.
Email with invoice is not sent
It is very likely that a broken pdf is the problem. The creation of a pdf can need a lot RAM, it is maybe necessary to increase the memory_limit to 256 MB. If your server is very slow it may necessary to increase the maximum execution time to 60 seconds. A normal page call in the frontend costs usally not more than 20 MB and should not take longer than 1.5 seconds.
TCPDF ERROR: [Image] Unable to get the size of the image:
TCPDF is unable to find some required files on the path. To resolve this, use the chapter about "customising the pdf" and check the html for missing images. It can also be an htaccess directory protection.
The XObject Template '-1' doesn't exist!
Please install the tcpdf library provided with our new installer http://dev.virtuemart.net/projects/tcpdf/files.
I dont want to create an invoice
1. create a order status code of "No invoice" On order status tab create a new status, eg call it No Invoice and give it a code, eg Z
2. On Configuration/Emails tab select only "No invoice" as Default Order Status to create an invoice (or on Config/Checkout tab is using a version older than VM3.0.11). That status will not be used by the payment plugins so create/send invoice will be ignored.
Fatal error: Call to undefined method VmVendorPDF::convertHTMLColorToDec()
This is caused by using a TCPDF version below 6, just update your tcpdf with our new component http://dev.virtuemart.net/projects/tcpdf/files