ZIP/PIN Code Validation at Checkout for Magento 2
Checks the postcode a customer types at Magento 2 checkout and in address forms against ZIP and PIN code ranges per country. 83 ranges for ten countries are preloaded. Blocking the order on the server is optional and off by default.
- Free
- Themes listed: Hyvä + Luma
composer require mage2kishan/module-zipcode-validation
- Package requirementsRead the source documentation
- Developer profileView Upwork profile
- Themes listedHyvä + Luma
- PHP versions listed8.1, 8.2, 8.3, 8.4
- Installation questionsDiscuss your store setup
What it does for your store
The main features, as listed in the module documentation.
-
Ranges per country
Numeric and alphanumeric ranges per country with an optional state code. A country with no active range accepts every code.
-
Inline AJAX check
The checkout postcode is checked 800 ms after the last change; other storefront forms are checked on change and blur.
-
Region and format checks
The code must match the selected region, and built-in format rules apply for India, the US, Canada and the UK.
-
Preloaded ranges
83 ranges for India, the US, UK, Canada, Australia, Germany, France, Italy, Spain and the Netherlands on first install.
-
Optional order blocking
Off by default. When on, shipping information and order placement are rejected from storefront, REST and GraphQL.
-
Admin grid and JSON
A ranges grid with search, filters and mass delete, a JSON export and a JSON import endpoint.
Installation
Example commands from the Magento root. Follow the package instructions and your staging and deployment process.
- 1Check the releaseMatch Magento, PHP, theme and dependency requirements.
- 2Install on stagingReview Composer changes and follow the package instructions.
- 3Configure and verifyUse the documented settings and test the affected features.
$ composer require mage2kishan/module-zipcode-validation $ bin/magento setup:upgrade $ bin/magento setup:di:compile $ bin/magento setup:static-content:deploy -f $ bin/magento cache:clean
Listed requirements
These are the details supplied in this listing. Confirm the selected release supports your Magento edition, PHP and storefront.
| Magento versions listed | 2.4.6, 2.4.7, 2.4.8 |
|---|---|
| PHP versions listed | 8.1, 8.2, 8.3, 8.4 |
| Themes listed | Hyvä, Luma |
| Composer package | mage2kishan/module-zipcode-validation |
Documentation
Product details and setup guidance. Check the package repository for release-specific instructions.
Postcode checks against your delivery ranges
Panth Zipcode Validation checks the postal code a customer types into a Magento 2 address form against ZIP and PIN code ranges stored in the database. The check runs as an AJAX request while the customer is still on the form, so a problem shows before the order is placed. It is for merchants who deliver only to defined postal areas.
Where it checks
- Checkout: a mixin on the standard postcode field checks the code 800 ms after the last change to postcode, country or region.
- Customer address book, registration and other storefront forms with a postcode field, on change and blur.
- Each check can be switched on or off for checkout, customer account and registration.
How codes are matched
- Ranges are looked up per country. If a country has no active range, every code for that country passes.
- Numeric ranges are compared as numbers; alphanumeric ranges such as UK or Canadian codes are compared in natural order, and full UK postcodes by their outward code.
- When a region is selected, the code must belong to a range for that region; otherwise the message names the region the code belongs to.
- Format rules: Indian PIN codes must be six digits and not start with 0, US ZIP codes 5 or 9 digits, Canadian codes A1A 1A1, and UK codes a full postcode.
Blocking orders
By default the scripts only show messages, so a customer can still submit the form. Turn on Enforce on Shipping Information and Order Placement to reject the shipping step and order placement from the storefront, REST and GraphQL when the shipping postcode is outside the active ranges. Enable it only after your ranges cover every postcode you deliver to, because a missing range blocks checkout for that area.
Ranges
- On first install 83 ranges are added for India, the United States, the United Kingdom, Canada, Australia, Germany, France, Italy, Spain and the Netherlands. Review them before you rely on them.
- Manage ranges in an admin grid with search, filters, edit and mass delete.
- Export all ranges as JSON, and import a JSON array through the admin import endpoint.
- Ranges are global: the same ranges apply to every store view.
Abuse protection
The check endpoint allows 60 requests per IP address per 5 minutes by default.
Themes
The storefront code targets Luma and Luma-based themes that use the RequireJS and Magento UI checkout. The page script is removed on Hyvä themes.
Requirements
- Magento Open Source or Adobe Commerce 2.4.4 to 2.4.8.
- PHP 8.1, 8.2, 8.3 or 8.4.
- mage2kishan/module-core, installed by Composer.
Free and open source under the MIT License.
Developer notes
- Module:
Panth_ZipcodeValidation. PHP namespace:Panth\ZipcodeValidation. - Validation service:
Model\PincodeValidatorwithvalidate(string $pincode, ?string $regionId = null, string $countryId = 'IN'): arrayandgetStateByPincode(string $pincode, string $countryId = 'IN'): ?string.Helper\Datawraps the same calls asvalidateZipcode(),validateIndianPincode()andgetStateByPincode(). - Storefront check:
Controller\Validate\Pincode, served atzipcodevalidation/validate/pincode. - Order enforcement:
Plugin\ShippingInformationPluginonMagento\Checkout\Model\ShippingInformationManagementandPlugin\QuoteSubmitPluginonMagento\Quote\Model\QuoteManagement, both callingModel\OrderAddressValidatorand declared inetc/di.xmlfor all areas. - Admin route:
zipcodevalidation, controllers underController\Adminhtml\Range, including the POST only JSON endpointzipcodevalidation/range/import. The ACL resourcePanth_ZipcodeValidation::configguards the configuration section, all menu entries, the grid data source and every admin controller. - Table
panth_zipcode_range:range_id,country_id,state_code,state_name,zip_start,zip_end,is_active,created_at. - The module declares no observers, cron jobs, web API routes, widgets or console commands.
| Module Category | Cart & Checkout |
|---|---|
| Best For | All Sizes |
Questions before you install?
Send me your composer.json and I will check for conflicts first. Free. Installation is +$45, custom work is quoted first.