> For the complete documentation index, see [llms.txt](https://docs.rishvi.co.uk/linnworks/llms.txt).
> Use it to discover all available pages before exploring further.
# Shopify External Reference Update
Extract the Note value from Linnworks order XML and automatically update the order External Reference Number. Preserve previous references in order notes and process only matching SubSource orders through the Rule Engine.
## Overview
Shopify External Reference Update is an automated order-reference management solution for Linnworks. It extracts the value stored in the order XML **Note** node and applies it to the order **External Reference Number**.
The macro processes selected orders supplied through the Linnworks Rule Engine. It validates that each order belongs to the configured **SubSource**, retrieves the first available XML record, parses the XML, and searches for a valid **Note** value.
Before replacing an existing External Reference Number, the macro preserves the previous value in an internal order note. It also avoids unnecessary updates when the current External Reference Number already matches the extracted XML Note value.
> Keep Linnworks external references aligned with marketplace XML data while preserving previous reference values for audit visibility.
## Who Should Use Shopify External Reference Update
Teams responsible for processing and dispatch can use the macro to ensure marketplace reference information is available directly on the Linnworks order.
Customer service teams can use the updated External Reference Number to locate and verify source order information more quickly.
Administrators configure the required SubSource, enable the macro, create the Rule Engine action, and monitor execution logs.
Operations teams benefit from consistent reference mapping and preserved historical values when an existing reference is replaced.
## Key Features
Retrieves the first available order XML record and extracts the value from the XML Note node.
Processes only orders where the order SubSource matches the configured SubSource value.
Writes the extracted XML Note value into the Linnworks External Reference Number field.
Saves the existing External Reference Number as an internal order note before replacing it.
Skips the update when the current External Reference Number already matches the XML Note value.
Logs skipped orders, missing XML, invalid XML, missing Note nodes, successful updates, and errors.
## How Shopify External Reference Update Works
Shopify External Reference Update runs through a defined sequence every time it processes one or more orders. The macro is triggered through the Linnworks Rule Engine and receives the relevant order IDs automatically.
The macro reads each order ID supplied through the `OrderIds` parameter and retrieves the corresponding order details from Linnworks.
The order SubSource is compared with the configured `SubSource` value. Orders with a different SubSource are skipped.
The macro retrieves the order XML and reads the first available XML record associated with the order.
The XML is parsed and searched for a node named **Note**. The extracted value is trimmed before use.
The Note value is limited to a maximum of 100 characters. Empty values, invalid XML, and XML without a Note node are skipped.
If the order already has a different External Reference Number, the previous value is preserved in an internal order note.
The validated XML Note value is written into the order External Reference Number and the result is recorded in the macro log.
## 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 Shopify External Reference Update macro and click Create Configuration.**
This creates a new configuration where the macro can be enabled and used by the Rule Engine.
**In the Macro Configuration screen, add the configuration name and required parameter value.**
This macro uses the selected order IDs provided by the Rule Engine.
Configure the required parameter:
- **SubSource** — enter the order SubSource that should be processed, for example:
`Nexus Wholesale`
Orders with a different SubSource are skipped.
**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.**
Choose the condition that identifies the orders where the XML Note value should be mapped into the External Reference Number.
**Add the macro action and click Save.**
In the **Add action** window, enter the **Action name**, for example:
Shopify External Reference Update
- Set **Action type** to:
`Execute a macro`
- In **Action value**, select:
`Shipping Delivery Note`
- 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
## Key Benefits
Manually copying XML Note values into Linnworks order references can take time and create inconsistent results. Shopify External Reference Update applies the same validation and update process to every selected matching order.
> Reduce manual reference updates, preserve previous values, and keep important marketplace reference information visible in Linnworks.
Removes the need to manually open each selected order and copy the XML Note value into the External Reference Number.
Updates the External Reference Number directly from the validated Note value contained in the order XML.
Validates the configured SubSource before applying changes so unrelated orders are skipped.
Stores the old External Reference Number in an internal order note before replacing it.
Skips the order when the existing External Reference Number already matches the XML Note value.
Keeps previous reference values available in the Linnworks order notes for future review.
## Usage of App
Shopify External Reference Update is triggered through the **Linnworks Rule Engine** to automatically map XML Note values into the External Reference Number.
### Execution
Call the Shopify External Reference Update macro through the Rule Engine with the required `OrderIds` and configured `SubSource`. No additional manual action is required once the rule is active.
### Outcome
When the macro runs against an order, it:
Confirms that the order SubSource matches the configured SubSource value before continuing.
Reads the first available XML record associated with the selected Linnworks order.
Parses the XML, locates the Note node, trims its content, and limits the final value to 100 characters.
Saves the existing External Reference Number in an internal order note when a different previous value exists.
Writes the validated XML Note value into the order External Reference Number.
Logs successful updates, skipped orders, missing data, XML validation issues, and errors.
## Input Parameters
Shopify External Reference Update requires the following inputs before it can process orders:
| Parameter | Required | Description |
| ------------- | -------- | ----------------------------------------------------------------------------------------- |
| **OrderIds** | Yes | The Linnworks order IDs to process. Passed through the Rule Engine trigger. |
| **SubSource** | Yes | The exact order SubSource that is allowed to be processed, for example `Nexus Wholesale`. |
The following processing rules are built into the macro:
| Rule | Description |
| ----------------------------- | -------------------------------------------------------------------------------------------- |
| **First XML record** | The macro processes the first available XML record returned for the order. |
| **Note node** | The macro searches the XML for a node named **Note**. |
| **Maximum reference length** | The extracted Note value is limited to 100 characters. |
| **Reference comparison** | No update is made when the current External Reference Number already matches the Note value. |
| **Previous reference backup** | A different existing reference is preserved in an internal order note. |
| **Duplicate note prevention** | The same previous-reference backup note is not added again when it already exists. |
## Best Practices
> Accurate SubSource configuration and valid XML data are essential for reliable external-reference updates.
Enter the precise SubSource value used by the intended orders. Orders with a different value are skipped.
Confirm that sample orders contain valid XML with a populated Note node before enabling the macro at scale.
Configure Rule Engine conditions so only orders requiring XML Note mapping are passed to the macro.
Run the macro against a small selection of orders and confirm the External Reference Number and backup notes are correct.
Review logs for SubSource mismatches, missing XML, invalid XML, empty Note values, and successful updates.
Confirm that previous External Reference Numbers are preserved correctly before relying on the macro in a live workflow.
## FAQ
**How is Shopify External Reference Update triggered?**
The macro is triggered through the Linnworks Rule Engine. When an order matches a configured rule, the relevant `OrderIds` are passed to the macro automatically.
**What configuration values are required?**
The macro requires a `SubSource` value. The order IDs are supplied automatically by the Rule Engine.
**Which orders are processed?**
Only orders where the order SubSource exactly matches the configured `SubSource` value are processed.
**Where does the new External Reference Number come from?**
The macro retrieves the first available order XML record, searches for a node named **Note**, and uses its value as the new External Reference Number.
**What happens if the Note value is longer than 100 characters?**
Only the first 100 characters are used.
**What happens when the External Reference Number already matches the Note value?**
The macro skips the update because no change is required.
**Is the old External Reference Number preserved?**
Yes. When a different existing External Reference Number is present, it is saved in an internal order note before the new value is applied.
**Can the same backup note be added more than once?**
The macro checks whether the same backup note already exists and avoids adding it again.
**What happens if the order has no XML?**
The order is skipped and the result is recorded in the macro log.
**What happens if the XML is invalid?**
The XML cannot be processed, so the order is skipped and the error is logged.
**What happens if the XML does not contain a Note node?**
No External Reference Number update is made.
**What happens if the Note node is empty?**
The order is skipped because there is no valid value to apply.
**Does the macro process more than one XML record?**
The documented behaviour uses the first available XML record returned for the order.
**Does the macro overwrite the old reference without recording it?**
No. A different existing reference is preserved in an internal order note before the update.
## Legal Information
- **Privacy Policy:** [https://rishvi.co.uk/privacy-policy/](https://rishvi.co.uk/privacy-policy/)
- **Terms and Conditions:** [https://rishvi.co.uk/terms-conditions/](https://rishvi.co.uk/terms-conditions/)
Please review these pages to understand how data is handled and the terms governing the use of this application.
## Summary
Shopify External Reference Update automates the mapping of XML Note values into the Linnworks External Reference Number.
Once configured with the required SubSource and connected to the Rule Engine, the macro validates each selected order, retrieves the first XML record, extracts the Note value, preserves any previous reference, and updates the order when valid data is available.
The first available order XML record is parsed automatically to locate the Note node.
Only orders matching the configured SubSource are eligible for an update.
Existing External Reference Numbers are saved as internal order notes before replacement.
Valid XML Note values are written directly into the External Reference Number field.
For orders that cannot be updated, review the Rule Engine and macro logs, confirm that the SubSource matches, and verify that the first order XML record contains a valid Note node.