How can we help?

Range rule types

There are a number of rule types that you can use when entering ‘Match Rules’ or ‘Exclusion Rules’ for a range. Understanding how these rules work and when best to use them will allow you to quickly create sets of rules that target anything from individual postcodes to large regions of a country.

Before we take a look at the different rule types available, it’s useful to have an understanding of the three broad ‘types’ of postcode format.

Postcode format types

Whilst there are a large number of different postcode formats in use around the world, any given postcode format will fall into one of three main types:

  • Numeric: This postcode format type is made up exclusively of numbers. In the vast majority of cases these numbers are sequential and describe specific areas.

    Example - Australia has a numerical postcode system - all postcodes are either three or four digits long e.g. 123 or 1234. 

  • Pseudo-numeric: This format type contains a mix of numbers and letters (often these letters match the two-letter country code). However the letters are a ‘fixed’ portion of the format and apply to all postcodes. Ultimately it is the numbers within these postcodes that actually identify a given address.

    Example - Lithuania uses a pseudo-numerical postcode format e.g. LT12345. The LT at the start is ‘fixed’ and does not change between addresses. The 12345 at the end of this postcode is actually used for matching.

  • Alphanumeric: An alphanumeric format contains a mix of numbers and letters that follow a specific pattern but can be entirely random. Unlike pseudo-numeric postcodes, there is no ‘fixed’ portion of the postcode that is shared amongst all postcodes.

    Example: Canada has an alphanumeric postcode system that consists of a repeating pattern of letters and numbers e.g. A1A 1A1.

Being able to identify which postcode format type you are working with will help you to chose the correct rule types and write match rules that are easier to understand.

'Single' rules

'Single' rules are the most basic type of rule. These rules consist of a full, valid postcode which the order destination address postcode must match.

In the example below the destination address must match 1234 or 4321 in order for this range to be considered a match.


The single rule that you enter must match a valid postcode format for the country that the range applies to. In the example above, the country for this range is Australia. Australia has two valid postcode formats - three digits (e.g. 123) and four digits (1234). Entering a single rule that does not match one of these formats will result in a validation error:


Note: rules are validated based on their format rather than on whether the postcode itself actually exists. In other words if you enter a made up postcode that is in the correct format, it will pass validation.

Single postcode rules are not case sensitive and you do not need to format single rules with spaces in order for them to be considered valid. When comparing a single postcode rule against a destination postcode, both are normalised by stripping spaces and making both uppercase. For example this rule:


Would be a valid match for the postcode:

W1 1AB 

When to use:

You should use 'single' rules when you have one or more specific postcodes that you want to target that do not really relate to one another in any way (for example they are not part of a sequence). They are also very useful for marking specific postcodes as exclusions.

When to avoid:

You should avoid using 'single' rules when the rules you are entering could be expressed more succinctly using another rule type. For example, a set of match rules like this:


Would probably be better written using a 'span' rule (see span rules):



'Span' rules

'Span' rules make it possible to match against potentially large numbers of postcodes in a single line. A hyphen '-' character is used to separate the 'from' and 'to' sides of a span rule.

In the example below, the postcode for the destination address must be between 1000 and 3000 (inclusive) in order for this span rule to be considered a match.


In order to be considered valid, both 'sides' of the span rule that you enter must match a valid postcode format for the country that the range applies to and they should both be the same format as one another.

In the example below the 'to' side of the span does not pass validation as it is not a format associated with the country for this Range (Australia):


In the next example, both sides of the span are valid postcode formats for Australia but they are different from one another and therefore fail validation


Span rules are considerably more suited to numerical or pseudo-numerical postcode formats (see postcode format types).

This is because when a span rule is evaluated to see if it is a match for a given postcode, the comparison is computed numerically. In other words we ask:

"Is this postcode greater than (or equal to) the 'from' side of the span rule and less than (or equal to) the ‘to’ side of the span rule".

With numerical postcodes this comparison is straightforward. For pseudo-numerical postcodes, the 'fixed' portion of the format is dropped and the postcode is evaluated as a number.

For example, given the range:


The LT would be dropped on both sides of the range leaving:


Whilst it is possible to use a span rule for an alphanumeric postcode format you will most likely be better off using a 'wildcard range' rule instead (see ‘wildcard range’ rules).

An alphanumeric span rule will technically work but due to the way this postcode type is computed it is considerably less clear what is going on.  As a full postcode is used on either side and the initial expectation might be that a comparison is made on the full postcode.  However in reality only the first letter or number that is different between the two postcodes is used for the comparison and the rest of the postcode is ignored.

When to use:

You should use a span rule to target a sequential group of numerical or pseudo-numerical postcodes.

When to avoid:

You should avoid using span rules when dealing with alphanumeric postcodes and opt instead for either 'wildcard' or 'wildcard span'.


'Wildcard' rules

A 'wildcard' rule allows for the creation of rules than can match any character from a given position within a postcode. An asterisk (*) character is used to define a wildcard rule.

In the example below, the postcode for the destination address must start with BS1 followed by a space and then any other combination of letters and numbers in order for this range to be considered a match:

BS1 * 

In order to be considered valid, the section of the postcode before the wildcard (*) character must match a valid format for the country assigned to the Range you are creating the rule for. The following example would fail validation for a Range set to the United Kingdom as it is not a valid UK postcode:

1BS * 

The rule must also contain only one wildcard character and this must come at the end of the rule. For example, in the rule below, two wildcard characters have been used making the rule invalid:

BS1 ** 

Finally the wildcard character must appear at the end of the rule. The following rule would be considered invalid:

BS* 1 

Wildcard rules are particularly useful for alphanumeric postcodes and can be used to target both wide and narrow areas depending on the placement of the wildcard character. For example, this rule:

BS* Will target any postcode in the city of Bristol, United Kingdom. Whereas this rule:

BS13 * 

Will target only properties within a specific postcode district of the city.

With wildcard rules, the placement of spaces is important and can affect the matches that a rule will generate. Take the following rule as an example:


Matches for this rule would include both BS1 1SB and BS11 1SB. However, consider the next rule:

BS1 * 

Note the space after the '1'. The matches for this rule would include BS1 1SB but would not include BS11 1SB. In UK postcodes, the space is a part of the format and is taken into account when wildcard rules are defined. Depending on how specific you wish to make your wildcard rule, you should be careful to use or omit the space - adding a space will result in a more specific rule and omitting it will make the rule match a broader set of postcodes.

Whilst wildcard rules can be used with numeric and pseudo-numeric postcodes, the same results can be achieved in much clearer fashion using the 'span' rule type. Consider this example for an Australian postcode:


Given that Australian postcodes can be either 3 or 4 digits long, this usage of a wildcard is already problematic as it's not really possible to tell whether it should match a 3 or 4 digit postcode. If we assume that the author of this rule was envisaging matches against 4 digit postcodes then the rule above effectively would match any postcode from 1000 to 1099.

Therefore it would be much clearer to write this as a range:


Now we can tell at a glance that the rule targets 4 digit postcodes and we can easily determine the range of values that would be considered a match.

When to use:

You should use a 'wildcard' rule when you want to target a narrow or broad set of alphanumeric postcodes.

When to avoid:

You should avoid using 'wildcard' rules when dealing with numeric or pseudo-numerical postcodes and opt instead for a 'span' type rule for this format types.


'Wildcard span' rules

As the name suggests, a 'wildcard span' rule is a combination of the 'wildcard' and 'span' rule types so it is recommended you review these rules before using wildcard spans as many of the same principles and constraints apply.

A wildcard span rule matches any character from a given position within a postcode within a given span. Take the following example of a wildcard span rule for a Range in the United Kingdom:

BS1 1*-BS1 5* 

This rule will match any postcodes that start BS1 1 to BS1 5. Postcodes outside of this span will not be matched so for example BS1 6AA will not match this rule.

In order to write a valid wildcard span rule you should follow the same guidelines outlined in the 'wildcard' and 'span' rule documentation.

To summarise:

  • Both sides of the span should be a valid format for the country the Range is for.
  • Both sides of the span should be the same format (e.g. BS5*-BS8* is valid whereas BS5*-BS10* is not).
  • The wildcard character must come at the end of each side of the rule (e.g. BS5*-BS8* is valid whereas BS*5-BS*8 is not).
  • There can only be one wildcard character on each side of the span (e.g. BS5*-BS8* is valid whereas BS**-BT** is not).

Wildcard span rules are very useful for alphanumeric postcode formats. They allow you to easily create spans between either numbers or letters. For example, the rule below spans between numbers:


And in the following example, the rule spans between letters:

BS1 8A*-BS 18P* 

Note that it is the the first character that is different between the 'from' and 'to' sides the span that is used to compute whether a given postcode falls within the span. The wildcard character should be positioned just after this character.

In the example below the first difference between the 'from' and 'to' sides of the span is the third character (highlighted):

BS3 1*-BS8 9* 

It is this character that will be used to determine whether a given postcode is within this span - the 4th characters are ignored and essentially replaced with the wildcard character. Therefore a better way of writing the rule above would be:

BS3 *-BS8 * 

Wildcard ranges are unsuited for use with numerical or pseudo-numerical postcode formats. These formats are better expressed as regular span rules.

When to use:

You should use 'wildcard span' rules when you want to target a set of alphanumeric within a given range.

When to avoid:

You should avoid using 'wildcard span' rules when dealing with numeric or pseudo-numerical postcodes and opt instead for a 'span' type rule for this format types.


'Area' rules

An 'area' rule can be used to match against parts of the destination address other than the postcode, or to provide a match where the destination countries where postcodes may be optional or not widely used.

Note: When an area rule is checked against an address field, both the rule and the address are ‘normalised’. Both the rule and the field are made lowercase and any special characters or diacritics are replaced with their non-accented counterparts e.g. 'ê becomes e', 'ü becomes u' etc. This helps to ensure that area rules match the widest possible set of address values.

At the broadest level, an area rule can be used to match the 'province' or 'state' field of a destination address that is entered at checkout:


In the example above the 'state' field of the address would need to match California. Rather than using state as the key, you may also use province or county.

On a more local level you can also specify a rule to match the town or city of a destination address:

city:San Francisco 

Rather than using city as the key you can also use town.

Finally, if the country you are setting the rule for has an informal postcode system (for example, in Chile, some people enter the town name as the postcode), you are free to specify a value that should be matched by the postcode field of a destination address:


Rather than using postcode as the key you can also use zip.

In some cases you may need to make an area rule more specific by matching across more than one address field. For example, you may want to set up an area rule for Springfield, Missouri in the U.S. However, there are several other towns called Springfield in the United States which would also be a match if the rule was simply:


To get around this you may chain area rules together for greater specificity using the '|' character:


You are free to chain any combination of the three 'levels' of area rule together. For instance you could use state and postcode or city and postcode or even state, city and postcode.

In order for an area rule to be considered valid it can contain only one colon ':' character per segment. The following example would be considered invalid because the 'town' rule contains two colon characters:


Also, you must ensure that you are using one of the whitelisted area keys, with the same spelling and case. All three rules in the example below would be considered invalid:

cty:San Francisco 
village:East Meon


When to use:

Area rules are very useful when you wish to target broader regions within a country and you are not too concerned about settings up rates to clearly defined postcode regions. Area rules are also useful to get around quirks' of postcode usage within countries where people sometimes use values other than an actual postcode within the 'postcode' field of address forms.

When to avoid:

Area rules are limited in their specificity and are best used for quickly targeting larger regions. If you need to set up fine grained rates for very specific parts of a city, or if you have specific exclusions that you wish to provide no or special shipping to then an area rule will most likely be too broad.


General tips on creating rules

The flexibility and variety of rules available should mean that most store owners can set up their rules quickly over a relatively small number of lines. Here are some tips to get you started:

  • Read the documentation: The overview of rules in this section is designed to help you decide which rule types are most relevant in your situation. Reading these guides will help you to write shipping rules than are concise and provide faster feedback for your customers.

  • Avoid copy/paste: A common mistake seen when entering rules is for a store owner to copy and paste hundreds of individual postcodes. Whilst it takes a little more work to input these postcodes as spans or wildcard span rules, the rules become a lot more readable and easier to refer to in future and also take less time to compute (meaning that your customers will get shipping rates returned faster).


In this section: