# What order-level custom fields (gift messages, engraving instructions, delivery-date selections) need special handling during an order-history migration?

Reviewed by Martin Dejnicki, Director of SEO & AI Search · facts verified October 11, 2026 · canonical: https://deploi.ca/shopify/faq/order-level-custom-fields-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](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order), 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](https://shopify.dev/docs/apps/build/metafields/list-of-data-types), October 2026).

- **Order custom attributes:** Text key and value pairs. Shopify's example: a "gift message, delivery instructions, or internal notes". They show in the Additional details section of the order page (October 2026) ([Shopify developer docs, Order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order); [Shopify developer docs, OrderCreateOrderInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateOrderInput))
- **Line item properties:** Text name and value pairs on each line. Shopify: "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) ([Shopify developer docs, OrderCreateLineItemInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateLineItemInput); [Shopify developer docs, OrderInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderInput))
- **Date-type order metafield:** A calendar date, validated by type. With 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) ([Shopify developer docs, List of data types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types); [Shopify developer docs, Query using metafields](https://shopify.dev/docs/apps/build/metafields/query-using-metafields); [Shopify developer docs, Use metafield capabilities](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities))
- **Order note:** One free-text field, 5,000 characters max. Shopify says the note commonly holds "special delivery instructions, gift messages, or internal processing notes" (October 2026) ([Shopify developer docs, Order](https://shopify.dev/docs/api/admin-graphql/latest/objects/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.

**CUSTOMIZE: Map 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](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderInput), 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](https://shopify.dev/docs/apps/build/metafields/query-using-metafields), 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](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateOrderInput), October 2026).
- A migration app moves the rows and you own the map, a split [Deploi's metafield migration record](https://deploi.ca/shopify/build-vs-buy/metafield-and-metaobject-schema-migration) scores CUSTOMIZE: buy the app that moves the data, build the check of what reads it (October 2026).

**WAIT: Leave 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.

## 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](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldInput), October 2026).

**Four places a legacy order field can land in Shopify, and which one checks the value's type**

| 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 |

Sources: [Shopify developer docs, Order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order); [Shopify developer docs, OrderCreateOrderInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateOrderInput); [Shopify developer docs, OrderCreateLineItemInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateLineItemInput); [Shopify developer docs, MetafieldInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldInput); [Shopify developer docs, List of data types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types); [Shopify developer docs, OrderCreateCustomAttributeInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateCustomAttributeInput); [Shopify developer docs, OrderCreateLineItemPropertyInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateLineItemPropertyInput). Verified October 10, 2026.

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](https://deploi.ca/shopify/faq/split-shipments-partial-fulfillments-migration).

## 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.

1. **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](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateLineItemInput), October 2026). Its order update input rewrites custom attributes, the note and metafields, but takes no line item properties ([shopify.dev](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderInput), October 2026). So a wrong engraving mapping means re-importing the order.
1. **Delivery-date selections go in a date-type order metafield.** Create the definition before the import, so every row inherits the date type.
1. **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](https://deploi.ca/shopify/build-vs-buy/gift-options-and-notes) notes that gift notes persist on past orders as attributes (October 2026).
1. **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](https://shopify.dev/docs/apps/build/metafields/list-of-data-types), October 2026). A metafield written without a definition must declare its type on every row ([shopify.dev](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldInput), 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](https://shopify.dev/docs/apps/build/metafields/query-using-metafields), October 2026). Orders are on Shopify's list of resources that support admin filtering ([shopify.dev](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities), 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](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities), October 2026).
- **No filter for text attributes.** Shopify's order search documents no filter for custom attributes ([shopify.dev](https://shopify.dev/docs/api/admin-graphql/latest/queries/orders), 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](https://apps.shopify.com/store-migration), October 2026). So Shopify's migration guide sends historical orders through migration apps or its Order API ([Shopify Help Center](https://help.shopify.com/en/manual/migrating-to-shopify), October 2026). The order creation input takes custom attributes, line item properties and metafields directly ([shopify.dev](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateOrderInput), October 2026). Matrixify, for example, imports order-level "Additional Details" and per-line "Line: Properties" as name and value lines ([Matrixify](https://matrixify.app/documentation/orders/), October 2026). Its listing shows 4.9 stars from about 1,770 reviews, with plans from free to $200 a month ([Shopify App Store](https://apps.shopify.com/excel-export-import), October 2026). Attribution fields take the same import route, and [what historical attribution data survives a migration](https://deploi.ca/shopify/faq/custom-platform-migration-attribution-data-loss) 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](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderInput), 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.

> **When not to do this**
> - **When the field only made sense to the old platform.** Legacy workflow states, plugin IDs and internal queue markers add noise to every order your staff open.
> - **When it holds anything sensitive.** Custom attributes show in the order's Additional details section ([shopify.dev](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateOrderInput), October 2026), and any app with read access to orders can read them, so treat them as low-trust storage.
> - **When it's already derivable.** A "has gift wrap" flag that is also a line item doesn't need to exist twice.
> - **When the volume is low enough to answer by hand.** A few hundred historical engraving orders cost less to look up in an archive than to model.

## Deploi's point of view

**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.

## 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.

## Sources

1. [Shopify developer docs, Order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order), checked October 10, 2026
2. [Shopify developer docs, OrderCreateOrderInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateOrderInput), checked October 10, 2026
3. [Shopify developer docs, OrderCreateLineItemInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateLineItemInput), checked October 10, 2026
4. [Shopify developer docs, OrderInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderInput), checked October 11, 2026
5. [Shopify developer docs, MetafieldInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldInput), checked October 10, 2026
6. [Shopify developer docs, List of data types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types), checked October 10, 2026
7. [Shopify developer docs, Query using metafields](https://shopify.dev/docs/apps/build/metafields/query-using-metafields), checked October 10, 2026
8. [Shopify developer docs, Use metafield capabilities](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities), checked October 11, 2026
9. [Shopify developer docs, orders query](https://shopify.dev/docs/api/admin-graphql/latest/queries/orders), checked October 10, 2026
10. [Shopify Help Center, Migrate to Shopify](https://help.shopify.com/en/manual/migrating-to-shopify), checked October 10, 2026
11. [Shopify App Store, Shopify Store Migration](https://apps.shopify.com/store-migration), checked October 10, 2026
12. [Matrixify, Import and Export Orders from Shopify in bulk with Matrixify](https://matrixify.app/documentation/orders/), checked October 10, 2026
13. [ITissible, Matrixify: Data Export Import on the Shopify App Store](https://apps.shopify.com/excel-export-import), checked October 11, 2026
14. [Shopify developer docs, OrderCreateCustomAttributeInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateCustomAttributeInput), checked October 10, 2026
15. [Shopify developer docs, OrderCreateLineItemPropertyInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/OrderCreateLineItemPropertyInput), checked October 10, 2026
16. [Deploi Build vs. Buy, Build or Buy Metafield and Metaobject Schema Migration on Shopify?](https://deploi.ca/shopify/build-vs-buy/metafield-and-metaobject-schema-migration), checked October 11, 2026, Deploi research
17. [Deploi Build vs. Buy, Build or Buy Gift Options & Notes on Shopify?](https://deploi.ca/shopify/build-vs-buy/gift-options-and-notes), checked October 10, 2026, Deploi research