Magento 2: Display Checkout Error Message Via Plugin

Aug 9, 2025 by Mei Lin 53 views

How to Display Error Messages on the Magento 2 Checkout Page Using Plugins

Hey guys! Ever run into a situation where you need to validate something on the checkout page in Magento 2, like a zip code, and then display an error message if it doesn't pass the validation? It's a pretty common scenario, especially when dealing with shipping restrictions or delivery availability. In this article, we're going to dive deep into how you can achieve this using Magento 2 plugins. We'll break down the process step-by-step, making it super easy to follow, even if you're not a Magento 2 guru. So, let's get started!

Understanding the Problem: Validating Zip Codes and Displaying Errors

Let's kick things off by understanding the problem we're trying to solve. Imagine you have a Magento 2 store, and you only deliver to specific zip codes. When a customer enters their zip code during checkout, you need to validate it against your allowed zip codes. If the zip code isn't in your delivery zone, you need to display an error message right there on the checkout page, preventing them from moving forward with the order. This ensures a smooth user experience and avoids any potential order fulfillment issues.

Now, why use a plugin for this? Well, Magento 2 plugins are a powerful way to modify the behavior of existing code without actually changing the core files. This is crucial because modifying core files can lead to upgrade issues and conflicts down the road. Plugins allow us to hook into specific points in the Magento 2 code flow and add our custom logic, making them perfect for this kind of validation scenario.

To effectively validate zip codes and display error messages, we need to consider a few key aspects. First, we need to identify the correct place in the checkout process to hook into. This is usually the shipping address section, as the zip code is entered there. Next, we need to create a plugin that intercepts the request, validates the zip code, and sets an error message if necessary. Finally, we need to ensure that this error message is displayed prominently on the checkout page, preventing the customer from proceeding until the issue is resolved. This involves a combination of PHP code for the plugin logic and potentially some JavaScript or UI components to handle the display of the error message on the frontend.

Step-by-Step Guide: Creating the Magento 2 Plugin

Alright, let's get our hands dirty and start building this thing! We'll break this down into manageable steps, so it's super clear. We'll create a module, set up the plugin, and write the code to validate the zip code and display the error message. Here we go:

1. Create a New Magento 2 Module

First things first, we need to create a new module for our custom functionality. Let's call it DeliveryZipCode. Inside the app/code directory, create the following folder structure: app/code/YourVendor/DeliveryZipCode. Replace YourVendor with your company name or your own name. This is a standard practice in Magento 2 to avoid naming conflicts.

Inside the DeliveryZipCode directory, we need two essential files: registration.php and etc/module.xml. The registration.php file tells Magento 2 that our module exists, and the module.xml file provides module information, such as its name and dependencies.

Create app/code/YourVendor/DeliveryZipCode/registration.php with the following content:

<?php

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'YourVendor_DeliveryZipCode',
    __DIR__
);

This code snippet is pretty standard. It registers our module with Magento 2 using the ComponentRegistrar. Make sure the module name 'YourVendor_DeliveryZipCode' matches your directory structure.

Next, create app/code/YourVendor/DeliveryZipCode/etc/module.xml with the following content:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="YourVendor_DeliveryZipCode" setup_version="1.0.0"/>
</config>

This XML file declares our module and its version. The setup_version attribute is important for database schema and data upgrades, but for this example, we'll keep it simple with 1.0.0.

2. Create the Plugin

Now, let's create the plugin itself. We'll need to define which class and method we want to intercept. In this case, we'll intercept the Magento\Checkout\Model\ShippingInformationManagement class and its saveAddressInformation method. This method is responsible for saving the shipping address information during the checkout process, making it the perfect place to validate the zip code.

Create the app/code/YourVendor/DeliveryZipCode/etc/di.xml file with the following content:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Checkout\Model\ShippingInformationManagement">
        <plugin name="validate_zip_code" type="YourVendor\DeliveryZipCode\Plugin\ShippingInformationManagement" sortOrder="10" disabled="false"/>
    </type>
</config>

This di.xml file is where we declare our plugin. Let's break down the important parts:

<type name="Magento\Checkout\Model\ShippingInformationManagement">: This specifies the class we're intercepting.
<plugin name="validate_zip_code" ...>: This defines our plugin. The name attribute is a unique identifier for the plugin. type specifies the class that contains our plugin logic. sortOrder determines the order in which plugins are executed (lower numbers execute first). disabled allows you to easily disable the plugin without removing it from the configuration.

Next, we need to create the plugin class itself. Create the app/code/YourVendor/DeliveryZipCode/Plugin/ShippingInformationManagement.php file with the following content:

<?php

namespace YourVendor\DeliveryZipCode\Plugin;

use Magento\Checkout\Model\ShippingInformationManagement;
use Magento\Framework\Exception\LocalizedException;
use Magento\Quote\Api\Data\ShippingInformationInterface;
use Magento\Quote\Model\QuoteIdMaskFactory;

class ShippingInformationManagement
{
    protected $quoteIdMaskFactory;

    public function __construct(
        QuoteIdMaskFactory $quoteIdMaskFactory
    ) {
        $this->quoteIdMaskFactory = $quoteIdMaskFactory;
    }

    public function beforeSaveAddressInformation(
        ShippingInformationManagement $subject,
        $cartId,
        ShippingInformationInterface $addressInformation
    ) {
        $shippingAddress = $addressInformation->getShippingAddress();
        $postcode = $shippingAddress->getPostcode();

        // Here you would add your logic to validate the zip code
        $allowedZipCodes = ['10001', '10002', '10003']; // Example zip codes
        if (!in_array($postcode, $allowedZipCodes)) {
            throw new LocalizedException(__('Sorry, we do not deliver to this zip code.'));
        }

        return null; // Important: Return null to proceed with the original method
    }
}

This is where the magic happens! Let's break down this code:

namespace YourVendor\DeliveryZipCode\Plugin;: This is the namespace for our plugin class.
use ...;: These are the necessary classes and interfaces we'll be using.
class ShippingInformationManagement: This is our plugin class.
public function __construct(QuoteIdMaskFactory $quoteIdMaskFactory): This is the constructor where we inject the QuoteIdMaskFactory. This factory is used to handle masked quote IDs (we'll see why later).
public function beforeSaveAddressInformation(...): This is the before plugin method. The naming convention is before + the method name we're intercepting (saveAddressInformation). This method will be executed before the original saveAddressInformation method.
- $shippingAddress = $addressInformation->getShippingAddress();: We get the shipping address from the ShippingInformationInterface.
- $postcode = $shippingAddress->getPostcode();: We extract the zip code from the shipping address.
- $allowedZipCodes = ['10001', '10002', '10003'];: This is an example array of allowed zip codes. You'll need to replace this with your actual zip code validation logic.
- if (!in_array($postcode, $allowedZipCodes)) { ... }: This is where we check if the entered zip code is in our allowed list. If not, we throw a LocalizedException with an error message.
- throw new LocalizedException(__('Sorry, we do not deliver to this zip code.'));: This throws an exception with a user-friendly error message. Magento 2 will catch this exception and display the message on the checkout page.
- return null;: This is crucial! In a before plugin, you must return null to allow the original method to execute. If you return anything else, you'll prevent the original method from running.

3. Enable the Module

Now that we've created our module and plugin, we need to enable it in Magento 2. Open your terminal, navigate to your Magento 2 root directory, and run the following commands:

php bin/magento module:enable YourVendor_DeliveryZipCode
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Let's break down these commands:

php bin/magento module:enable YourVendor_DeliveryZipCode: This enables our module.
php bin/magento setup:upgrade: This runs the Magento 2 setup upgrade process, which registers our module and any database schema changes (we don't have any in this example, but it's a good practice to always run this).
php bin/magento setup:di:compile: This compiles the dependency injection configuration, which is necessary for plugins to work correctly.
php bin/magento setup:static-content:deploy -f: This deploys the static content (CSS, JavaScript, etc.). The -f flag forces the deployment, which is useful after making changes.
php bin/magento cache:flush: This flushes the Magento 2 cache, ensuring that our changes are reflected.

4. Test the Plugin

Alright, the moment of truth! Let's test our plugin. Go to your Magento 2 store frontend, add a product to the cart, and proceed to checkout. Enter a shipping address with a zip code that is not in your allowedZipCodes array in the plugin code. You should see an error message displayed on the checkout page, preventing you from proceeding.

If you enter a valid zip code, you should be able to proceed with the checkout process without any errors.

Advanced Considerations and Best Practices

So, we've got the basic plugin working, which is awesome! But there are always ways to make things even better, more robust, and more user-friendly. Let's dive into some advanced considerations and best practices for our zip code validation plugin.

1. Configuration Options

Hardcoding the allowed zip codes directly in the plugin code, like we did in our example, isn't ideal. It means that every time you want to change the allowed zip codes, you have to modify the code and redeploy the module. A much better approach is to use Magento 2's configuration system. This allows you to define the allowed zip codes in the Magento 2 admin panel, making it easy for store administrators to manage them without touching any code.

To do this, you'll need to create a system.xml file in your module's etc/adminhtml directory. This file defines the configuration sections, groups, and fields. You can then access these configuration values in your plugin using Magento 2's configuration object.

For example, you could create a configuration field where administrators can enter a comma-separated list of allowed zip codes. Your plugin would then retrieve this value, split it into an array, and use it for validation. This approach makes your plugin much more flexible and maintainable.

2. Custom Error Message Placement

The default error message display in Magento 2 is functional, but it might not be the most visually appealing or user-friendly. You might want to customize the placement and appearance of the error message to better fit your store's design and improve the user experience.

One way to do this is to use Magento 2's UI components. UI components allow you to create custom frontend elements, such as error message containers, and integrate them into the checkout page. You can then use JavaScript to dynamically display the error message in your custom container.

Another approach is to use Magento 2's layout system. You can modify the checkout page layout using XML files to insert your custom error message block in a specific location. This gives you more control over the placement of the error message.

3. Asynchronous Validation

Our current plugin validates the zip code synchronously, meaning that the validation happens when the shipping address is saved. This can potentially slow down the checkout process, especially if you have a complex validation logic. A better approach is to perform the validation asynchronously using JavaScript and AJAX.

You can create a custom JavaScript component that sends an AJAX request to a custom Magento 2 controller with the zip code. The controller would then validate the zip code and return a response indicating whether it's valid or not. The JavaScript component would then display the error message if necessary.

This approach has several advantages. First, it doesn't block the checkout process while the validation is happening. Second, it allows you to provide immediate feedback to the customer as they type in the zip code. Third, it reduces the load on the server by only performing the validation when necessary.

4. Third-Party Services

For more advanced zip code validation, you might consider using a third-party service. These services often provide features such as address auto-completion, zip code lookup, and real-time address verification. Integrating with a third-party service can improve the accuracy of your validation and provide a better user experience.

Magento 2 has a robust API that makes it easy to integrate with external services. You can create a custom module that handles the API communication and integrates the service into your checkout process.

5. Testing, Testing, Testing!

This cannot be stressed enough. Always thoroughly test your plugin after making any changes. Test with different zip codes, different scenarios, and different browsers. Use automated testing tools to ensure that your plugin works correctly and doesn't introduce any regressions.

Troubleshooting Common Issues

Even with the best planning, things can sometimes go wrong. Let's look at some common issues you might encounter when developing Magento 2 plugins and how to troubleshoot them.

1. Plugin Not Executing

If your plugin doesn't seem to be executing, the first thing to check is your di.xml file. Make sure the type attribute in the <plugin> tag is correctly pointing to your plugin class. Also, check the sortOrder attribute. If another plugin has a lower sortOrder, it might be intercepting the method before yours.

Another common issue is that the Magento 2 cache might not be cleared. Run php bin/magento cache:flush to clear the cache and try again.

2. Error Message Not Displaying

If your plugin is throwing an exception, but the error message isn't displaying on the checkout page, there might be an issue with the exception handling. Make sure you're throwing a Magento\Framework\Exception\LocalizedException. This is the standard exception type for displaying user-friendly error messages in Magento 2.

Also, check your browser's developer console for any JavaScript errors. There might be a JavaScript error preventing the error message from being displayed.

3. Unexpected Behavior

If your plugin is causing unexpected behavior, the best way to debug is to use Xdebug or a similar debugging tool. This allows you to step through your code line by line and inspect the values of variables. This can help you identify the exact point where the issue is occurring.

Also, check the Magento 2 logs for any errors or warnings. The logs can provide valuable information about what's going wrong.

Conclusion: Mastering Magento 2 Plugins for Checkout Validation

So there you have it, guys! We've covered a lot in this article. We've gone from understanding the problem of validating zip codes on the checkout page to building a fully functional Magento 2 plugin that displays error messages. We've also discussed advanced considerations, best practices, and troubleshooting tips.

By using Magento 2 plugins, you can easily customize the checkout process and add your own validation logic. This allows you to create a more user-friendly and efficient checkout experience for your customers. Remember, plugins are a powerful tool in the Magento 2 ecosystem, and mastering them will greatly enhance your ability to customize and extend your store's functionality.

Keep experimenting, keep learning, and keep building awesome Magento 2 stores!