Shopify External Reference Update

Manually copying values from order XML into the External Reference Number can be time-consuming and increases the risk of missed or inconsistent order references. The Automated XML Note Mapping to External Reference for Nexus Wholesale Orders macro helps keep Linnworks order references accurate by automatically extracting the value from the XML Note node and applying it to the order External Reference Number.

This macro checks selected Linnworks orders, validates that each order belongs to the configured SubSource, reads the first available order XML record, extracts the Note value, and updates the order reference. If an existing External Reference Number is already present, the previous value is backed up as an internal order note before the update is applied.

With this automated approach, your team can reduce manual reference updates, preserve important historical values, and improve order traceability across operational workflows.

Keep external references aligned with marketplace XML data while preserving previous reference values for audit visibility.

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

Order reference information can be important for fulfilment, marketplace checks, customer service, and internal tracking. This macro helps reduce manual checks by copying the relevant XML Note value into the External Reference Number field.

How It Works

The macro checks each selected order and updates the External Reference Number only when a valid XML Note value is found and the order matches the configured SubSource.

Usage of App

This macro is designed to run against selected orders through the Rule Engine. It is useful when orders need the XML Note value copied into the External Reference Number field automatically.

OrderIds

Defines the Linnworks order IDs that should be processed. These are supplied by the Rule Engine when the macro action runs.

SubSource

Defines the required order SubSource. Orders with a different SubSource are skipped and no update is made.

XML Note Node

The macro searches the order XML for a node named Note and uses its value as the new External Reference Number.

External Reference Number

The order field updated by the macro after the XML Note value is extracted and validated.

Internal Order Note Backup

If the order already has an External Reference Number, the old value is saved as an internal order note before the new value is applied.

Execution Logging

The macro records skipped orders, successful updates, and errors using the macro logger.

Key Points to Remember

• The macro processes only the order IDs provided in OrderIds

• The macro checks whether the order SubSource matches the configured SubSource

• Orders with a different SubSource are skipped

• The macro reads the first available order XML record

• The macro searches the XML for a Note node

• The XML Note value is trimmed before use

• If the XML Note value is longer than 100 characters, only the first 100 characters are used

• The External Reference Number is updated only when the new value is different from the current value

• If an old External Reference Number exists, it is backed up as an internal order note

• The macro checks whether the same backup note already exists before adding it again

• Orders with no XML, empty XML, invalid XML, or no Note node are skipped

Once the macro is running, it helps keep order references aligned with XML order data while preserving previous values for audit visibility.

What You Can Expect

• Matching orders are checked automatically
  Orders passed by the Rule Engine are validated against the configured SubSource.

• XML Note values are extracted
  The macro parses the order XML and reads the Note node value.

• External Reference Number is updated
  Valid XML Note values are written to the order External Reference Number field.

• Previous references are preserved
  Existing External Reference Numbers are backed up into internal order notes before being replaced.

• Orders without valid XML Note data are skipped
  If XML is missing, empty, invalid, or does not contain a Note node, no update is made.

• Execution is logged
  The macro records start, skipped orders, successful updates, errors, and finish messages.

Overall Impact

This macro improves order reference accuracy, reduces manual updates, and helps teams keep important XML reference data visible in Linnworks order records.

What To Do After the Macro Runs

After the rule has triggered the macro, review selected orders if needed to confirm that the XML Note value has been copied into the External Reference Number field.

Steps to Follow

Why This Matters

Keeping XML reference values mapped into the External Reference Number helps:

• Reduce manual order editing

• Improve order reference accuracy

• Preserve previous reference values

• Support fulfilment and customer service workflows

• Make source reference information easier to find

• Help teams process relevant marketplace orders more efficiently

Best Practices

To get the most value from this macro, use it with rule conditions that target only the orders where XML Note mapping is required.

Recommended Guidelines

• Use clear rule conditions
  Configure the Rule Engine so the macro runs only for orders where XML Note mapping is relevant.

• Set the correct SubSource
  Enter the exact SubSource value expected on the orders you want this macro to process.

• Validate sample XML first
  Confirm that the order XML contains a valid Note node before using the macro across a large order set.

• Review sample orders after setup
  Confirm that the External Reference Number is updated correctly before enabling the rule for wider use.

• Check skipped orders in the logs
  Review log messages for SubSource mismatch, missing XML, invalid XML, or missing Note nodes.

• Avoid repeated rule execution where possible
  The macro skips updates when the External Reference Number already matches the XML Note value, but rule conditions should still be configured carefully.

Troubleshooting

External Reference Number was not updated

Confirm that the order SubSource matches the configured SubSource value.

Order has no XML records

Confirm that XML data exists for the order before expecting the macro to update the reference.

XML parsing failed

Check whether the XML content is valid and can be parsed.

No Note node was found

Confirm that the order XML contains a node named Note.

Macro is not visible in the Rule Engine

Confirm that the macro configuration has been created and enabled in Apps > Macro Configuration.

Old reference was not added to notes

Confirm that the order had an existing External Reference Number before the macro update. If the same backup note already exists, the macro does not add it again.

Rule did not run

Confirm that the rule condition matches the order and that the rule has been saved and enabled.

Example Scenario

If an order has:

• SubSource: Nexus Wholesale

• Current External Reference Number: OLD-REF-1001

• XML Note value: NW-PO-4567

And the macro is configured with:

• SubSource: Nexus Wholesale

Then the macro will:

• Validate that the order SubSource matches

• Extract NW-PO-4567 from the XML Note node

• Add an internal order note:

  Old External Reference Number :- OLD-REF-1001

• Update the External Reference Number to:

  NW-PO-4567

Summary

The Automated XML Note Mapping to External Reference for Nexus Wholesale Orders macro checks selected Linnworks orders, validates the configured SubSource, extracts the XML Note value, and updates the External Reference Number when valid data is found.

By running through the Rule Engine, this macro helps teams automate order reference updates, reduce manual work, preserve previous values, and improve order traceability across the fulfilment workflow.