Articles

VM2 Ordernumber Plugin - Customize order and invoice numbers

Documentation of the Ordernumber Plugin for VirtueMart 2

Configuration

After installation in Joomla's extension manager, you need to configure the plugin. It is automatically enabled, but by default, does not change the order and invoice numbers! You have to manually configure the plugin in the Joomla plugin manager (NOT inside VirtueMart!) first:

  • Go to the Plugin manager in the Joomla backend ("Extensions" -> "Plug-In Manager")
  • Find the plugin named "VM - Custom Order and Invoice Numbers" and click on it. This will bring up the configuration screen for the plugin:
    plg vmshopper ordernumber plugindescription
  • First change the "Status" on the left side the "Enabled" to enable the plugin itself
  • Then configure your desired format of order and invoice numbers on the right side. If you leave one of the "Customize .... number" radio buttons at its default value of "No", then VirtueMart's default format will be used for that type of number.
  • If you enable customizing one of the numbers, you can then change the format in the text box below. The text does not have to follow any particular format, but a # incidates a counter and everything between square backets [...] indicates a variable.
  • The third option ("Counter") lets you specify whether the counter that will be inserted at the # position in the string should be a global counter or start from 1 for each new value of the remaining format. E.g. If you use a format "[year]-#" and you have the counter set to global, then you will get order numbers 2012-1, 2012-2, ..., 2012-512,2013-513, 2013-514. In particular, the counter will NOT start from 1 if the year changes. If you select "Separate counter per format value", then the counter will start from 1 for a new year: 2012-1, 2012-2, ..., 2012-512,2013-1, 2013-2, ...

Frequently Asked Questions (FAQ) ->

How the plugin works

When a new order is submitted, a new invoice is created or a new user is created, this plugin immediately creates the corresponding order/invoice/customer number before VirtueMart uses its default algorithm. VirtueMart then stores this number in the database and does not create its own numbers. This plugin does not override the general order or invoice handling, but only hooks in at that one point where the number is initially created.

As a consequence, this plugin is not able to change the numbers of existing orders, invoices and customers.

Order/Invoice Number Format Strings

The format strings are simple texts, where the following variables will be replaced. Everything that does not match one of these is taken verbatim into the invoice/order/customer numbers and order password.

Variable   Ord.Nr. Pwd. Inv.Nr. Cust.Nr.
# Running counter (either global or per format-value); Not applicable to the order password!
Date and Time:
[year] Current year (4 digits)
[year2] Current year (2 digits)
[month] Current month (2 digits); leading zeros if necessary
[day] Current day (2 digits); leading zeros if necessary
[hour] Current hour in 24-hour format; leading zeros if necessary
[hour12] Current hour in 12-hour format; leading zeros if necessary
[ampm] Current am-pm (for 12-hour format) in lower-case
[minute] Current minute; leading zeros if necessary
[second] Current second; leading zeros if necessary
Random Numbers and Strings:
[randomDigit[n]] Random sequences of n decimal digits (n=1 if not given).
[randomHex[n]] Random sequences of n hexadecimal digits (n=1 if not given).
[randomLetter[n]] Random sequences of n (upper- and lowercase) letters (n=1 if not given).
[randomULetter[n]] Random sequences of n uppercase letters (n=1 if not given).
[randomLLetter[n]] Random sequences of n lowercase letters (n=1 if not given).
[randomAlphanum[n]] Random sequences of n general alphanumeric characters (A-Z, a-z, 0-9) (n=1 if not given).
Billing Address information:
Lastname Last name of the shopper (billing address)
Firstname First name of the shopper (billing address)
Company Company of the shopper (billing address)
City City of the shopper (billing address)
zip ZIP of the shopper (billing address)
country Full county name (billing address)
countrycode2 2-letter country code (billing address)
countrycode3 3-letter country code (billing address)
Order and Invoice details:
orderNumber Order number, for which the invoice is created
orderStatus Status of the order (abbreviations: S, R, X, C, U, P)
Internal Variables (use strongly discouraged):
vendorID (Internal) VirtueMart Vendor ID
userID (Internal) VirtueMart User ID
orderID (Internal) Order ID, for which the invoice is created
CountryID (Internal) Country ID of the shopper's country
IPaddress IP-Address of the shopper's computer

Examples

  • For example, a format "[year][month]-#" will create numbers like:

201211-1
201211-2
201211-3
201212-1
201301-1
201301-2

  • A format "[year2]-[month]: [randomHex3]-[randomULetter5][randomDigit]-#" will create order/invoice numbers like:

12-11: a3b-ETZKE8-1
12-11: 808-KWCHZ1-2
12-11: 3cfb-JKIKR0-3
12-11: 328-QXPZJ7-4

  • If you want the invoice numbers to match the order numbers, you can use a format "[orderNumber]" (notice the lack of the running counter!). However, this might not fulfil the legal requirement of successive invoice numbers, as some orders might be cancelled (but still counted) before an invoice is issued!
  • For the order passwords, it is STRONGLY suggested to only use random fields and no fixed parts due to security concerns!
  • The default order number of VirtueMart 2 more or less corresponds to a format "[randomHex4]0#", the default order password to a format "p_[randomHex5]" and the default invoice format to a format "[year2][month][day][randomHex4]0#".
  • For customer numbers (which are by default not displayed in VirtueMart's invoices) we strongly recommend to use a GLOBAL counter and no date-specific part in the customer number, as this will give a hint of the customer's first order date, which might be even regarded as sensitive information! Also, the customer number format cannot contain any order-specific placeholders for obvious reasons (the customer needs to register BEFORE any order can be created).

 

FAQ

License

This plugin is licenced unter the GNU GPLv3. However, you have to pay for the download (all updates are free to our customers). After that, you have all the right and duties that the GPL gives you.

Version History

2014-09-06: Version 1.10 (Fix some minor issues with Joomla 3.0)
2014-08-16: Version 1.9 (update for Joomla 3.x and VirtueMart 3.x compatibility; drop Joomla 1.5 support)
2013-02-26: Version 1.8 (add backward support for the outdated Joomla 1.5)
2013-01-22: Version 1.7 (implement country variables)
2013-01-11: Version 1.6a (fix some update problems from 1.5 to 1.6)
2013-01-09: Version 1.6 (customer numbers can also be customized)
2012-11-16: Version 1.5 (implement padding the counter with zeros)
2012-11-23: Version 1.4 (fix random elements in the formats)
2012-11-17: Version 1.3 (fix python 5.2 for real; fix German translation)
2012-11-15: Version 1.2 (fix for phython 5.2; only create invoice number when neccessary)
2012-11-14: Version 1.1 (implement variables derived from user data)
2012-11-12: Version 1.0 (initial release for Joomla 2.5)