Checkout fields and country address rules

Every field the checkout form draws, in the order it draws them, with the three condition documents that decide when each is required, when it is hidden and what a valid answer is — plus the attribute vocabulary those conditions may be written against. Fields owned by core are the shipped checkout: they can be reordered, relabelled, required, hidden or turned off, and they cannot be deleted. Read this before writing any condition; an attribute not on the published list is refused by name rather than quietly matching nothing.

Add a field to the checkout form. The key is lowercase snake_case, or vendor/name for an add-on's own, and it is what the answer is stored under on every order. required, hidden and validation are condition documents in KahunaCart's own condition language — the same one sales, coupons and payment methods use — written against the attributes list_checkout_fields publishes; a validation document also needs a message_key saying what to tell a customer whose answer is refused. Null means the condition is absent, so a null required is never required; a container with no children is always true, so an empty required is always required.

Change a checkout field. Only the fields you send are written. A core field can be reordered, relabelled, required, hidden or turned off like any other — what it cannot be is deleted. Sending null for required, hidden or validation clears that condition.

Delete a field a merchant or an add-on added. A core field is refused with a 409 and a sentence saying to turn it off instead: the shipped checkout is expressed in those rows, and a store that deleted billing_city would be a store that cannot take an address. Answers on every order that already carry the field keep their value and their label, because an order records what happened rather than what the store currently asks.

What one country expects of a postal address: the layout it prints in, the postcode grammar, the phone grammar and which address fields it will not do without. A country nobody has seeded answers the generic rules rather than a 404, which is exactly what checkout uses for it, so this is never an error. effective_address_format is the layout that would actually be used — the row's own, else the shipped table, else the default — while address_format is only what the row itself carries.

Fix one country without waiting for a release. A postcode pattern that refuses valid post, a required-field set that insists on a postcode in a country that has none, an address printing in the wrong order on an invoice — each is one row here. Patterns are regular expressions without delimiters, matched case-insensitively; an empty pattern accepts anything, including nothing. Clearing address_format puts the shipped layout back. restore: true returns every value to what this release ships. Nothing here affects any other country.