Shopify Line Item Properties: Complete Reference for 2026

What line item properties actually are

Every line item in a Shopify cart can carry an arbitrary number of custom key-value pairs. These pairs are called "line item properties." They originate from the customer's form submission on the product page (or via a personalizer app's API call), travel with the line item through cart and checkout, and land on the resulting Shopify order as a structured field.

The underlying data shape is a key-value map per line item. Stored in the order JSON as:

"properties": [
  { "name": "Custom text", "value": "Happy Birthday Mom" },
  { "name": "Font", "value": "Dancing Script" },
  { "name": "Color", "value": "Gold" },
  { "name": "_print_file_url", "value": "https://cdn.shopify.com/.../design-12345.png" }
]

The Liquid representation iterates as an array of key-value pairs accessible via .first and .last:

{% for property in line_item.properties %}
  {{ property.first }}: {{ property.last }}
{% endfor %}

How to capture line item properties (no app)

Add an HTML form input to your product page's add-to-cart form with the name attribute prefixed by properties[]:

<label for="custom-text">Custom text:</label>
<input type="text" id="custom-text" name="properties[Custom text]" maxlength="20">

<label for="font">Font:</label>
<select name="properties[Font]">
  <option value="Roboto">Roboto</option>
  <option value="Playfair Display">Playfair Display</option>
  <option value="Dancing Script">Dancing Script</option>
</select>

<label for="photo">Upload photo:</label>
<input type="file" name="properties[Photo]">

When the customer submits the add-to-cart form, Shopify captures each properties[...] input as a line item property on the resulting cart line. File inputs are auto-uploaded to Shopify's Files CDN and stored as URL values.

This works without any app. For real personalization at production scale you'll want validation (character limits, file size/format checks, DPI warnings), a live preview UI, font picker, mobile-friendly upload flow, and Cart Transform-based pricing — which is what apps like Print It My Way provide on top of the same underlying line-item-properties mechanism.

Liquid reference: product page

To display line item properties already in the cart on the product page (e.g., to show "already in cart with X customization"):

{% for item in cart.items %}
  {% if item.product_id == product.id %}
    {% for property in item.properties %}
      {% unless property.last == blank or property.first.first == '_' %}
        <p>{{ property.first }}: {{ property.last }}</p>
      {% endunless %}
    {% endfor %}
  {% endif %}
{% endfor %}

Critical: the unless clause filters two things: empty properties (Shopify creates blank properties for empty form fields by default) and underscore-prefixed properties (hidden by convention).

Liquid reference: cart page

In sections/main-cart-items.liquid or your theme's cart template:

{% for item in cart.items %}
  <div class="cart-item">
    <h3>{{ item.product.title }}</h3>
    {% if item.properties.size != 0 %}
      <ul class="cart-item-properties">
        {% for property in item.properties %}
          {% unless property.last == blank or property.first.first == '_' %}
            <li>
              <strong>{{ property.first }}:</strong>
              {% if property.last contains '/uploads/' %}
                <a href="{{ property.last }}" target="_blank">View file</a>
              {% else %}
                {{ property.last }}
              {% endif %}
            </li>
          {% endunless %}
        {% endfor %}
      </ul>
    {% endif %}
  </div>
{% endfor %}

The property.last contains '/uploads/' check detects file URLs and renders them as clickable links instead of raw URLs.

Liquid reference: checkout (legacy checkout.liquid)

If you're still on checkout.liquid (Shopify Plus, deprecated as of Aug 2024), the syntax is the same as the cart loop above. For new Shopify Checkout Extensibility, line item properties are accessed via the Checkout UI Extensions API, not Liquid. See our Cart Transform deep dive for the modern pattern.

Liquid reference: order confirmation email

In Settings → Notifications → Order confirmation → Edit code, find the {% for line in subtotal_line_items %} loop and add:

{% for line in subtotal_line_items %}
  <p>{{ line.title }} × {{ line.quantity }}</p>
  {% if line.properties.size != 0 %}
    {% for property in line.properties %}
      {% unless property.last == blank or property.first.first == '_' %}
        <p style="margin-left:20px;font-size:13px;color:#666;">
          <strong>{{ property.first }}:</strong> {{ property.last }}
        </p>
      {% endunless %}
    {% endfor %}
  {% endif %}
{% endfor %}

The same loop works for the Shipping confirmation, Refund, and Abandoned cart email templates. Always test with a draft order before going live — email client rendering (Gmail, Outlook, Apple Mail) varies and inline styles are required for predictable formatting.

Liquid reference: admin order detail

The Shopify admin order detail page renders line item properties automatically — no Liquid edits needed. Underscore-prefixed properties show in a separate "Other details" expandable section. Properties with file URLs render as clickable "View file" links.

For custom admin views (Shopify Plus Flow apps, custom dashboards), access via the GraphQL Admin API:

query {
  order(id: "gid://shopify/Order/123456") {
    lineItems(first: 10) {
      nodes {
        title
        customAttributes {
          key
          value
        }
      }
    }
  }
}

Note: in GraphQL, line item properties are called customAttributes (Shopify's API naming inconsistency). The data is identical.

Hidden properties (underscore convention)

Any property whose name starts with _ (underscore) is treated as hidden by Shopify's customer-facing surfaces (cart page, checkout, order confirmation email). The property is still saved on the order and accessible via the Admin API, Liquid templates (after explicit access), and the admin order detail page (in the "Other details" section).

Use hidden properties for production data the customer doesn't need to see:

• _print_file_url — URL of the print-ready PNG/PDF for your POD vendor
• _design_json — raw design state (text positions, font sizes, color codes) for re-editing
• _personalizer_app_version — which version of the app captured this design
• _fulfillment_routing — internal vendor or warehouse routing tag
• _thumbnail_url — pre-rendered design thumbnail for fulfillment

These are not encrypted or secret. They're just visually suppressed in default surfaces. If the customer inspects the order JSON via Admin API or asks for their data under GDPR, hidden properties show. Don't put truly sensitive data in line item properties.

File uploads via line item properties

Use a standard HTML <input type="file"> in your product form with a properties[...] name:

<input type="file" name="properties[Upload your design]"
       accept=".png,.jpg,.jpeg,.svg"
       max-size="10485760">

Shopify's file upload flow:

1. Customer selects file, browser uploads it to Shopify's Files CDN
2. Shopify returns a CDN URL (https://cdn.shopify.com/...uploads/...)
3. The URL is captured as the line item property value (not the binary file)
4. Cart, checkout, order email show a "View file" link to the CDN URL
5. POD vendor reads the URL from the order and downloads the file for production

File size limit: 20MB per upload (Shopify default). Allowed types are governed by the accept attribute and Shopify's MIME-type filter. For HEIC support (iPhone default format), you'll need an app that converts server-side — native Shopify doesn't accept HEIC.

Line item properties vs cart attributes

Both are custom key-value stores on the cart/order, but at different granularity:

Aspect	Line item properties	Cart attributes
Scope	Per line item	Per cart (entire order)
Use case	Per-product personalization (engraving text per item)	Order-level data (delivery date for whole shipment, gift note)
Liquid loop	{% for property in line.properties %}	{% for attribute in cart.attributes %}
Form input	name="properties[Key]"	name="attributes[Key]"
Stays with item on split orders	Yes	Stays with parent order
Visible in admin	Yes, inline on line item	Yes, in order notes section

4 common bugs and fixes

Bug 1: Empty property values show as blank lines

If you don't filter property.last == blank, every empty form field creates a blank "Key: " line in the cart and email. Always wrap your loop in:

{% unless property.last == blank %}...{% endunless %}

Bug 2: Hidden properties showing up on customer surfaces

The underscore convention is honored by Shopify's default templates but NOT automatically by your custom Liquid. If you wrote your own cart loop and forgot to filter underscores, hidden production data leaks to the customer:

{% unless property.first.first == '_' %}...{% endunless %}

The property.first.first grabs the first character of the property name to check for the underscore prefix.

Bug 3: File URLs render as raw text instead of links

Without explicit detection, file URLs show as plain text in your cart loop. Use a contains '/uploads/' check to render them as anchors:

{% if property.last contains '/uploads/' %}
  <a href="{{ property.last }}" target="_blank">View file</a>
{% else %}
  {{ property.last }}
{% endif %}

Bug 4: Properties lost between cart and checkout

If you have a custom checkout template (checkout.liquid on Plus, or a custom-coded section) that doesn't preserve properties, they vanish at checkout. Cart Transform–based personalization apps (Print It My Way) handle this automatically by storing personalization fees as line items. If you're seeing this with a vanilla theme, check your theme's add-to-cart JavaScript isn't stripping the properties array before submit.

When you need an app (and when you don't)

Native Shopify line item properties handle the data capture and transport perfectly. Where you need an app:

• Live preview canvas — rendering the customer's design on the product image in real time as they type
• Font picker UI — loading and previewing 35+ Google Fonts in a dropdown
• Photo upload validation — file size/format checks, HEIC support, DPI warnings before checkout
• Conditional logic — "show field B only when field A = X" without writing JavaScript
• Cart Transform pricing — adding personalization fees as clean cart line items via Shopify Functions
• Mobile UX — touch-friendly canvas, mobile camera roll integration, responsive layouts
• Admin dashboard — viewing all custom orders with inline previews

For native (no-app) line item property capture, the HTML form inputs in this guide are sufficient. For anything visual, add a personalizer app — they all use line item properties as the underlying transport, so your fulfillment workflow is identical regardless of which app you pick.

Frequently asked questions