Skip to content

Reference Patterns

Reference Patterns

InvenTree contains a number of data models which require a unique reference field (such as Purchase Orders). In addition to being unique these reference values must conform to a specific pattern (which can be defined by the user). Defined reference patterns also make it simple for the user to control how references are generated.

Default Patterns

Out of the box, InvenTree defines a standard "pattern" for each type of reference (which can be edited via the InvenTree settings interface).

Model Type Default Pattern Example Output
Purchase Order PO-{ref:04d} PO-0001
Sales Order SO-{ref:04d} SO-0123
Build Order BO-{ref:04d} BO-1234
Return Order RMA-{ref:04d} RMA-0987

Pattern Requirements

Patterns can contain a mixture of literal strings, named variable blocks, and wildcard characters:

  • The pattern must contain a single {ref} variable - this is the required sequential part of the pattern
  • A ? (question mark) character is treated as a wildcard which will match any character
  • A # (hash) character is treated as a wildcard which will match any digit 0-9
  • Any other characters will be matched literally


When building a reference, the following variables are available for use:

Variable Description
{ref} Incrementing portion of the reference (*required)). Determines which part of the reference field auto-increments
{date} The current date / time. This is a Python datetime object

The reference field pattern uses Python string formatting for value substitution.

Date Formatting

The {date} variable can be formatted using the Python Format Codes.

Substitution Examples

Some examples below demonstrate how the variable substitution can be implemented:

Pattern Description Example Output
PO-{ref} Render the reference variable without any custom formatting PO-123
PO-{ref:05d} Render the reference variable as a 5-digit decimal number PO-00123
PO-{ref:05d}-{date:%Y-%m-%d} Render the date variable in isoformat PO-00123-2023-01-17

Last update: December 15, 2023