Save a checkout field to an order metafield
In short
Every Checkout Ninja input block has a Where to store the value setting: Attribute or Metafield. Choose Metafield and enter a Namespace and Key such as custom.po_number, and the value is saved as a cart metafield. Shopify only copies it to the order if an order metafield definition with the same namespace and key exists and has cart-to-order copying enabled. Attributes need no setup and show under Additional details.
✓ Applies to
- Text Input, Dropdown, Date Picker, Phone Input, Gift Message and Dependency Dropdown (Combined mode)
- Text Input fields nested in a Conditional Checkbox
- Advanced and Deluxe plans
✕ Doesn't apply to
- The Checkbox block, which doesn't save its value
- Dependency Dropdown in Separate mode, which always saves attributes
Before you start
Decide which storage fits. Attribute storage needs no setup; metafield storage needs a definition in Shopify.
| Attribute | Metafield | |
|---|---|---|
| Set in the block | Attribute → Name of the attribute, e.g. po_number | Metafield → Namespace and Key, e.g. custom.po_number |
| Where the value is written | A cart attribute | A cart metafield, type single line text |
| Reaches the order | Always | Only if Shopify copies it (see below) |
| Where you see it | Order page → Additional details | Order page → Metafields |
| Setup in Shopify | None | An order metafield definition |
If you leave the name blank on a Text Input or Dropdown, the block’s Label is used as the attribute name. Gift Message defaults to giftMessage, and Dependency Dropdown to dependent_dropdown. Date Picker and Phone Input have no fallback, so always name them.
For metafield storage you also need:
- An input block that stores values: Text Input, Dropdown, Date Picker, Phone Input, Gift Message, or Dependency Dropdown in Combined mode. The Checkbox block doesn’t save its value.
- Permission to edit metafield definitions in your Shopify admin.
- Pick a namespace and key. Use lower case letters, numbers and underscores, with exactly one dot between them, for example
custom.delivery_date.
Steps
- In Checkout Ninja, open your block under Blocks and click the input block to edit it.
- Under Where to store the value, choose Metafield.
- In Namespace and Key, enter your
namespace.key, for examplecustom.delivery_date. - Click Done, then Save.
- In your Shopify admin, go to Settings → Metafields and metaobjects → Orders and add a definition.
- Use the same namespace and key as step 3, and the type Single line text.
- Enable cart-to-order copying on the definition (Shopify calls this the
cartToOrderCopyablecapability). Without it, Shopify doesn’t copy the value to the order. - Save the definition.
Shopify copies a cart metafield to the order only when an order metafield definition with the same namespace and key exists and has cart-to-order copying enabled. Checkout Ninja writes the cart metafield, but doesn’t create or change your order definitions. If you can’t enable copying on your definition, use Attribute storage instead.
Verify it worked
- Open your checkout, fill in the field and place a test order.
- Open the order in Orders and scroll to Metafields. Your definition shows the value.
- Negative check: an order placed before you created the definition, or with copying off, has no value in that metafield.
Limitations
- Values are always saved as single line text, even dates and phone numbers.
- A name with more than one dot, such as
a.b.c, isn’t valid. The value is saved tocustom.default_keyinstead. - Shopify doesn’t apply cart metafield changes when the buyer uses an accelerated checkout such as Apple Pay or Google Pay. Attribute storage is the safer choice if many buyers use them.
- Dependency Dropdown in Separate mode ignores this setting and always saves attributes.
- Metafields don’t show under Additional details, and packing slips and order exports that list attributes won’t include them.
Troubleshooting
The order has no metafield value. Check the order definition’s namespace and key match the block’s Namespace and Key exactly. Then check cart-to-order copying is enabled on the definition. Place a new test order: Shopify doesn’t fill in values for past orders.
The value is saved under custom.default_key.
The Namespace and Key has more than one dot, or nothing on one side of the dot. Use the format namespace.key.
The value is on the order but I can’t find it. You may be looking in the wrong place. Attribute values are under Additional details, not Metafields. Check the block’s Where to store the value setting.
Frequently asked
Should I use an attribute or a metafield? +
Use an attribute unless you have a reason not to. Attributes reach the order with no setup and show under Additional details. Choose a metafield when a tool you use reads order metafields, or you want a typed field on the order.
What namespace is used if I only enter a key? +
custom. Entering po_number saves to custom.po_number. Use exactly one dot to set your own namespace, such as ops.po_number.
What type should the order metafield definition be? +
Single line text. Checkout Ninja writes every value as a single_line_text_field.
Why is my metafield value missing from the order? +
Usually because no order metafield definition exists with the same namespace and key, or cart-to-order copying isn't enabled on it. Shopify only copies the cart metafield to the order when both are true.