Custom Order Number Patterns in Drupal Commerce

Developer Desk

Drupal Commerce differentiates between the serial numeric ID assigned to an order by the database on save and the order number used to formally identify a placed order. Orders typically start as "drafts" (as in the case of shopping carts) and are assigned an order number when placed (as when a customer completes checkout).

In Commerce 1.x, the order number defaulted to the order ID. This created confusing order number sequences in admin listings when carts were checked out long after they were created or when they were abandoned. Businesses that required sequential order numbers without gaps needed custom code to make it happen.

Thanks to the Number Pattern module we added in Commerce 2.x, site builders have much greater control over order number generation via configuration alone. Number Pattern is used to generate order numbers and invoice numbers (via Commerce Invoice), and it is available for other contributed modules to use as well.

See selection here in the order type edit form:

When you first install Drupal Commerce, you get a Default order type that generates a sequential order number via the Default number pattern. You can disable the checkbox to revert to the previous method of using the order ID, which is nice if you want the order ID in URLs to match the order number. If you define additional number patterns, you can also differentiate the pattern use per order type (e.g. to use a different pattern for subscription renewal orders vs. the initial order).

Your site can have as many number patterns as needed, adding static prefixes / suffixes or token replacements in addition to the number itself. Commerce Core supports multiple options for number generation (i.e. an infinite sequence or a sequence that resets on a monthly or yearly basis), and you can define your own NumberPattern plugin in code as needed. (For example, you might prefer non-sequential numbers using a hash of some order details.)

The full configuration form looks like:

One common use case is to prefix the order number with a code identifying the order source, e.g. WEB-1001, WEB-1002, etc. You may have one pattern with no prefix for orders and a separate pattern with an INV- prefix for invoices. Just make sure you spend extra time to get it right at launch so you aren't trying to change the approach with a lot of data to update.

Finally, note that the sequences for number generation can be store specific. If your site uses multiple stores, whether for different sellers as in a marketplace scenario or to differentiate markets you sell in, you have the option to maintain distinct sequences for order numbers (or invoice numbers) on a per-store basis. Bear in mind that doing so can produce duplicate numbers if you don't add some differentiating characters to the pattern (e.g. the store ID).

With all of these options, unless you need a truly unique number generation method, you'll almost never need custom code to implement whatever order number pattern your clients require.

Add new comment