What order-level custom fields (gift messages, engraving instructions, delivery-date selections) need special handling during an order-history migration?
Order-level custom fields migrate as order and line item custom attributes, which Shopify's own documentation describes as holding a gift message, delivery instructions, or internal notes (per shopify.dev, September 2026). Gift messages and engraving text survive as key-value pairs. Delivery-date selections need a metafield with a date type, or they arrive as unvalidated strings.
Three places Shopify will put this data, and they behave differently
| Destination | What it is | Good for | Weakness |
|---|---|---|---|
| Order customAttributes | "A list of additional information that has been attached to the order. For example, gift message, delivery instructions, or internal notes" (per shopify.dev, Sep 2026) | Anything the customer typed at checkout, one value per order | Strings only. No type, no validation, no filtering |
| Line item properties | Per-item key-value pairs, accepted on the line item at order creation (per shopify.dev, Sep 2026) | Engraving text, monogram, personalization that belongs to one unit | Same string-only limit |
| Order metafields | Typed, namespaced, definable | Delivery dates, promised windows, anything you will query or report on | Needs a definition created before the import runs |
The mistake is treating all three as interchangeable because they all look like extra fields in an export. They are not. A gift message is free text and belongs in a custom attribute. A delivery date is a date, and putting a date into a string field means every downstream report has to parse it and every parse has an edge case.
Which fields need real handling, ranked
- Engraving and personalization on a line item. This is the one that must be per line, not per order. A two-item order with different engraving on each item collapses into ambiguity if you store it at order level. Map it to line item properties before anything else.
- Delivery-date selections. Create the metafield definition with a date type first, then import. Doing it in the other order leaves you with strings you have to re-migrate.
- Gift messages. Low risk, high visibility. They are the field customer service will look for on day one, so they should be on the order detail page, not in an attachment.
- Internal operational flags. Fraud review outcomes, manual price overrides, rep notes. These usually should not migrate as customer-visible attributes at all, because Shopify renders order custom attributes in the supplemental information area of the order details page.
The part that fails in QA, every time
Custom attributes carry no schema, so nothing rejects a bad value. A legacy export with three different key spellings for the same concept, say gift_message, giftMessage and Gift Message, imports cleanly and produces three fields that no report can group. Normalize keys in the transformation step, not in Shopify, and publish the key list as a document your support team can read.
When NOT to migrate a custom field
- When the field only made sense to the old platform. Legacy workflow states, plugin IDs and internal queue markers create noise on a customer-facing order page.
- When it contains anything sensitive. Order custom attributes are visible to staff and can be exposed through apps. Treat them as low-trust storage.
- When it is already derivable. A "has gift wrap" flag that is also a line item does not need to exist twice.
- When the volume is low enough to answer by hand. A few hundred historical engraving orders are cheaper to look up in an archive than to model.
The Deploi point of view
Our own position, from building on Shopify. Separate from the facts above.
- Our take: Decide the destination per field before a single row moves, and write the decision down as a mapping table that both the agency and the merchant's ops lead sign. The order that works is: define metafields, import products, import customers, import orders. Shopify itself gives the last three in that sequence so that "products and customers can be properly connected to the orders" (per Shopify Help Center, September 2026), and metafield definitions have to come before all of it.
- Where we disagree: Most migration scopes list custom fields as a line item called "order attributes" and price it as one task. That is how the engraving-per-line problem gets found during UAT. We split the field list into the three destinations 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 custom attributes, line item properties and metafields are three destinations with different type guarantees, and that the per-line personalization case is the one that cannot be fixed after import without a re-migration.
Reviewed by Martin Dejnicki, Director of SEO & AI Search. Facts verified 2026-09-14.
Where we worked this out
Our decision records