What order-level custom fields (gift messages, engraving instructions, delivery-date selections) need special handling during an order-history migration?
Short answer
Engraving instructions and delivery-date selections need special handling; gift messages need only consistent keys. Shopify's example for an order's custom attributes is a "gift message, delivery instructions, or internal notes" (shopify.dev, October 2026). Engraving goes in line item properties, so each line keeps its own text. Delivery dates go in a date-type metafield, which Shopify validates (shopify.dev, October 2026).
- Order custom attributes
- Text key and value pairsShopify's example: a "gift message, delivery instructions, or internal notes". They show in the Additional details section of the order page (October 2026).Sources: Shopify developer docs (Order, OrderCreateOrderInput)
- Line item properties
- Text name and value pairs on each lineShopify: "Often used to provide product customization options". Its order update input takes no line item properties, so they can't be rewritten after import (October 2026).Sources: Shopify developer docs (OrderCreateLineItemInput, OrderInput)
- Date-type order metafield
- A calendar date, validated by typeWith filtering enabled on its definition, orders can be filtered by the date and range-queried; order metafields of an eligible type can also be made queryable in ShopifyQL reports (October 2026).Sources: Shopify developer docs (List of data types, Query using metafields, Use metafield capabilities)
- Order note
- One free-text field, 5,000 characters maxShopify says the note commonly holds "special delivery instructions, gift messages, or internal processing notes" (October 2026).Source: Shopify developer docs (Order)
Deploi’s call
Decide each field's destination before a single row moves, in a mapping table the agency and the operations lead both sign. Import in this order: metafield definitions, products, customers, orders. Shopify gives the last three in that sequence so that "products and customers can be properly connected to the orders" (Shopify Help Center, October 2026). Defining the metafields first means every imported row inherits its type instead of declaring its own.
CustomizeMap each field to its own destination when
- The value differs per line, like engraving text. Put it in line item properties, which Shopify's order update input can't rewrite later (shopify.dev, October 2026).
- Someone will filter or report on the value, like a delivery date. Put it in a date-type order metafield whose definition has filtering turned on (shopify.dev, October 2026).
- Staff need the value on day one, like a gift message. Put it in a custom attribute, which shows in the order's Additional details section (shopify.dev, October 2026).
- A migration app moves the rows and you own the map, a split Deploi's metafield migration record scores CUSTOMIZE: buy the app that moves the data, build the check of what reads it (October 2026).
WaitLeave the field in the archive while
- It only meant something to the old platform, like a workflow state, plugin ID or queue marker.
- It holds anything sensitive, because any app with read access to orders can read custom attributes.
Basis: Build or Buy Metafield and Metaobject Schema Migration on Shopify?, our Build vs. Buy decision record, scored CUSTOMIZE.
Where can a migrated custom field live on a Shopify order?
A migrated custom field can live in four places on a Shopify order, and only one of them carries a type Shopify checks. The order note, the order's custom attributes and each line item's properties hold plain text. Order metafields hold a value of a declared type, such as a date (shopify.dev, October 2026).
| Destination | What it holds | Type checking | Limit |
|---|---|---|---|
| Order note | One free-text note per order | None | 5,000 characters |
| Order custom attributes | Text key and value pairs, shown in the order's Additional details section | None | Text only |
| Line item properties | Text name and value pairs on one line item | None | Text only |
| Order metafields | A value of a declared type, such as a date | Built-in validation for every type | Each value needs a type, or a definition that sets one |
So every field migrates as something, and the real question is which destination keeps it useful after cutover. A gift message is free text and belongs in a custom attribute or the note. A delivery date is a date, so storing it as text means every downstream report has to parse it. Shipment detail follows other rules: split shipments and partial fulfillments migrate as fulfillment records.
Which fields need handling first, and where does each one go?
The fields that need handling first are the costly ones to fix after import: per-line text and dates. Rank them this way.
- Engraving and personalization go on the line item. A two-item order with different engraving on each item turns ambiguous at order level. Shopify describes line item properties as "Often used to provide product customization options" (shopify.dev, October 2026). Its order update input rewrites custom attributes, the note and metafields, but takes no line item properties (shopify.dev, October 2026). So a wrong engraving mapping means re-importing the order.
- Delivery-date selections go in a date-type order metafield. Create the definition before the import, so every row inherits the date type.
- Gift messages go in a custom attribute or the note. They're low risk and high visibility, because customer service looks for them on day one. Deploi's gift options record notes that gift notes persist on past orders as attributes (October 2026).
- Internal operational flags stay in the archive. Fraud review outcomes, manual price overrides and sales rep notes would otherwise sit in the Additional details section beside the gift message.
Why does a delivery date need a metafield instead of a text attribute?
A delivery date needs a metafield because only a metafield gives Shopify a type it can validate and filter on. Shopify's date type stores a calendar date with no presumed time zone, and "All types have built-in validation" (shopify.dev, October 2026). A metafield written without a definition must declare its type on every row (shopify.dev, October 2026), which is why the definition comes first.
The definition also decides what the date can do after cutover:
- Filtering. Shopify says "filtering must be enabled on the metafield definition" before you query by value, and date types take range queries (shopify.dev, October 2026). Orders are on Shopify's list of resources that support admin filtering (shopify.dev, October 2026).
- Reporting. Order metafield definitions can be made queryable in analytics, including Shopify's ShopifyQL reports, where Shopify marks the type eligible (shopify.dev, October 2026).
- No filter for text attributes. Shopify's order search documents no filter for custom attributes (shopify.dev, October 2026), so a date kept as text has to be parsed by every report that reads it.
Which import route carries order custom fields?
Order custom fields reach Shopify only through a migration app or the Admin API (application programming interface). Shopify's own Store Migration app moves "product and customer data", not order history (Shopify App Store, October 2026). So Shopify's migration guide sends historical orders through migration apps or its Order API (Shopify Help Center, October 2026). The order creation input takes custom attributes, line item properties and metafields directly (shopify.dev, October 2026). Matrixify, for example, imports order-level "Additional Details" and per-line "Line: Properties" as name and value lines (Matrixify, October 2026). Its listing shows 4.9 stars from about 1,770 reviews, with plans from free to $200 a month (Shopify App Store, October 2026). Attribution fields take the same import route, and what historical attribution data survives a migration has its own answer.
What fails in quality assurance after the import?
Inconsistent keys fail quality assurance (QA) after the import, because custom attributes carry no schema and nothing rejects a bad key. A legacy export with gift_message, giftMessage and Gift Message for the same concept imports cleanly as three fields that no report can group. Fixing them later means rewriting every affected order, because Shopify's order update input "Overwrites the existing custom attributes" (shopify.dev, October 2026). So normalize keys in the transformation step, not in Shopify, and publish the key list for your support team.
When should a custom field stay behind?
A custom field should stay behind in the archive when moving it adds noise, risk or cost and nobody will read it in Shopify.
Deploi’s point of view
Our own position, from building on Shopify. Kept apart from the sourced facts above.
- Where we disagree
- Most migration scopes list custom fields as one line item called "order attributes" and price it as one task. That is how the engraving-per-line problem gets found during user acceptance testing. We split the field list by destination at scoping time and refuse to quote it as a single number, because the per-line cases and the typed cases are different work.
- What this page adds
- that the order note, custom attributes, line item properties and metafields are four destinations with different type guarantees, and that the per-line personalization case is the one Shopify's order update can't fix after import, so a wrong mapping means a re-import.
Decision records behind this answer
When this answer changes
- Shopify's order update input starts accepting line item properties, so a wrong engraving mapping no longer needs a re-import.
- Shopify adds a custom attribute filter to order search, or changes which resources support admin filtering by metafield value.
- Shopify's Store Migration app starts importing orders.
- Matrixify changes its order columns or its plans.
Related questions
- How do split shipments and partial fulfillments in historical order data migrate to Shopify's fulfillment-order model without breaking the audit trail?
Split shipments migrate as one fulfillment per shipment, not as the original fulfillment orders.
- Do we lose years of historical conversion and revenue-attribution data when migrating a custom platform's tracking setup to Shopify?
Historical revenue survives a move to Shopify; session attribution does not.
Sources
Every figure on this page traces to one of these. Official and vendor pages are checked on the date shown; Deploi records are our own published decisions.
- Shopify developer docs, Order
- Shopify developer docs, OrderCreateOrderInput
- Shopify developer docs, OrderCreateLineItemInput
- Shopify developer docs, OrderInput
- Shopify developer docs, MetafieldInput
- Shopify developer docs, List of data types
- Shopify developer docs, Query using metafields
- Shopify developer docs, Use metafield capabilities
- Shopify developer docs, orders query
- Shopify Help Center, Migrate to Shopify
- Shopify App Store, Shopify Store Migration
- Matrixify, Import and Export Orders from Shopify in bulk with Matrixify
- ITissible, Matrixify: Data Export Import on the Shopify App Store
- Shopify developer docs, OrderCreateCustomAttributeInput
- Shopify developer docs, OrderCreateLineItemPropertyInput
- Deploi Build vs. Buy, Build or Buy Metafield and Metaobject Schema Migration on Shopify?
- Deploi Build vs. Buy, Build or Buy Gift Options & Notes on Shopify?