> 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. # Amazon Customisation Automatically extract Amazon order customisation details from order XML, validate the Amazon order reference, and add the customisation values as order notes in Linnworks. Amazon customised orders can contain important buyer-selected personalisation details that need to be visible during fulfilment, picking, packing, or customer service review. When these details are stored inside Amazon XML data or customisation URLs, teams may need to open and inspect order XML manually. The *Amazon Customisation Details Note* macro helps make this information easier to access by extracting customisation values from Amazon order XML and adding them directly into Linnworks order notes. This macro checks each selected order, validates that the Amazon order ID in the XML matches the Linnworks channel reference, retrieves the buyer customisation data, and creates a note containing the SKU, label, and selected input value. > Keep Amazon customisation details visible by automatically copying buyer-selected values into Linnworks 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, when to run it, and which XML fields should be extracted. 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 Amazon Customization macro and click Create Configuration.**

This creates a new configuration where you can define the required parameter values. **In the Macro Configuration screen, add the configuration name and parameter values.**

Configure the required parameters, including: - **xmlnodelist** **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 Amazon orders where buyer customisation details may be present. **Add the macro action and click Save.**

In the **Add action** window, enter the **Action name**, for example: `AmazonCustomisationDetailsNote` - Set **Action type** to: `Execute a macro` - In **Action value**, select: `AmazonExtractDetails_new` - 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 Amazon customisation details can be important for fulfilment accuracy, especially when products require buyer-selected names, text, colours, options, or other personalisation values. This macro helps reduce manual checks by extracting the required values and adding them to the order notes. Eliminates the need to manually inspect Amazon order XML to find customisation details. Adds buyer customisation details into order notes so they are easier to view during fulfilment. Confirms the Amazon order ID in the XML matches the Linnworks channel reference before creating notes. Helps warehouse and packing teams see SKU-specific personalisation details directly on the order. Skips orders that already contain a note created by the same macro. Adds the order despatch date as an extended property when the expected despatch-date property is not already available. ### How It Works The macro checks selected orders, validates the Amazon XML order reference, extracts customisation data, and adds the result as an order note. The macro starts execution and writes **Macro Start - Orders to Process** to the log. It loops through each order ID provided in the **OrderIds** parameter. For each order, the macro retrieves the order details using the Linnworks Orders API. The macro checks whether a despatch-date extended property name exists. If it does not, it adds a **Despatch Date** extended property using the order **DespatchByDate** value. The macro retrieves existing order notes and checks whether the order was already processed by **Add Note From AmazonXMLDataExtract macro**. If the order was already processed, the macro skips that order. The macro retrieves the order XML using the Linnworks Orders API. It reads the Amazon order ID from the XML path **/OrderWithItems/Order/AmazonOrderId** and compares it with the Linnworks channel reference. If the Amazon XML order ID does not match the Linnworks channel reference, the macro skips note creation for that order. If the order reference matches, the macro reads the buyer customisation URL from **BuyerCustomizedInfo/CustomizedURL**. The macro sends the customisation URL to the external XML extraction endpoint and retrieves the customisation XML data. The macro uses the configured **xmlnodelist** parameter to select customisation nodes from the returned XML. For each selected node, the macro extracts the **label** and the input value. The input value can come from **inputValue**, **text**, or **optionValue**. The macro creates note lines in the format **SKU : label - input value**. If note content was created and the same note does not already exist, the macro adds the note to the order. The macro logs any errors 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 when Amazon personalised or customised order data needs to be visible in Linnworks order notes. Defines the Linnworks order IDs that should be processed. Only these selected orders are checked and updated. Defines the comma-separated XML node paths used to select customisation nodes from the returned customisation XML. Defines a comma-separated list of field names that the macro reads from each selected XML node. The macro reads this value from **/OrderWithItems/Order/AmazonOrderId** and compares it with the Linnworks channel reference before processing notes. The macro reads this value from each Amazon order item and sends it to the external XML extraction endpoint. Customisation details are added to the order note in the format **SKU : label - input value**. The macro adds a **Despatch Date** extended property using the order **DespatchByDate** value when the expected property name is not found. The macro records processing details, skipped orders, XML parsing issues, API failures, and completion status using the macro logger. ### **Key Points to Remember** - The macro processes only the order IDs provided in **OrderIds** - The macro is intended to run from the Rule Engine - The macro retrieves order XML from Linnworks - The Amazon XML order ID must match the Linnworks channel reference - Orders with mismatched references are skipped - Orders already processed by **Add Note From AmazonXMLDataExtract macro** are skipped - The macro reads customisation URLs from **BuyerCustomizedInfo/CustomizedURL** - The macro uses an external API endpoint to fetch the customisation XML - The note format is **SKU : label - input value** - The input value can come from **inputValue**, **text**, or **optionValue** - Notes are created with **Internal** set to **false** - The note creator is set as **Add Note From AmazonXMLDataExtract macro** - The macro checks whether the same note already exists before adding it - XML parsing failures are logged and do not stop the full macro run Once the macro is running, it helps ensure Amazon customisation details are visible directly in Linnworks order notes. ### **What You Can Expect** - **Amazon customisation details are added to order notes**\ Matching customisation data is extracted and saved as a non-internal order note. - **SKU-specific details are included**\ Each note line includes the SKU followed by the customisation label and selected value. - **Mismatched XML data is skipped**\ If the Amazon order ID in the XML does not match the Linnworks channel reference, the macro skips note creation. - **Previously processed orders are skipped**\ Orders with an existing note created by this macro are not processed again. - **Despatch date may be stored as an extended property**\ The macro can add a **Despatch Date** extended property based on the order despatch date. - **Execution is logged**\ The macro records when it starts, processes orders, encounters issues, and finishes. ### **Overall Impact** This macro improves visibility of Amazon personalisation data, reduces manual XML checks, and helps fulfilment teams process customised orders more accurately. ### What To Do After the Macro Runs After the macro has completed, review the affected orders to confirm that Amazon customisation details have been added to the order notes. ### **Steps to Follow** Open Linnworks and locate the Amazon orders processed by the rule. Open an affected order and review the order notes. Confirm that the note contains lines in the format **SKU : label - input value**. Review the note details against the customised product requirements. Continue with normal picking, packing, fulfilment, or customer service processing. ### **Why This Matters** Keeping Amazon customisation details visible helps: - Reduce manual order XML checks - Improve fulfilment accuracy for personalised items - Make buyer-selected customisation values easier to find - Prevent missed personalisation details - Support picking, packing, and customer service workflows ### Best Practices To get the most value from this macro, configure rule conditions and XML parameters carefully. ### **Recommended Guidelines** - **Use clear Amazon order conditions**\ Configure the Rule Engine so the macro runs only for Amazon orders where customisation details may exist. - **Configure xmlnodelist carefully**\ Make sure the XML node paths match the structure returned by the customisation XML. - **Use comma-separated values**\ Enter multiple XML node paths or dynamic fields as comma-separated values. - **Review sample orders first**\ Test the macro on a small number of customised Amazon orders before wider use. - **Check macro logs**\ Review logs for skipped orders, XML reference mismatches, parsing failures, or external API errors. - **Avoid repeated processing**\ The macro skips orders already processed by the configured creator name, helping prevent duplicate note creation. ### **Troubleshooting** Confirm that the order contains Amazon order XML and that the XML includes a valid **CustomizedURL** value. Check whether the Amazon order ID in the XML matches the Linnworks channel reference. Confirm that the macro configuration has been created and enabled in **Apps > Macro Configuration**. Check the **xmlnodelist** parameter and confirm that the selected nodes contain **label**, **inputValue**, **text**, or **optionValue** values. Review the macro logs for the customisation URL and API failure message. The macro checks whether the same note already exists and also skips orders already processed by the macro creator name. ### **Summary** The *Amazon Customisation Details Note* macro checks selected Linnworks orders, validates the Amazon XML order reference, extracts buyer customisation data from Amazon customisation XML, and adds the details to the order notes. This helps teams reduce manual checks, improve personalisation accuracy, and keep Amazon customised order details visible throughout the fulfilment process.