Checkout fields

You can edit every checkout field. This page explains how store administrators can customize the default form and how developers can add fields through an add-on.

New fields appear in the existing checkout form.

What a checkout field is

A checkout field is a control the customer fills in while placing an order, with rules about when it appears and what counts as an answer.

A custom field is different: it is a typed value stored on a record, such as a supplier code an operator types on an order afterwards. It is never collected from a shopper.

A VAT number typed at checkout is a checkout field. A supplier reference added later is a custom field. An answer collected at checkout does not become a filterable column of the order list.

The shipped fields

Every built-in checkout field has a record owned by core. Upgrading preserves the existing fields, their order and their markup.

A core field can be reordered, relabelled, required, hidden or switched off. It cannot be deleted: the API answers a delete with a 409 and tells you to switch it off instead. The two company lines and the billing phone ship switched off.

Add a field

1. In the admin, open KahunaCart → Checkout and select the Fields panel.
2. Select New field. Give it a key, a label key, a type and a section.
3. Set Required when, Hidden when and Valid when if the field needs any of them. Each is the same condition builder sales and payment methods use.
4. Select Create field.

The field is on the checkout on the next page load.

To hide a built-in field, switch Enabled off. To reorder, change Position: the shipped fields are spaced by ten, so there is room between any two.

The three conditions

required, hidden and validation are written in the same condition language as sales, coupons and payment methods.

A document is a container of all, any or none, holding conditions and other containers. Each condition is an attribute, an operator and a value.

Empty and unset mean different things:

validation is written as the condition that holds when the answer is good. The refusal is its opposite.

The attributes you can test

The list is closed. An attribute not on it is refused by name when you save the field. GET /kahunacart/checkout-fields serves the list with every label translated, and the admin's condition builder is drawn from it.

A money condition is in a currency. On a store that sells in more than one currency cart_subtotal carries a currency beside its value, the store's own when it is missing, and it is false on an order in any other. A field required over 50.00 in dollars is not required on a euro order unless it also has a condition in euro, in an any container. The checkout field screen is read-only, so write it through the API. See Rules and conditions.

A namespaced key folds its slash to a double underscore, so acme/delivery_date is asked about as field_acme__delivery_date.

A condition on another field reads what was submitted, in one pass, so the answer never depends on field order and cannot loop. A field the customer cannot see reads as empty.

An empty box is not a posting, so a field the resolver hides after the customer changed their country on the same page does not turn a blank into a refused order.

Declare a field from an add-on

Subscribe to onKahunaCartRegisterCheckoutFields and register onto the registry.

public static function getSubscribedEvents(): array
{
    return ['onKahunaCartRegisterCheckoutFields' => ['onKahunaCartRegisterCheckoutFields', 0]];
}

public function onKahunaCartRegisterCheckoutFields(Event $event): void
{
    $event['registry']->register([
        'key' => 'vat_number',
        'owner' => 'kahunacart-eu-vat',
        'type' => 'text',
        'section' => 'billing',
        'position' => 65,
        'label_key' => 'PLUGIN_KAHUNACART_EU_VAT.NUMBER',
        'required' => [
            'container' => 'all',
            'children' => [
                ['attribute' => 'billing_country', 'operator' => 'in', 'value' => ['DE', 'FR', 'NL', 'IE']],
                ['attribute' => 'field_is_business', 'operator' => 'eq', 'value' => '1'],
            ],
        ],
    ], 'kahunacart-eu-vat');
}

The declaration is written into the field table on the first request that reads it. The field survives your add-on being switched off, and a merchant's edits survive it being switched back on.

A malformed declaration costs itself and nothing else. It is logged with a sentence explaining what is wrong, and the checkout still renders.

Where a value is stored

A core address field's answer goes into the order's billing or delivery address. Switching billing_company on puts a company on the invoice.

Everything else lands in the order's checkout-field data, one entry per field, each carrying the value and the label key that was on the field when the order was placed:

{
  "vat_number": {
    "value": "DE123456789",
    "label_key": "PLUGIN_ACME_VAT.NUMBER",
    "type": "text",
    "section": "billing",
    "position": 65
  }
}

The label travels with the value, so an invoice printed years later still says what the number beside it was, whatever happened to the field since.

In a theme

The checkout template renders every control through one partial, partials/kahunacart-checkout-field.html.twig. Override that file to restyle every checkout control at once. Keep the name and the value: a control posting a name the resolver did not offer is refused.

A theme that overrides the checkout template itself should draw the field model section by section through that partial too, or fields you add here never appear on its checkout. The Kahuna theme does this since 1.0.8, with a Kahuna-styled override of the partial: fields you add, the company line once it is switched on, and fields from add-ons such as the newsletter opt-in all appear, and a field is shown, required or hidden exactly as your rules say for the address the shopper has entered. Before 1.0.8 it drew its own fixed set of inputs.

The checkout template has four named regions, kahunacart_checkout_notices, kahunacart_checkout_express, kahunacart_checkout_fields and kahunacart_checkout_shipping. See Theming.

A section holding exactly one field takes that field's label as its legend and draws the control unlabelled, as the order-notes fieldset does. Autocomplete tokens are declared, not guessed, so a browser never fills a "delivery instructions" box with a street address.

API reference

MCP tools: list_checkout_fields, create_checkout_field, update_checkout_field, delete_checkout_field.

Configuration

Related

• Countries and addresses - the other half of the address form, and where required-by-country comes from
• Rules and conditions - the condition language these three documents are written in
• Theming - the named regions and the field partial
• Storefront - the checkout page itself
• Events - every onKahunaCart* event
• Custom fields and the settings store - the other kind of extra field, and which one you want
• Storefront JSON API - the JSON checkout the same rules apply to