Skip to content
KahunaCart

Powered by Grav CMS + Helios Theme

Countries and addresses

Each country has editable address rules: line order, postcode and phone patterns, and required fields. This page explains how to change those rules and which countries have predefined values.

The four values

Value What it decides Empty means
Address format The order the lines print in, on the invoice, the packing slip, the credit note, the address book and the admin order detail The shipped layout for that country, else the default
Postcode pattern Whether a postcode is accepted at checkout Anything is accepted, including nothing
Phone pattern The same, for a phone number Anything is accepted
Required fields Which address fields the customer must fill in Address line 1, city and postcode

Important

A country with no row is never an error. It uses the generic layout, no patterns and the generic required set.

Which countries carry values

Every one of the 249 countries has a row. Values are filled in for two groups:

  • The thirty largest ecommerce markets: US, CN, GB, JP, DE, FR, KR, CA, IN, AU, BR, ES, IT, MX, NL, RU, ID, TR, SE, PL, CH, BE, AT, DK, NO, IE, SG, AE, NZ and ZA.
  • Every country your tax zones and shipping zones name. These have a record you can edit, even when no predefined values are supplied.

Everything else gets an empty row. Fill one in when you need it. It takes effect on the next request.

The postcode patterns follow each country's real rules. AE has none, because the United Arab Emirates has no postcode system. IE has an Eircode pattern but does not require one.

The phone patterns are a format check, not a numbering plan. Every seeded country gets the same rule: an optional +, then digits and the punctuation people type between them. Set a stricter rule for a country if your store needs one.

Address formats are not copied into rows. Around sixty layouts ship in code, and a country's address_format stays empty until you edit it. Empty means "use the shipped layout".

The token list

A format is one line per printed line, with placeholders in braces:

TXT
{name}
{company}
{address1}
{address2}
{postcode} {city}
{country}
Token What it prints
{name}, {company} The recipient
{address1}, {address2} The street lines
{city} The city
{region} The subdivision's name where the store knows it, otherwise what was entered
{region_code} Its ISO 3166-2 code
{postcode} The postcode
{country} The country's English name
{country_code} Its ISO code

Every token has an upper-case twin, such as {city_upper} and {country_upper}, for postal services that ask for one.

An empty token vanishes along with the punctuation around it, so {city}, {region_code} {postcode} with no region prints Boston 02101. A line with nothing left on it is dropped.

One formatter draws every address: the checkout review, the receipt, the invoice, the packing slip, the credit note, the admin order detail and the address book. In Twig the same lines come from kahunacart_address_lines(address).

Which layout wins

Three layers, most specific first:

  1. address.formats in kahunacart.yaml.
  2. The country's own address_format row, edited in the admin.
  3. The shipped table, and under that address.default_format or checkout.locale_fallback_format.

Required fields, and when they apply

A country's required set names address fields without a section prefix, such as address1, city, postcode and region. One row governs the billing address and the delivery address alike.

Important

A country's required fields only apply when the cart holds something that has to be delivered. A cart of downloads checks out with no address at all. A required condition you put on a checkout field yourself still applies to both.

Fix one country

  1. In the admin, open KahunaCart → Checkout and switch to the Countries panel.
  2. Look the country up by its two-letter code.
  3. Edit the postcode pattern, the phone pattern, the required fields or the address format. Patterns are regular expressions without delimiters, matched case-insensitively. Leave one empty to accept anything.
  4. Select Save.

The change takes effect on the next request, for that country only.

Select Restore shipped values to put a country back to what this release ships. This also clears an address format you typed in.

Caution

A pattern that will not compile is refused when you save it, and is ignored if it somehow reaches the checkout. A stray bracket never makes every address in one country invalid.

API reference

Route Permission What it does
GET /kahunacart/countries kahunacart.orders.manage or kahunacart.customers.view Every country an address may name, as code and name, and under regions the states of the countries that list them. The admin's address forms draw their lists from it
GET /kahunacart/countries/{code}/locale kahunacart.products.manage One country's four values, plus the layout that would actually be used
PUT /kahunacart/countries/{code}/locale kahunacart.products.manage Change them, or send restore: true to put the shipped values back

MCP tools: list_countries, get_country_locale, update_country_locale.

A country with no row answers the read with the generic values rather than a 404. The first save creates the row.

Configuration

Key Default Effect
checkout.locale_enabled true Set to false and no postcode pattern, phone pattern or per-country required field applies. Layouts still apply