Map Magento custom data to Mintsoft orders

Before you start

Property mappings allow you to extract custom data from Magento order JSON responses and map them to specific fields in Mintsoft orders. This feature is useful for capturing custom checkout fields, gift messages, delivery instructions, and other custom data from your Magento store.

Prerequisites

You should have access to a sample Magento order JSON to identify the correct paths for your custom fields.

Overview of mapped fields

You can create mappings to the data for each order. This includes standard data items in Mintsoft as well as ad hoc data.

Standard order level data in Mintsoft can be mapped from either order level or order item level.

Concatenated text fields

Multiple values are joined using '. ' (full stop + space). You can create multiple mappings for the same field and all matching values will be appended together:

GiftMessage
DeliveryMessage
PackingNotes

Single value fields

The value is set to first available:

DeliveryDate
EORINumber
PIDNumber
RequiredDespatchDate
IOSS

Ad hoc data

Ad hoc data can be mapped at order level or at order item level. To retrieve ad hoc data use the following option: PersonalisationOption.

Important level restrictions:

EORINumber, PIDNumber, and IOSS can only be mapped at order level. If you set these to order item level, they will be ignored during import.
GiftMessage, DeliveryMessage, PackingNotes, RequiredDespatchDate, and DeliveryDate can be mapped at either order or order item level.
For PersonalisationOption, the name of the created field in Mintsoft is taken from the last segment of your JSON Path. Example: a path of extension_attributes.custom_fields.ioss_number creates a name/value pair with Name = ioss_number.

Map a property

To add a property mapping for Magento, follow the steps below.

Click Connect, then click Order Integrations.
Click Magento.
Click Property Mappings.
Enter the following:
- JSON Path (required) – The JSON path expression to extract data from Magento's order response.
  - Example: extension_attributes.custom_field or items[*].extension_attributes.gift_note.
- Level – Select either Order or OrderItem.
- MappedField – Select one of: GiftMessage, DeliveryMessage, PackingNotes, PersonalisationOption, DeliveryDate, EORINumber, PIDNumber, RequiredDespatchDate, or IOSS.
Click Create.

Note: The MagentoAccountId is set automatically when you add a mapping from an account's property mappings page.

Understanding JSON Path

Order JSON example

{
  "entity_id": "12345",
  "increment_id": "000012345",
  "created_at": "2025-11-12 10:30:00",
  "customer_email": "[email protected]",
  "grand_total": 125.50,
  "order_currency_code": "GBP",
  "items": [
    {
      "item_id": "54321",
      "sku": "PROD-001",
      "name": "Custom T-Shirt",
      "qty_ordered": 2,
      "price": 25.00,
      "row_total": 50.00,
      "extension_attributes": {
        "personalization_text": "Happy Birthday John!",
        "gift_wrap": "Yes",
        "custom_options": [
          {
            "option_id": "1",
            "option_value": "Size: Large"
          }
        ]
      }
    },
    {
      "item_id": "54322",
      "sku": "PROD-002",
      "name": "Gift Card",
      "qty_ordered": 1,
      "price": 50.00,
      "row_total": 50.00,
      "extension_attributes": {
        "personalization_text": "Best Wishes!",
        "gift_wrap": "No"
      }
    }
  ],
  "extension_attributes": {
    "shipping_assignments": [
      {
        "shipping": {
          "address": {
            "firstname": "John",
            "lastname": "Smith",
            "street": ["123 Main Street"],
            "city": "London",
            "postcode": "SW1A 1AA",
            "country_id": "GB",
            "telephone": "020 1234 5678"
          }
        }
      }
    ],
    "gift_message": {
      "message": "Happy Birthday! Enjoy your gift."
    },
    "delivery_instructions": "Please leave with neighbour if not home",
    "custom_checkout_fields": [
      {
        "code": "delivery_date",
        "label": "Preferred Delivery Date",
        "value": "2025-11-15"
      },
      {
        "code": "gift_note",
        "label": "Gift Note",
        "value": "From your loving family"
      },
      {
        "code": "eori_number",
        "label": "EORI Number",
        "value": "GB123456789000"
      }
    ],
    "ioss_number": "IM1234567890"
  }
}

Order-level property mapping examples

JSON Path	Level	MappedField	Result in Mintsoft
`extension_attributes.gift_message.message`	Order	GiftMessage	Populates Gift Messages field with "Happy Birthday! Enjoy your gift."
`extension_attributes.delivery_instructions`	Order	DeliveryMessage	Populates Delivery Notes field with "Please leave with neighbour if not home"
`extension_attributes.custom_checkout_fields[?(@.code=='delivery_date')].value`	Order	DeliveryDate	Sets Required Delivery Date to 2025-11-15
`extension_attributes.custom_checkout_fields[?(@.code=='eori_number')].value`	Order	EORINumber	Sets EORI Number to "GB123456789000"
`extension_attributes.ioss_number`	Order	IOSS	Creates Order Name/Value with Name="IOSS", Value="IM1234567890"
`extension_attributes.custom_checkout_fields[?(@.code=='gift_note')].value`	Order	PersonalisationOption	Creates Order Name/Value with Name="value", Value="From your loving family"

Order item-level property mapping examples

JSON Path	Level	MappedField	Result in Mintsoft
`extension_attributes.personalization_text`	OrderItem	PersonalisationOption	Creates Item Extra Info with Name="personalization_text", Value="Happy Birthday John!" (for first item) and "Best Wishes!" (for second item)
`extension_attributes.gift_wrap`	OrderItem	PersonalisationOption	Creates Item Extra Info with Name="gift_wrap", Value="Yes" or "No" for each item

Important: Avoid trailing dots in JSON Path expressions. The system validates paths using Newtonsoft.Json (JToken.SelectToken) which will reject invalid syntax.

Order item level paths

For level = OrderItem, write the JSON Path relative to the individual item object (not from the root).

Example: In the online evaluator, you might test using items[0].extension_attributes.personalization_text to access the first item's data. However, in the JSON Path field for an order item-level mapping, you would enter just extension_attributes.personalization_text (without the items[0]. prefix). The system automatically applies your path to each item in the order.

Common JSON Path patterns

Direct field: extension_attributes.field_name
Nested field: extension_attributes.custom_data.field_name
Array filter: custom_fields[?(@.code=='field_code')].value
First array item: items[0].field_name (for testing only - use relative path for OrderItem mappings)
All array items: items[*].field_name (returns multiple values)

Testing your mappings

Get a sample order JSON from Magento.
Copy the JSON to https://jsonpath.com/.
Test your JSON Path expression to ensure it returns the expected value.
Create the mapping in Mintsoft using the validated path.
Import a test order to verify the mapping works correctly.

Note: The paths shown above may not be the same for your mapping. Use the evaluator to help build your JSON Path.

More expressions can be found here: Standard Magento JSON for an order.

Where mapped data appears in orders

Order-level mappings

GiftMessage → Gift Messages field.
DeliveryMessage → Delivery Notes field.
PackingNotes → Comments field (also called Packing Notes).
DeliveryDate → Required Delivery Date field.
RequiredDespatchDate → Required Despatch Date field.
EORINumber → EORI Number field.
PIDNumber → PID Number field.
IOSS → Stored as Order Name/Value with Name "IOSS" (viewable in Orders > Overview > Actions > Details > Items tab).
PersonalisationOption (order level) → Order Name/Values (viewable in Orders > Overview > Actions > Details > Items tab).

Item-level mappings

PersonalisationOption (OrderItem level) → Item Extra Info (viewable in Orders > Overview > Actions > Details > Extra Info on the specific order item).

To view ad hoc order item data:

Click Orders, then click Overview.
Find the order.
Click Actions.
Click Details, then click Extra Info.

To view ad hoc order level data:

Click Orders, then click Overview.
Find the order.
Click Actions.
Click Details, then click Items.

Magento Integration

Order rule action - GenerateAdditionalDocument and GenerateAdditionalGiftDocument

Shopify - How to set up Property Mappings

Magento - Troubleshooting

API - Create an order