Checkout Fields

Add your own fields to the Magento checkout without code: a delivery date, an order comment, a PO number, "How did you hear about us?" and anything else your shop needs to know. Values are checked on the server, saved with the order and shown on the admin order page, in the order grid, in the customer account, in order emails and on the invoice PDF. This guide covers installation, every setting and day-to-day use.

• Demo (Luma): https://demo.softawarecommerce.com/radiant-tee.html (add the product to the cart and go to checkout)
• Demo (Hyvä, Luma checkout fallback): https://demo.softawarecommerce.com/hyva/radiant-tee.html
• Admin demo: https://demo.softawarecommerce.com/try-admin/checkout-fields
• Changelog: Release notes · Questions: FAQ

The demo store has four fields (Delivery date, Order comment, PO number and a "How did you hear about us?" dropdown) and values on ten demo orders, so the admin demo shows the order grid columns and the Checkout Fields box on the order page. PO number is limited to the Wholesale customer group, so storefront visitors see the other three.

1. Requirements

Hyvä Checkout (the separate commercial checkout) is not supported. The customer account, guest order and print views have Hyvä templates.

2. Installation

Install with Composer from repo.softawarecommerce.com. Your access keys and the full set-up are described at https://softawarecommerce.com/shop/composer-access/.

composer config repositories.softaware composer https://repo.softawarecommerce.com
composer config --auth http-basic.repo.softawarecommerce.com PUBLIC_KEY PRIVATE_KEY
composer require softaware/module-checkout-fields
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

Installing adds three example fields, all switched off, so your live checkout does not change: Delivery date, Order comment and PO number (PO number only for the Wholesale customer group, if that group exists). On Hyvä, run your usual Tailwind build after installing; the module registers itself for Hyvä's Tailwind source scanning.

To update later: composer update softaware/module-checkout-fields, then the same bin/magento commands.

3. Quick start

1. Go to Softaware > Checkout Fields > Manage Fields.
2. Tick the example fields you want, choose Actions > Enable, or open one and adjust it first.
3. Or click Add New Field, enter a label and a code, pick the type and the position, and click Save Field.
4. Add a product to the cart on the storefront and go to checkout: the field appears in the step you chose.
5. Place a test order and open it under Sales > Orders: the values are in the Checkout Fields box.

4. Settings

Stores > Configuration > Softaware > Checkout Fields (also under Softaware > Checkout Fields > Settings). Both settings can be set per website and store view.

If you use custom email templates, set Add to Order Emails Automatically to No and place the block where you want it:

{{layout handle="softaware_checkout_fields_email" order_id=$order_id area="frontend"}}

5. Managing fields

Softaware > Checkout Fields > Manage Fields lists every field with label, code, type, position, sort order, required, status and store views. Search by keyword (label or code), filter, and use Actions to enable, disable or delete several fields at once. The form is split into sections in the order a field is set up.

General

Text Input (text and text area)

Options (dropdown, radio buttons, multiple-choice checkboxes)

Click Add Option for each choice and enter its value and label. Option labels can be translated per store view.

Delivery Date

Delivery days are calendar days. The calendar in the checkout only offers allowed days, and the server checks the date (and the time slot) again when the order is placed.

Who Sees the Field

Labels per Store View

A label for each store view, for example "Wie haben Sie von uns erfahren?" on a German store view. Empty means the default label. Placeholder and tooltip use the same text on every store view.

Where the Value Is Shown

The admin order page always shows the values to users with the "View Values on Orders" permission.

6. In the checkout

Fields appear in the Luma checkout at the position you chose, sorted by sort order. Required fields are marked like Magento's own fields and are checked before the customer moves on to the next step.

Values are saved on the cart as the customer goes through the checkout and are checked on the server: unknown field codes, values for fields the customer cannot see, HTML, options that do not exist and dates that are not allowed are refused. When the order is placed, required fields and delivery date rules are checked again, and the values are copied to the order together with the label and the value as shown.

The fields follow the checkout layout on phones. Hyvä stores show the same fields through the Hyvä Luma Checkout fallback.

7. Values on orders

Order page

Sales > Orders > (order) shows a Checkout Fields box with every value of the order. Users with the "Edit Values on Orders" permission click Edit Values, change or add values and click Save Values. Delivery date rules and required fields are not checked here, so your team can record what was agreed with the customer. Each change is noted in the order comments (not visible to the customer). Cancel closes the form without saving.

Order grid

Every field with Order Grid Column = Yes adds a column to Sales > Orders. Use Columns to show or hide it, filter and sort by it, and export it with Magento's CSV and Excel XML export. Dates are stored as YYYY-MM-DD, so they sort in date order. Exported values that start with =, +, - or @ get a leading apostrophe, so spreadsheet programs do not run them as formulas.

Customer account, emails and invoice PDF

Fields with Show to Customer = Yes appear on the order page in the customer account, the guest order view and the print view (Luma and Hyvä), and below the items in order, invoice and shipment emails. Fields with Show on Invoice PDF = Yes are printed on the invoice PDF.

Old orders

Each order keeps its own copy of the label and the shown value. Renaming a field, changing an option label or deleting a field does not change orders that were already placed.

8. REST and GraphQL

REST, values of a cart (the Luma checkout uses these endpoints too):

GET  /V1/guest-carts/:cartId/softaware-checkout-fields      (masked cart ID, guest carts only)
PUT  /V1/guest-carts/:cartId/softaware-checkout-fields      {"values": [{"code": "delivery_date", "value": "2026-10-14"}]}
GET  /V1/carts/mine/softaware-checkout-fields               (customer token)
PUT  /V1/carts/mine/softaware-checkout-fields               {"values": [...]}

Values are text; option values separated by commas; 1 for a ticked checkbox; YYYY-MM-DD for dates; YYYY-MM-DD <time slot> for delivery dates with time slots. An empty value removes it. Values sent are saved, other values of the cart stay. Guest endpoints only accept active carts without a customer.

Orders (GET /V1/orders/:id, GET /V1/orders) include extension_attributes.softaware_checkout_fields (code, label, value, display_value) for integrations with the "View Values on Orders" permission.

GraphQL:

query { softawareCheckoutFields(cart_id: "MASKED_ID") { code label type position required value } }

mutation { setSoftawareCheckoutFieldValues(input: { cart_id: "MASKED_ID",
  values: [{ code: "order_comment", value: "Please ring twice" }] }) { fields { code value } } }

query { customer { orders { items { number softaware_checkout_fields { code label value display_value } } } } }

Cart access follows Magento's rules: guest carts for guests, customer carts only for their customer, current store only. Required fields and delivery date rules are checked again by placeOrder.

9. CLI

bin/magento softaware:checkout-fields                                     # list all fields
bin/magento softaware:checkout-fields delivery_date order_comment --enable
bin/magento softaware:checkout-fields po_number --disable

10. Permissions

System > Permissions > User Roles > Role Resources, under Softaware > Checkout Fields:

11. Troubleshooting

A field does not appear in the checkout. Check that the module and the field are enabled, and that the field allows the current store view, the customer's group (NOT LOGGED IN for guests) and, if set, the selected shipping method. Fields of the shipping step are not shown when the cart has only virtual or downloadable products. Flush the cache after changes.

The calendar offers no days. The earliest and latest day, the weekdays and dates without delivery and the cut-off time may leave no allowed day in the range. Increase Latest Delivery or leave it empty.

The order grid column is missing. Check Order Grid Column on the field, then open Columns in Sales > Orders: a saved grid view may have the column hidden. The user also needs "View Values on Orders".

Values are missing in emails. Check Show to Customer on the field and Add to Order Emails Automatically. With a custom email template, add the layout handle shown in section 4.

An order has no values. Orders created in the admin (Create New Order), through multi-address checkout, Instant Purchase, an integration or PayPal Express started from the cart do not go through the checkout fields. Required fields never block those orders; add values afterwards with Edit Values.

12. Limitations

• Admin order creation has no checkout fields; use Edit Values on the order page afterwards.
• Multi-address checkout, Instant Purchase and Hyvä Checkout (commercial) are not supported.
• If a guest signs in during checkout, values already saved on the guest cart are not moved to the customer's cart.
• Values are not copied by Reorder and are not shown on shipment or credit memo PDFs.
• No file upload field type.

13. Data and privacy

Values are stored in softaware_checkout_field_quote (carts, deleted with the cart) and softaware_checkout_field_order (orders, deleted with the order). Deleting a customer does not delete their orders in Magento, so the values stay with those orders until the orders are deleted. Do not create fields that ask for sensitive data you do not need.

14. Uninstall

bin/magento module:disable Softaware_CheckoutFields
composer remove softaware/module-checkout-fields
bin/magento setup:upgrade
bin/magento cache:flush

The fields and the values are stored in the tables softaware_checkout_field, softaware_checkout_field_quote and softaware_checkout_field_order. Back up the database before you uninstall if you want to keep the values, and check afterwards whether the tables are still there; drop them yourself once you no longer need them.