Gift messages are not supported by WooCommerce "out of the box" and, depending on how you've decided to implement them into your store, you might have needed to utilise a 3rd party app to do so. As such, it is possible that different apps store gift messages differently from store to store.


In order to successfully download gift messages from your store, once you have enabled Downloading Gift Messages from your WooCommerce settings page, you need to enter a path to direct Shiptheory to where it can find a gift message in your orders:



Gift Message Path syntax

The gift message path uses dot notation to dictate how to navigate through the JSON data Shiptheory downloads from WooCommerce when processing your orders and shipments.


For example:

meta_data.{n}[key=gift_message].value


Would extract "Thanks for looking after Whiskers" from the order data below:

{
    "meta_data": [
        {
            "id": 12740686,
            "key": "_order_number",
            "value": "123456789"
        },
        {
            "id": 12740687,
            "key": "gift_message",
            "value": "Thanks for looking after Whiskers"
        }
    ]
}



  • The path is Case Sensitive. For example, "name" will match "name" but not "Name" or "NAME".

  • {n} can be used to match any unordered elements, such as multiple line items or notes.

  • If multiple matches can be made, only the first match is returned.

  • If you need to match an element where an attribute matches a certain value, you can add a match condition to the path in square brackets. For example, in the JSON above there are multiple properties. In order to match the value of the gift_message, a condition has been added to the path to return the value of the element with a name attribute equalling "gift_message"
    meta_data.{n}[name=gift_message].value



Data Path testing tool

We have a tool to help you build and test your data path, available here: https://helm.shiptheory.com/sandbox/find_data_path.


Simply copy-and-paste the JSON data from a WooCommerce order or fulfillment into the tool and you will be able to enter and test your data path before saving to your WooCommerce settings.



More examples

{
    "order": {
        "id": 3820949393871,
        "line_items": [
            {
                "id": 5756501196957,
                "name": "White T-Shirt",
                "price": "13.95",
                "properties": [
                    {
                        "name": "gift_message",
                        "value": "Happy Birthday Jack!"
                    }
                ],
                "quantity": 1,
                "requires_shipping": true,
                "sku": "tshirt-w",
                "variant_id": 35262767071389
            },
            {
                "id": 5756501196957,
                "name": "Blue T-Shirt",
                "price": "13.95",
                "properties": [
                    {
                        "name": "gift_message",
                        "value": "Merry Christmas Sophie!"
                    }
                ],
                "quantity": 1,
                "requires_shipping": true,
                "sku": "tshirt-b",
                "variant_id": 35262767071389
            }
        ],
        "name": "#2937",
        "note": "This is an order note",
        "note_attributes": [
            {
                "name": "note",
                "value": "Note A"
            },
            {
                "name": "note",
                "value": "Note B"
            }
        ]
    }
}


  • order.note
    Returns: This is an order note

  • order.note_attributes.{n}.value
    Since this has multiple matches (Note A and Note B), the first match is returned
    Returns: Note A

  • order.line_items.{n}[sku=tshirt-b].name
    Returns: Blue T-Shirt



If you have any questions regarding this or anything else, please don't hesitate to get in touch with the Shiptheory support team!