Shopify cartToOrderCopyable: The End of Cart Attribute Hacks

Shopify just quietly dropped one of the most developer-friendly features in recent memory — and barely anyone has noticed yet.

If you've ever built a custom buyer journey on Shopify — think gift messages, delivery notes, custom engraving text, or product personalizations — you know the pain. Getting custom data from the cart to the order has always meant hacks, workarounds, and crossing your fingers.

Not anymore.

The Old Way Was Painful

Here's how developers have been handling this for years:

Cart Attributes — the go-to hack. You'd stuff data into cart.attributes, which are just untyped key-value strings. Any app could read or overwrite them. No validation, no permissions, no structure. It worked, but it was messy.

Note Fields — another classic workaround. Dump everything into the order note and hope your fulfillment team could parse it. Not exactly scalable.

Custom Webhooks — listen for orders/create, intercept the data, and manually write it where it needs to go. Fragile, adds latency, and breaks when webhooks fail (which they do).

Checkout Extensions — better, but still required custom code to bridge the cart-to-order gap.

Every Shopify developer has their own variation of these hacks. I've implemented all of them across 200+ stores. None of them felt right.

Enter cartToOrderCopyable

As of API version 2026-04 (released February 4, 2026), Shopify introduced the cartToOrderCopyable capability for order metafield definitions.

The concept is dead simple:

1. Create an order metafield definition (e.g., custom.gift_message)
2. Enable the cartToOrderCopyable capability on it
3. Set the cart metafield with the same namespace and key via the Storefront API
4. When the customer checks out, Shopify automatically copies the value to the order

That's it. No webhooks. No post-purchase flows. No middleware. Shopify handles the heavy lifting at checkout completion.

How to Set It Up

Step 1: Create the Order Metafield Definition

Use the GraphQL Admin API to create an order metafield definition with the capability enabled:

mutation {
  metafieldDefinitionCreate(definition: {
    name: "Gift Message"
    namespace: "custom"
    key: "gift_message"
    type: "single_line_text_field"
    ownerType: ORDER
    capabilities: {
      cartToOrderCopyable: {
        enabled: true
      }
    }
  }) {
    createdDefinition {
      id
      name
    }
    userErrors {
      field
      message
    }
  }
}

You can also configure this via your app's TOML file:

[metafields.custom.gift_message]
name = "Gift Message"
type = "single_line_text_field"
owner_type = "ORDER"

[metafields.custom.gift_message.capabilities]
cartToOrderCopyable = true

Step 2: Set Cart Metafields via Storefront API

When the customer enters their gift message (or whatever custom data), use the cartMetafieldsSet mutation:

mutation cartMetafieldsSet($metafields: [CartMetafieldsSetInput!]!) {
  cartMetafieldsSet(metafields: $metafields) {
    metafields {
      key
      value
    }
    userErrors {
      field
      message
    }
  }
}

With variables:

{
  "metafields": [
    {
      "ownerId": "gid://shopify/Cart/YOUR_CART_ID",
      "namespace": "custom",
      "key": "gift_message",
      "value": "Happy Birthday! Hope you love this!",
      "type": "single_line_text_field"
    }
  ]
}

Step 3: There Is No Step 3

Seriously. When the customer completes checkout, Shopify automatically copies the cart metafield value to the order metafield. You can then access it from the order in the Admin API, Checkout UI extensions, or Shopify Functions.

Why This Is a Big Deal

Security

Cart attributes are a free-for-all. Any app installed on the store can read and write them. Cart metafields support app-reserved namespaces and edit/view permissions. Your data stays your data.

Typed Data

Cart attributes are strings. Always. Cart metafields support all metafield types — integers, booleans, dates, JSON, URLs, references. No more parsing strings and hoping for the best.

No More Webhook Dependency

The old webhook approach was fragile. Webhooks can fail, arrive out of order, or be delayed. With cartToOrderCopyable, the data transfer is atomic — it happens during checkout completion, guaranteed by Shopify.

Cleaner Order Admin

Metafields show up neatly in the Shopify admin order view. No more hunting through note fields or decoding cart attributes.

Real-World Use Cases

• Gift Messaging — No more lost "Happy Birthday" notes
• Delivery Instructions — "Leave at the back door" actually makes it to the order
• Product Personalizations — Engraving text, custom colors, monograms
• B2B Purchase Orders — PO numbers that flow cleanly to fulfillment
• Subscription Preferences — Size, frequency, flavor choices
• Campaign Tracking — Custom UTM or referral data persisted to orders

What About Existing Cart Attributes?

Shopify's official stance is clear: they now recommend cart metafields over cart attributes and checkout metafields for custom data storage.

That doesn't mean cart attributes are going away tomorrow. But the writing is on the wall. If you're building something new, use metafields. If you're maintaining an existing app, plan your migration.

Limitations to Know

• Only works on order metafield definitions (not other owner types)
• Maximum of 25 cart metafields per cartMetafieldsSet call
• Requires API version 2026-04 or later
• The namespace and key must exactly match between cart and order metafield definitions
• The cartMetafieldsSet mutation won't trigger Shopify Functions until the next cart interaction

The Bottom Line

This is Shopify saying "we heard you." Every developer who's ever duct-taped cart attributes to order notes is breathing a sigh of relief right now.

The cartToOrderCopyable capability is clean, secure, typed, and automatic. It's how custom data should have always worked in Shopify.

If you're building custom buyer journeys, personalization features, or any app that needs to pass data from cart to order — stop what you're doing and implement this. Your future self will thank you.

Have questions about implementing this in your Shopify store or app? I've been building Shopify solutions for 8+ years — [reach out](mailto:[email protected]) and let's chat.