Installation Instructions for Magento 2 (Backend Address Validation)

This module was developed in close collaboration with our partner agency Parc Network developed. Parc Network is an experienced Magento agency that supports online stores with Magento development, custom extensions, and the implementation of complex projects.

Functional description #

What does the module do?

Unlike our front-end modules for Shopware, JTL & Co. The validation here does not take place while the customer is entering information at checkout, but rather automatically afterward—via a cron job directly in your Magento backend.

The endereco backend module for Magento 2 automatically checks the shipping addresses of your incoming orders in the background using the endereco API. Orders with problematic addresses are flagged for manual review. This keeps your fulfillment process running smoothly and helps you avoid delivery issues before they arise.

Core functions

Automatic background checking

• A cron job checks for new orders with the order status you've configured
• Each shipping address is sent to the endereco API and processed
• No customer interaction required—the verification process is fully automated

Reliable blocking in case of problems

• Ambiguous or incorrect addresses are flagged for manual review
• You can choose to have unambiguous corrections applied automatically
• Addresses with additional information (e.g., apartment number) can always be specifically marked for review

Transparent Data Management

• The original address, API suggestion, and manual correction are stored separately
• All changes can be traced at any time for audits and CSV exports
• Fully customizable CSV export directly from the order form

Business Benefits for You as a Store Owner

• Fewer delivery problems: Incorrect addresses are identified before the goods are shipped
• Lower returns rate: Fewer undeliverable mailings due to incorrect or incomplete addresses
• Less manual work: The module automatically corrects minor typos and formatting differences
• Full Control: You decide for yourself which types of errors result in a lockout and which are automatically corrected
• Clean Database: Standardized, verified addresses are available for CSV export and integration with connected systems

Functions in detail #

Here's how the exam works

1. A cron job checks for new orders with your configured order status at regular intervals.
2. Each shipping address is sent to the endereco API for verification.
3. Depending on the result, one of two things will happen:
   • The order will be required to take the exam, if the address is ambiguous, contains an address suffix, or returns a critical status, or
   • The address will be automatically corrected, if the result is unambiguous and automatic overwriting is enabled.
4. All results are stored in the database—the original address, the API suggestion, and any manual corrections.

Requirements #

• Magento 2.4 or later
• An active endereco account with a valid API key → Request an API key here
• Enabled cron jobs in your Magento installation

Installation #

Note for Live Shops: Lead setup:upgrade On a production store, always use the flag –keep-generated from:

php bin/magento setup:upgrade --keep-generated

Without this flag, Magento deletes and regenerates all automatically generated code during the update. This can result in a brief period of downtime for your customers. The flag ensures that the existing generated code is preserved and that the update runs without interruption. This flag is not necessary in development or staging environments.

Installation via ZIP File

1. Extract the ZIP file to app/code/Parc.

2. Activate the module:

php bin/magento module:enable Parc_AddressValidation

3. Install the database updates:

php bin/magento setup:upgrade

4. Clear the cache:

php bin/magento cache:flush

Installation via Composer

1. Deploy the module via a Composer repository, for example:

• private repository repo.magento.com
• public repository packagist.org
• public GitHub repository as a VCS

2. Add the Composer repository:

composer config repositories.repo.magento.com composer https://repo.magento.com/

3. Install the module:

composer require parc/module-addressvalidation

4. Activate the module:

php bin/magento module:enable Parc_AddressValidation

5. Install the database updates:

php bin/magento setup:upgrade

6. Clear the cache:

php bin/magento cache:flush

Request access data #

The module only works with a valid API key, which you can get from us. If you haven't received one yet, you can request it for free here: Request API Key

Configuration of the module #

You can then find the configuration in the Magento backend under Stores → Configuration → endereco Backend Address Validation → Address Validation.

„Enabled“ – turns the module on or off.

„API Key“ – your endereco API key.

„Cron Schedule“ – Specifies how often the test job runs (default: */10 * * * *, i.e., every 10 minutes). Make sure the interval is long enough so that one run is completed before the next one starts. For more information, see Cron Interval and Parallel Runs.

„Order Status“ – Specifies which order statuses are used for verification. Select the statuses that fit your ordering process—typically the status that new orders have before order processing begins. Common statuses include Pending or Processing. You can select multiple options.

„Validation Hold Status“ – the status assigned to orders when they need to be reviewed manually. We recommend using a separate status for this. See Create a Custom Status for Address Validation.

„Sharpness“ – Specifies which API status codes result in an order being put on hold (Classification A/B/C). Explained in detail at Sharpness – When Orders Are Paused.

„Check additional info“ – If enabled, orders with additional address information (e.g., apartment number) will always be held for review.

„Auto-Overwrite Address“ – When enabled, unique API corrections are automatically written back to the native Magento address fields. You should enable this option if your shipping or fulfillment extension accesses the native Magento address fields directly (e.g., street, ZIP, City). This ensures that minor API corrections are also applied there. You can leave it disabled if you use your own shipping connector that retrieves the validated address independently from the table parc_addressvalidation or from the CSV export of this module. In this case, the native fields are irrelevant.

„CSV Column Mapping“ – Specifies which fields are included in the CSV export and which database tables they come from. Explained in detail at CSV Column Mapping.

Technical Details #

Attributes

The module stores the test data in the table parc_addressvalidation. A record is created for each order that contains three versions of the shipping address listed side by side.

Metadata

Original Address (orig_*) – the address entered by the customer at checkout

API Proposal (api_*) – the correction suggested by the endereco API

Manual Correction (manu_*) – correction made by an admin user

Priority When applying or exporting an address: manual correction → API suggestion → original.

Check Pending Orders

If an order is on hold due to an address validation issue, you can review and correct it directly in the Magento admin panel:

1. Go to Sales → Orders and open the order.
2. At the top of the order details page, you'll see the Invoice- and Shipping Address, exactly as the customer entered it.
3. Scroll to the section Validated Shipping Address. Here, the address is pre-filled with the API's suggestion and displayed broken down into individual fields. The API automatically separates the street name and house number, even if the customer entered them together (for example, 4a Balthasar-Neumann Street in Balthasar Neumann St. and 4a (broken down as follows):
   • House number
   • Street
   • Postcode
   • Place
   • Address suffix
4. Check the fields and make corrections if necessary.
5. Use one of the three buttons to continue:

„Save“ – saves your changes to the inspection record without applying them to the order just yet.

„Save as shipping address“ – saves your changes and immediately sets the address as the shipping address for the order.

„Restore original shipping address“ – Rejects the API suggestion and the manual correction, and restores the address originally entered by the customer.

6. Once the address is correct, click at the top of the page on Monster, to put the order back into processing.

Priority with the Fiend: Manual correction → API suggestion → Original address

CSV Export of Verified Addresses

1. Go to Sales → Orders.
2. Use the checkboxes to select the orders you want.
3. Select in the Actions-Dropdown Export Validated Addresses (CSV).
4. The file is saved with the settings specified under CSV Column Mapping downloaded with the configured columns.

CSV Column Mapping

The CSV export is fully customizable—you decide which columns appear in the file and what they're called. You can set up the mapping in two steps under Stores → Configuration → endereco Backend Address Validation → Address Validation one.

Step 1: Select the relevant tables

First, specify which database tables the export can retrieve data from. Three tables are available:

You can select one or all three tables. Save this selection before continuing. The tables selected here determine which columns will be available in Step 2.

Step 2: Define Column Mapping

Once the tables have been selected, you can set up the column mapping. Each row in the mapping defines a column in the CSV file:

• Column Header – the label that appears in the CSV header (e.g.,. Order Number, Validated ZIP). Your choice.
• Data – the value shown in this column, selectable from a drop-down menu with two groups:

Group 1 – Verified Address Fields

Always provide the best available address—manual corrections take precedence over the API suggestion.

Group 2 – Direct Database Columns

Each column from the tables selected in Step 1 is available here, displayed as table_name.column_name (e.g.,. sales_order_grid.increment_id). This allows you to display any order details alongside the verified address.

Sample Mapping

This mapping displays the original shipping address (at the time of the check) next to the best-verified address—useful for a before-and-after comparison or for integrating with an external fulfillment system.

Note: The orig_*–The fields capture the shipping address at the time the cron job first processed the order. The validated-Fields always provide the best available address—manual corrections take precedence over the API suggestion.

The CSV export uses ; as a column separator.

Sharpness – When Orders Are Paused #

The Sharpness-This setting controls how strictly the module filters addresses. An order is held for review as soon as any of the following conditions are met:

1. The API returns a status code that you have marked as critical.
2. The address includes an additional element (e.g., apartment number) and Check additional information is enabled.
3. The API returns more than one possible address (this rule is always active and cannot be disabled).

Configurable Status Codes

The endereco API returns a set of status codes for each verified address. You specify which of these codes are considered critical. For any order in which a critical code appears, the order is held for review.

The available codes are grouped by address component:

Check additional information

If this option is enabled, any address that includes additional information (e.g., apartment number, floor, c/o) will always be flagged for verification, regardless of the returned status codes.

Recommended Setting

A good starting point that reliably catches serious problems while automatically allowing minor corrections to pass through:

Mark as critical (order will be put on hold):

• address_not_found
• address_multiple_variants
• address_major_correction
• building_number_is_missing
• building_number_not_found

Do not mark as critical (automatic correction when Auto-Overwrite is enabled):

• address_minor_correction
• postal_code_minor_correction
• street_name_minor_correction
• building_number_minor_correction

This way, clearly incorrect or undeliverable addresses are flagged for manual review, while minor typos or formatting differences are automatically corrected—without any effort on your team's part.

Create a Custom Status for Address Validation #

By default, you can set the Magento status held Use this as the "Validation Hold" status. However, we recommend creating your own status (e.g.,. Address Validation Pending), so that orders with address issues are clearly separated from other suspended orders. This makes it much easier to filter and export only the affected orders in a CSV file.

Step 1: Create a new status

1. Go to Stores → Settings → Order Status.
2. Click on Create New Status and fill in the fields:
   • Status Code – internal identifier, lowercase with underscores, e.g.,. address_validation_pending. Cannot be changed after saving.
   • Status Label – the name displayed in the admin panel, e.g.,. Address Validation Pending.
3. Click on Save Status.

Step 2: Set the status to „On Hold“

1. Click on Assign Status to State.
2. Specify:
   • Order Status – Select your new status.
   • Order Status - On Hold (held) Select this option. This is necessary because the module internally sets the order status to held sets this when an order is put on hold.
   • Use Order Status as Default – Activate this only if you want this status to completely replace the default hold status.
3. Click on Save Status Assignment.

Step 3: Configure the module

1. Go to Stores → Configuration → endereco Backend Address Validation → Address Validation.
2. Set Validation Hold Status to your new status (Address Validation Pending).

Orders held by the module now appear under a separate status. This makes filtering in the order grid and targeted CSV exports much easier.

Cron Interval and Parallel Runs #

Note: This is a known limitation that will be fixed in a future version. Until then, please follow this recommendation.

The verification cron job processes all orders that have not yet been verified in a single run. If the interval is set too short and a run takes longer than the interval, multiple instances of the job may start simultaneously. This can result in two runs processing the same order at the same time, which may lead to the following:

• duplicate entries in the table parc_addressvalidation
• Duplicate order comments
• The order is put on hold twice

What you can do until the issue is resolved:

Set the cron interval so that one run is guaranteed to complete before the next one starts. A safe starting point is 10 minutes (*/10 * * * *). If your order volume is high, you should increase the interval even further.

To estimate a confidence interval, check under System → Action Logs, how long the last runs took, or track your progress, which cron_schedule-Table for the job parc_addressvalidation to check.

Configuration: Stores → Configuration → endereco Backend Address Validation → Address Validation → Cron Schedule.

Common Problems #

Orders are not reviewed.

• Check whether the module is located under Stores → Configuration → endereco Backend Address Validation → Address Validation is enabled.
• Check to see if your API key is entered correctly.
• Make sure the orders have the status configured under „Order Status.“.
• Check whether cron is running on your server (if in doubt, ask your hosting provider).

All orders are held for review.

• Check your Sharpness-Setting. A stricter setting results in more orders being flagged.
• Check whether Check additional information is enabled and whether your customers frequently provide apartment numbers.

The corrected address is not applied after unlocking.

• Make sure you've saved the address correction before unlocking the order.

We hope you have success using our module! We welcome your feedback, suggestions, and comments—that’s the only way we can continue to improve our services for you.

If you have any questions we will be happy to help you! Simply send an e-mail to: support@endereco.de or call: 0931 66 39839 – 0

Your endereco team