Address Field Character Replacement
Automatically replace unsupported or accented characters in selected Linnworks order address fields, record the changes in order notes, and update zero-cost items for international orders.
Unsupported, accented, or special characters in customer address fields can cause issues during order processing, label generation, courier validation, and dispatch. The Address Character Replacement macro helps clean selected Linnworks orders by replacing specific characters in shipping and billing address fields with courier-friendly alternatives.
This macro checks selected orders, updates configured address fields where required, and records the original and updated values in an order note. For international orders, it also checks for order items with zero cost and updates those items with a calculated cost value.
With this automated approach, your team can reduce manual address corrections, improve dispatch readiness, and help avoid courier or label errors caused by unsupported characters.
Keep address data courier-ready by automatically replacing unsupported characters and recording every change in the order notes.
Configure the Macro
Once the app is installed, you need to create a macro configuration so the system knows which macro to run and allows it to be selected in the Rule Engine.
This setup can be adjusted anytime based on your operational requirements.
Steps to Configure
Go to Apps > Macro Configuration and click + Add new configuration.
Select the AddressCharacterReplacement macro and click Create Configuration.
In the Macro Configuration screen, add the configuration name.
This macro uses the selected order IDs provided by the Rule Engine. No additional custom parameter values are required.
Make sure to enable the macro to continue with the Rule Engine configuration.
Note: If the macro is not enabled, it will not appear in the Action value list when setting up the rule.
Go to Orders > Rules engine and click + Add new rule.
Enter the rule name and click Create.
Click Add new, select Condition, set the condition as required, and save it.
Use conditions that target orders where address cleanup is required, such as international orders, marketplace orders, or orders ready for dispatch.
Add the macro action and click Save.
In the Add action window, enter the Action name, for example:
AddressCharacterReplacement
-
Set Action type to:
Execute a macro -
In Action value, select:
AddressCharacterReplacement -
Click Save
Note: If the macro is not enabled, it will not appear in the Action value list when setting up the rule.
Review the saved rule setup.
-
Verify the condition and action are connected correctly
-
Click Save in the bottom-right corner to save the rule
Address characters that are not accepted by courier systems can delay fulfilment or cause label generation errors. This macro helps reduce those issues by replacing configured characters automatically and recording the changes for visibility.
Reduce Manual Address Checks
Eliminates the need to manually review selected orders for common accented or unsupported address characters.
Improve Dispatch Readiness
Helps ensure address fields are cleaner before courier validation, label generation, or dispatch processing.
Record Every Address Change
Adds an order note showing which fields changed and what the old and new values were.
Clean Shipping and Billing Fields
Updates selected shipping and billing address fields where configured characters are found.
Support International Orders
Checks international orders for zero-cost items and updates those item costs.
Update Only When Needed
The macro updates customer information only when at least one configured address character is replaced.
How It Works
The macro checks each selected order, replaces configured characters in specific address fields, records any changes in a note, and updates zero-cost items for international orders.
Step 1
The macro starts execution and writes Macro Started to the log.
Step 2
It loops through each order ID provided in the OrderIds parameter.
Step 3
For each order, the macro retrieves the order details using the Linnworks Orders API.
Step 4
If the order cannot be found, the macro logs Order Is Null and moves to the next order.
Step 5
The macro checks selected address fields and replaces configured characters such as accented letters and commas.
Step 6
When a field is changed, the macro adds the change details to a note in the format field changed from old value to new value.
Step 7
If any address changes were found, the macro updates the customer information on the order.
Step 8
The macro adds an order note containing the address changes and sets CreatedBy to Address Character Replacement.
Step 9
The macro checks whether the order country is different from United Kingdom.
Step 10
For international orders, it finds order items where Cost is 0.0 and updates the item cost values.
Step 11
The macro logs address updates, cost updates, skipped UK orders, and writes Macro Finished when execution ends.
Usage of App
This macro is designed to update selected orders automatically through the Rule Engine. It is useful before dispatch, courier validation, label generation, or any workflow where clean address data is required.
OrderIds
Defines the Linnworks order IDs that should be processed. Only these selected orders are checked and updated.
Shipping Address1
The macro checks and updates the first shipping address line when configured characters are found.
Shipping Address2
The macro checks and updates the second shipping address line when configured characters are found.
Shipping Town
The macro checks and updates the shipping town field when configured characters are found.
Billing Address1
The macro checks and updates the first billing address line when configured characters are found.
Billing PostCode
The macro checks and updates the billing postcode field when configured characters are found.
Full Name
The macro checks and updates the shipping full name field when configured characters are found.
International Zero-Cost Item Update
For orders where the shipping country is not United Kingdom, the macro updates items that have a cost of 0.0.
Execution Logging
The macro records address updates, no-change results, international cost updates, errors, and completion status using the macro logger.
Character Replacement Rules
The macro replaces the following configured characters:
| Original Character | Replacement |
|---|---|
| á | a |
| à | a |
| â | a |
| ä | a |
| ã | a |
| å | a |
| ā | a |
| ç | c |
| é | e |
| í | i |
| ñ | n |
| ó | o |
| ú | u |
| ý | y |
| ž | z |
| ß | ss |
| œ | oe |
| æ | ae |
| , | space |
Key Points to Remember
-
The macro processes only the order IDs provided in OrderIds
-
The macro is intended to run from the Rule Engine
-
Address fields are updated only when configured characters are found
-
Empty address fields are ignored
-
Every changed field is recorded in an order note
-
The order note is created by Address Character Replacement
-
The macro updates customer information only when the note contains at least one change
-
The macro checks international orders separately after address processing
-
An order is treated as international when the shipping country is not United Kingdom
-
For international orders, zero-cost items are updated
-
The macro does not update UK order item costs
-
The configured replacements are case-sensitive and only include the characters defined in the code
Once the macro is running, it helps ensure selected orders have cleaner address data before fulfilment.
What You Can Expect
-
Unsupported address characters are replaced
Configured accented characters are replaced with courier-friendly equivalents. -
Commas are removed from configured address fields
Commas are replaced with spaces. -
Address changes are recorded
The macro adds a note showing each changed field, including the original and updated values. -
Orders without address changes are skipped for customer updates
If no configured characters are found, the customer information is not updated. -
International zero-cost items are updated
For non-UK orders, items with Cost = 0.0 are updated with calculated cost values. -
Execution is logged
The macro records when it starts, updates addresses, skips changes, updates costs, encounters errors, and finishes.
Overall Impact
This macro improves address data quality, reduces manual corrections, and helps prevent fulfilment delays caused by unsupported characters in customer address fields. It also supports international order handling by updating zero-cost items where required.
What To Do After the Macro Runs
After the macro has completed, review the selected orders if needed to confirm that address characters were replaced and notes were added correctly.
Steps to Follow
Step 1
Open Linnworks and locate the orders processed by the rule.
Step 2
Open an affected order and review the shipping and billing address fields.
Step 3
Confirm that accented or unsupported characters were replaced with the configured alternatives.
Step 4
Review the order note created by Address Character Replacement.
Step 5
For international orders, review any zero-cost items if required.
Step 6
Continue with normal order validation, picking, packing, label generation, or dispatch processing.
Why This Matters
Keeping address data clean helps:
-
Reduce courier validation issues
-
Prevent label generation problems
-
Avoid manual address correction
-
Improve dispatch readiness
-
Make address changes traceable through order notes
-
Support international order processing
Best Practices
To get the most value from this macro, use it before courier allocation, label generation, or dispatch.
Recommended Guidelines
-
Run before dispatch
Use the macro before shipping labels are generated so address fields are cleaned before courier validation. -
Use clear rule conditions
Configure the Rule Engine so the macro runs only for orders where address cleanup is required. -
Review sample orders first
Test a small batch of orders to confirm the replacements work as expected. -
Check order notes
Use the generated note to confirm exactly which fields were changed. -
Review international order handling
Confirm that zero-cost item updates match your operational and accounting requirements. -
Extend replacements carefully
If more characters need replacing, update the replacement dictionary in the macro code and test before using widely.
Troubleshooting
No address was updated
Confirm that the selected order contains one of the configured characters in the fields checked by the macro.
Expected character was not replaced
Check whether the character is included in the replacement dictionary. The macro only replaces the characters defined in the code.
Macro is not visible in the Rule Engine
Confirm that the macro configuration has been created and enabled in Apps > Macro Configuration.
No order note was created
A note is created only when at least one address field is changed.
International item costs were not updated
Confirm that the shipping country is not United Kingdom and that the order contains items with Cost = 0.0.
UK order item costs were not changed
This is expected. The macro logs Not an International Order for orders where the shipping country is United Kingdom.
Summary
The Address Character Replacement macro checks selected Linnworks orders for configured unsupported or accented characters in specific shipping and billing address fields. When changes are found, it updates the customer information and records the old and new values in an order note.
For international orders, it also checks for zero-cost items and updates their cost values. This helps improve address quality, dispatch readiness, and operational consistency before fulfilment.
Last updated 5 days ago
Built with Documentation.AI