Line properties and order metafields

Choose the correct owner and preserve a shopper's personalization through checkout.

A cart or wishlist metafield belongs to the whole resource. A cart-line or wishlist-line property belongs to one selected product or variant. Two lines containing the same variant but different personalization have different identities. Use cart line IDs and wishlist identity hashes when updating or removing a particular personalized line.

Data	Meaning	After checkout
Cart / wishlist metafield	Information about the entire cart or wishlist	No automatic copy to an order
cart_line / wishlist_line property	Declared information about one selected item	Cart properties become the order item's saved property snapshot
order / order_item metafield	A separately declared, editable value on the saved order or item	Read and write through the order metafield endpoints
Line artifact	An app-owned, versioned file reference attached to a line	Linked to the order item; optional explicit metafield transfer

Which surface shows which value#

Value	Where the merchant sees it
cart_line / wishlist_line property	A `Name: value` line under the order item title — the checkout snapshot, read-only
order_item metafield	The item's Metafields list, where merchants read or edit values according to merchant_access
Line artifact with transfer_to_order_line	An order-item metafield record, so the artwork reference appears in that same Metafields list

The property lines and the item's metafields use one order: the definition's sort_order, then its name, then the wire key. An item with a single property looks unchanged; declare sort_order when your app ships several fields. A line carries at most 20 properties in total, shared with every other app on that line.

Ordinary buyer-entered values#

Declare the appropriate line owner with buyer_access=read_write. The hosted cart_add action accepts properties[namespace.key]. Unknown definitions, hidden or read-only buyer fields, invalid types and over-limit values are rejected. Hosted cart_update and cart_remove identify the line with line_id. Changing the product or variant alone cannot identify a personalized line.

personalized-cart.vasc liquid

{% form 'cart_add' %}
  <input type="hidden" name="product_id" value="123">
  <input type="hidden" name="quantity" value="1">
  <label>Engraving <input name="properties[custom.engraving]" maxlength="40"></label>
  <button type="submit">Add to cart</button>
{% endform %}

Replace the sample product and key with a purchasable product and a declared buyer-writable cart-line definition. Check the action's user_errors even when the request succeeds. Ordinary hosted-form property inputs do not grant authority to attach an app's private artifact. Use an authorized app storefront surface for artifact attachment.

Wishlist to cart#

The hosted wishlist_move_to_cart action moves the exact saved line. Destination cart declarations and product/variant availability are validated. Artifact transfer additionally requires the same active app installation, compatible cart-line declaration and an unexpired reference. Moving a saved item does not renew its lease. If transfer fails, the saved item remains; cart addition and removal of that saved row succeed together.

Saved order values#

The order item's properties are the checkout snapshot, not its mutable order_item metafields. Updating or deleting a metafield does not rewrite that snapshot. Ordinary properties are not automatically converted into editable metafields. An artifact with transfer_to_order_line=true requires a matching string order_item declaration with the same key in the same app release. Snapshot reads and order webhooks respect definition access: private app values remain private, while shared values require the recipient's order scope. Merchant visibility follows merchant_access.

Order and item metafield writes validate the URL's store, order and item relationship, declared type, references and app ownership. A batch succeeds or fails as a whole. Send explicit null or an empty string to remove a value; omitting value is invalid. Unchanged values do not emit another change event. Subscribe to order_metafields/create, /update, /delete or order_item_metafields/create, /update, /delete with read_orders. See Orders Store API for pagination, current limits, request bodies and errors.