Skip to content
upproof.

Guide · 5 min read · updated 2026-11-11

Shopify line item properties for personalization

Line item properties are extra pieces of information a customer adds to a product before it goes into the cart, such as engraving text, a chosen font or an uploaded design. Shopify stores them on that specific line of the order, not on the product or the whole order. That is what makes them the natural home for personalization: two lines with the same variant can carry different text or different files.

How line item properties work

On the product page, any form field named properties[Some name] inside the add-to-cart form is sent with the item. Shopify keeps the name and value on the cart line, carries them through checkout and saves them on the order line.

<form action="/cart/add" method="post">
  <input type="hidden" name="id" value="{{ product.selected_or_first_available_variant.id }}">

  <label for="engraving">Engraving text</label>
  <input id="engraving" type="text" name="properties[Engraving]">

  <!-- Starts with an underscore: stored on the line, hidden from the customer -->
  <input type="hidden" name="properties[_reference]" value="abc123">

  <button type="submit">Add to cart</button>
</form>

A few rules worth knowing:

  • They are set before checkout. The values travel with the add-to-cart request. Plan for them to be right when the item is added.
  • An underscore hides a property. Names starting with _ are, by theme convention, not shown to the customer in the cart or at checkout. Use them for internal references.
  • Values are text. A file is not stored in the property itself; an app stores the file and puts a link or reference in the property.
  • Different values make different lines. The same variant added twice with different properties becomes two cart lines, which is exactly what personalized products need.

Line item properties and customer file uploads

Most Shopify upload apps rely on line item properties. The customer picks a file on the product page, the app stores it, and the add-to-cart form carries a reference to it. When the order arrives, the reference on each line says which file belongs to which item. If the reference is lost, the file is still stored, but nobody can tell which line it was for.

That is why the weak points are the paths that skip the product form. Quick-buy buttons, quick-add from a collection page and some accelerated checkout buttons can add an item without its properties. Test each of them on your theme before you rely on uploads.

How Upproof uses them

Upproof’s product page block adds three properties to the line: a hidden _proof_ref that ties the upload to the order line, a visible “Uploaded design” entry, and “Design notes” when the customer writes one. The files themselves are stored by Upproof, not in the property. When the order arrives, each line is matched to its own upload, and that line gets its own proof and its own approval. For the setup steps, see collect customer artwork on Shopify without email.

Checklist before you launch personalization

  1. Add the same variant twice with different values and confirm you get two lines.
  2. Place a test order and check that every property appears under the right item in the admin.
  3. Try every buy button on the product and collection pages, including accelerated checkout.
  4. Confirm that hidden properties stay hidden from the customer in the cart and at checkout.

Questions

Where do I see line item properties on an order?

In the Shopify admin they appear under the item on the order page. They are also available to apps through the order’s line items.

Why does a property start with an underscore?

Shopify themes conventionally hide properties whose name starts with an underscore from the customer in the cart and at checkout. They are meant for references that apps or staff need but the customer does not.

Can a customer upload a file as a line item property?

A property holds text. File upload apps store the file somewhere else and save a link or a reference in the property, so the file and the line stay connected.

Why are properties sometimes missing from an order?

Properties are sent with the add-to-cart form. A route that skips the product form, such as some quick-buy, quick-add or accelerated checkout buttons, can add the item without them. Test every way a customer can buy the product.

Keep reading

Upproof adds artwork upload and versioned proof approval to Shopify product pages. See it in the Shopify App Store or read how approval works.