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 for the destination countries where postcodes may be optional or not widely used.


Area rules are defined using a 'key' (e.g. state,city,postcode) and a 'value' - one or more characters that you want to match.

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:

state: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.

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:

postcode:Alcones

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

Finally you can also match the first or second line of the destination address using these keys:

Address line 1 - address_1, address1, address_line_1, addressline1

Address line 2 - address_2, address2, address_line_2, addressline2

Valid usage

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:

province:ProvinceName|town:My:Town

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

State:California

village:East Meon

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. ê => e, ü => u etc. This helps to ensure that area rules match the widest possible set of address values.

Combination area rules

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 city:Springfield.

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

state:Missouri|city:Springfield

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

Partial place names

In some circumstances you may want to match only part of an address field. For example you might want to match any destination addresses where the first line of the address contains the word 'Sunset'.

You can do this using square brackets to specify a partial place name:

address_1:[sunset]

This rule would match addresses such as '1 Sunset Street', 'Apt 3 Sunset Boulevard' or 'Sunset House'.

You can use multiple words within a partial if you need to e.g. [sunset street]. You are also free to use partials in combination area rules if required.

Area rules are very useful when you wish to target broader regions within a country and you are not too concerned about setting 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.

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


Related articles: