Magento 2: New custom address fields are shown on checkout, but not saved in DB

Magento 2: New custom address fields are shown on checkout, but not saved in DB

August 12, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Magento 2: New custom address fields are shown on checkout, but not saved in DB

Debugging Magento 2 Custom Checkout Fields: Common Mistakes and Solutions

If you’re facing issues with custom fields on the Magento 2 checkout not being saved to the database or missing from other address forms, you’ve likely encountered common configuration pitfalls during implementation. Let’s dive into troubleshooting this issue step-by-step.

Understanding the Problem Scope

The most likely culprits for your problem lie in the setup and configuration of the custom fields. You mentioned using a Plugin as recommended by the official Magento docs guide on adding new checkout fields. While this approach is valid, it requires precise implementation to function correctly across all relevant areas of the Magento frontend.

Checking Your Custom Attribute Setup

Before proceeding with code-level troubleshooting, ensure that your custom attributes are configured correctly in the backend:

  1. Navigate to Stores > Attributes > Customer Addresses.
  2. Locate your custom fields and verify they have been enabled.
  3. Check if they are assigned to the correct customer address attribute set.

Issues with Plugin Implementation

The first challenge lies in how you’ve implemented the plugin for the checkout form. Let’s review some common issues:

Incorrect Form Element ID

Ensure that the Magento_Checkout/js/customer-address-form script is being used correctly to identify your new fields. The element ID should match the field name exactly.

Example: Correct usage

checkoutForm = Element.find('Magento_Checkout/js/customer-address-form');
fieldName = 'your_field_name';

Example: Incorrect usage (wrong ID)

checkoutForm = Element.find('customer-address-form'); // Wrong ID

Missing Dependencies

Check if you’ve included all necessary dependencies in your plugin. Ensure that the Magento_Checkout/js/customer-address-form is being loaded before your script.

Example: Correct dependency setup

define([
    'jquery',
    'Magento_Customer/js/customer-data',
    'Magento_Checkout/js/customer-address-form'
], function ($, customerData) {
    ...
});

Example: Incorrect dependency (missing required library)

define([
    'jquery',
    'Magento_Customer/js/customer-data'
], function ($, customerData) {
    ...
});

Addressing Missing Fields on Other Forms

The second part of your issue involves the custom fields not appearing on the “My Account” address forms.

Custom Form Elements in Magento 2

To ensure that your new fields appear consistently across all address forms, use the Magento\Customer\Block\Address block to add them programatically. This block is responsible for rendering the customer’s address form and includes methods like addField which allow you to add custom elements.

Example: Adding a field to the customer address form

$context = $this->getContext();
$block = $this->customerAddressFormBlockFactory->create(
    ['data' => [
        'name_in_form' => $context->getElementNameInForm($field),
        'form_name' => $context->getCheckoutPostCodeName() . '.shipping_address.' . $this->addressHelper->getFieldName($attribute)
    ]]
);
$block->addField(
    $this->scopeConfigInterface->getValue('general/Developer/Developer/IsActive'),
    'custom_field',
    [
        'name' => $context->getCheckoutPostCodeName() . '.shipping_address.' . $this->addressHelper->getFieldName($attribute),
        'label' => __($attribute->translateLabel()),
        'input_name' => $context->getCheckoutPostCodeName() . '.shipping_address.' . $this->addressHelper->getFieldName($attribute)
    ]
);
return $block;

Conclusion and Further Reading

Debugging Magento 2 custom checkout fields often involves meticulous review of plugin configurations, dependencies, and backend settings. Remember to double-check the ID matching between your script and form elements.

For a comprehensive guide on extending the checkout process in Magento 2, refer to our in-depth article at Laravel Company’s official Magento blog.

In this post, we covered:

  1. The importance of correct attribute configuration.
  2. Common mistakes in plugin implementation for custom fields.
  3. Ensuring consistency across different address forms.

By following these guidelines and thoroughly reviewing your code against the examples provided, you should be able to resolve the issue with custom checkout fields not being saved or appearing inconsistently.

Magento 2 Checkout Database Extensions

Our network