Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 61 ยท Cart, Checkout and Customer Pages

Cart, Discounts and the Path to Checkout

Learn the Shopify cart object, line items, cart attributes and discount display, how shipping estimates work, and what a theme can and cannot change at checkout.

Everything a shopper has chosen lives in one object: cart. Your theme reads it to draw the cart page and the drawer, to show totals and discounts, and to start the journey to checkout. But there is a hard border in this story. The cart belongs to your theme. Checkout does not. Shopify hosts it, secures it and controls how it can be customized, and a theme developer needs to know exactly where that border runs so they never promise a client something that a theme cannot deliver.

This lesson covers the cart and line item objects, cart attributes and notes, how discounts appear in Liquid, shipping estimates, the checkout button, and the checkout customization options that exist outside the theme. It builds on The Product Form and Add to Cart and Building a Cart Drawer.

The Liquid, forms and endpoints below are read-only: they run only on Shopify. The stand-ins are JavaScript re-creations that show the arithmetic and the form parsing. Property names reflect current Online Store 2.0 themes; confirm them against the current Liquid reference for your target stores.

The cart object

These properties cover most cart pages:

Property Meaning
cart.items array of line items
cart.item_count total quantity of all lines (not the number of lines)
cart.items_subtotal_price sum of line prices after line-level discounts
cart.original_total_price total before any discounts
cart.total_price total after discounts, before shipping and (often) before taxes
cart.total_discount total saved by all discounts
cart.cart_level_discount_applications discounts that apply to the whole cart
cart.note the free-text note
cart.attributes key-value data attached to the cart
cart.requires_shipping true if any line needs shipping
cart.currency.iso_code the cart currency

All money values are integers in the smallest currency unit, so you print them with the money filter and never do float math on them (the reasoning is in Money as Integers). For the data-design view of carts in general, see Designing the Cart.

Be careful with the difference between item_count and the number of lines. A cart holding three mugs and one towel has item_count of 4 and cart.items.size of 2. Use item_count in the header badge and items.size when you need to know whether any lines exist.

Line items

Each element of cart.items is a line item. The properties you will use most:

LIQUID
{%- for item in cart.items -%}
  <li>
    <a href="{{ item.url }}">{{ item.product.title }}</a>
    {%- unless item.product.has_only_default_variant -%}
      <span>{{ item.variant.title }}</span>
    {%- endunless -%}

    {%- if item.original_price != item.final_price -%}
      <s>{{ item.original_price | money }}</s>
    {%- endif -%}
    <span>{{ item.final_price | money }}</span>
    x {{ item.quantity }}
    = {{ item.final_line_price | money }}

    {%- for allocation in item.line_level_discount_allocations -%}
      <p>{{ allocation.discount_application.title }}: -{{ allocation.amount | money }}</p>
    {%- endfor -%}

    {%- for property in item.properties -%}
      {%- unless property.last == blank -%}
        <p>{{ property.first }}: {{ property.last }}</p>
      {%- endunless -%}
    {%- endfor -%}
  </li>
{%- endfor -%}

original_price is the unit price before discounts and final_price is after line-level discounts. The *_line_price versions multiply by quantity. Line item properties (the custom engraving text, a gift message per item) arrive as item.properties. Properties whose name starts with an underscore, such as _bundle_id, are hidden from the customer in checkout and emails but still readable in Liquid, so skip them yourself if you do not want them on screen.

Cart attributes and the note

The cart also carries data that does not belong to a single product. The note is one free-text field. Attributes are named values, created by inputs whose name looks like attributes[some_key]:

LIQUID
<form action="{{ routes.cart_url }}" method="post" id="CartForm">
  <label for="CartNote">Order note</label>
  <textarea id="CartNote" name="note">{{ cart.note }}</textarea>

  <label>
    <input type="checkbox" name="attributes[gift_wrap]" value="Yes"
      {% if cart.attributes.gift_wrap == 'Yes' %}checked{% endif %}>
    Gift wrap this order
  </label>

  <button type="submit" name="update">Update</button>
  <button type="submit" name="checkout">Check out</button>
</form>

Attributes survive into the order, which means the warehouse or an app can read them later. The bracket syntax is a form-encoding convention that Shopify (and many frameworks) parse into a nested object. The first stand-in below parses it so you can see exactly what arrives.

How discounts show up

The theme does not calculate discounts. Shopify applies discounts (automatic ones and codes) and your Liquid only displays the result:

  • Line-level discounts are in item.line_level_discount_allocations, and each one points to a discount_application with a title.
  • Cart-level discounts are in cart.cart_level_discount_applications, each with a title and total_allocated_amount.
  • cart.total_discount is the overall saving, useful for a "You saved" line.
LIQUID
{%- if cart.cart_level_discount_applications.size > 0 -%}
  <ul>
    {%- for discount in cart.cart_level_discount_applications -%}
      <li>{{ discount.title }} (-{{ discount.total_allocated_amount | money }})</li>
    {%- endfor -%}
  </ul>
{%- endif -%}

Do not hard-code a promotion in the theme ("10% off applied!") because the cart already tells you what really happened. The rules behind stacking, priority and eligibility are explained in Building a Promotions Engine. Notice also that discounts that depend on shipping or on the shopper's identity may only be finalized in checkout, so a cart page can legitimately show less than the final total.

flowchart LR
  A["Cart page<br/>(your theme)"] -->|"checkout button"| B["Checkout<br/>(hosted by Shopify)"]
  B --> C["Order confirmation"]
  A -.->|"reads"| D["cart object<br/>items, attributes, discounts"]
  B -.->|"reads cart, adds shipping<br/>taxes, payment"| D

The theme draws the cart; Shopify takes over at the checkout button.

Stand-in: totals and savings

This stand-in computes the same figures Shopify gives you ready-made. In a real store you read them; here you can watch how line prices, discount allocations and the cart total relate. All values are cents.

JS Stand-in: cart totals with discount allocations

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The saved amount of $9.00 is the $4.00 mug discount plus the $5.00 cart-level code. In Shopify those relationships are already computed for you, which is why your theme should display values rather than recreate the rules.

Stand-in: how bracket names become data

A form field named attributes[gift_wrap] becomes { attributes: { gift_wrap: 'Yes' } } on the server. This stand-in parses a URL-encoded body the way a framework would, so you can see how names map to structure.

JS Stand-in: parsing attributes[...] field names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last line shows how the server knows which submit button was pressed: a button's name is sent only for the button that was clicked. A button named checkout sends the shopper onward, while one named update stays on the cart page.

The checkout button and what themes cannot change

The cart form posts to routes.cart_url. A submit button named checkout tells Shopify to save the changes and redirect to checkout. Optionally, {{ content_for_additional_checkout_buttons }} renders accelerated wallet buttons (such as Shop Pay and others the store has enabled) inside the cart form. Without a form submit, JavaScript can send the shopper to routes.root_url | append: 'checkout', but it must save the note and attributes first, or they are lost.

What a theme cannot do:

  • change the checkout page markup or CSS with Liquid. Checkout is not part of the theme folder;
  • run arbitrary JavaScript inside checkout;
  • decide shipping rates, taxes or payment methods.

Customization of checkout happens through Shopify's checkout extensibility instead: a branding configuration (colors, fonts, logo), UI extensions that place app-built components at defined spots, and Functions that change logic such as discounts, delivery options and payment method ordering. Older approaches that edited a checkout template have been retired in favor of these, so treat any tutorial that edits a checkout template as outdated and check the current docs. Which features are open to which plan has also changed over time, so verify before you promise anything to a client.

For the commerce concepts behind these steps, read Checkout Flow and Conversion, Taxes and Shipping Rates.

Shipping estimates in the cart

Shoppers like to see shipping cost before checkout. Themes can show an estimate calculator, either from an app or by calling the storefront shipping-rates endpoints with a country, province and postal code. The request is asynchronous: you ask Shopify to prepare the rates and then poll for the result, so build a loading state, an error message for unknown addresses and a "no rates found" state. Do not present the number as final. Taxes, discounts and the exact address are settled in checkout, and an estimate that is off by a little is better explained ("Estimated shipping") than hidden.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A cart holds 3 mugs and 1 tea towel. What is cart.item_count?

    item_count adds up all quantities (3 + 1 = 4). The number of lines is cart.items.size, which is 2.
  2. 2. Where should discount amounts shown in the cart come from?

    Shopify applies discounts. The theme reads line_level_discount_allocations and cart_level_discount_applications and displays the result.
  3. 3. Which of these can a theme NOT do?

    Checkout is hosted by Shopify and customized through checkout extensibility, not through theme Liquid.
  4. 4. An input is named attributes[gift_wrap]. How does it end up on the cart?

    Bracket names are parsed into a nested object, and the attributes group becomes cart attributes that later travel with the order.

Summary

  • The cart object gives items, counts, totals, notes, attributes and discount applications; all money is integer cents.
  • Line items expose original and final prices, line-level discount allocations and properties.
  • Attributes and the note are set with form fields named attributes[...] and note.
  • Display discounts; never recalculate them in the theme.
  • A button named checkout hands over to Shopify's hosted checkout, which is customized with checkout extensibility rather than Liquid.

Next, follow the shopper beyond the cart: Customer Accounts and Account Pages.