Skip to content

Cart & Checkout ​

The cart system consists of a mini-cart (sidebar drawer), an "Item added" popup under the header, and a full cart page. All three read the same Vuex cart store (src/vue/store/cart.js) and render parts of the same Vue component tree (src/vue/components/StoreCart/).

PieceLiquid entry pointVue component
Mini-cart drawersnippets/cart.liquid (header cart icon)StoreCart → StoreCartBody (fixed: true)
"Item added" popupsnippets/mini-cart-single-product.liquidStoreCartSingleProduct
Full cart pagesections/main-cart.liquid (templates/cart.json)StoreCart → StoreCartBody (fixed: false)
Cart store--src/vue/store/cart.js (Vuex module cart)

Theme B only

The Savings row (Total Savings) and the _theme_id cart attribute for Checkout Savings exist on Theme B (staging) only. Everything else on this page applies to both themes -- see Theme A vs Theme B.

Cart Store (Optimistic Cart) ​

File: src/vue/store/cart.js

Every cart change is shown on screen immediately and sent to Shopify's AJAX Cart API in the background. If the request fails, the change is rolled back and an error toast is shown.

ActionWhat the buyer sees at onceRequest
addItemA placeholder line (built from the product JSON already on the page) is added to the top of the cart and the "Item added" popup opensPOST /cart/add.js
removeItemThe line disappearsPOST /cart/update.js (quantity 0)
updateItemNew quantity and totals; quantity 0 removes the linePOST /cart/update.js
updatePlanNew subscription plan and price on the linePOST /cart/change.js (keeps line properties and position)
updateNoteNote textPOST /cart/update.js
applyDiscountWaits for Shopify (only Shopify knows if a code is valid)GET /discount/CODE, then GET /cart.js
removeDiscountsCode chip and discount disappear at oncePOST /cart/update.js with discount: ""

How it stays consistent:

  • Queued requests. Mutations run one after another (queueCartMutation), so fast clicking never races.
  • Key aliases. Shopify gives a line a new key when it is added or its plan changes. The store maps old keys to new ones, so the buyer can keep changing a line while an earlier request for it is still running.
  • Stable rows. Each line keeps a viewKey, so a row is updated in place instead of being re-mounted (no fade/flicker).
  • Background refresh. After the queue drains, the store re-reads /cart.js. A refresh that is already stale (the cart changed while it was in flight) is dropped.
  • Cart-level discounts (codes, automatic order discounts) are carried over when totals are re-computed locally: percentage discounts scale with the lines, fixed amounts stay.
  • Errors appear as a toast at the bottom of the screen ("Couldn't add item to cart", "Couldn't update quantity", ...) for 4 seconds (ERROR_TIMEOUT).

The store also loads /products/HANDLE.js for every line (loadProductDetails), which gives the cart the one-time variant prices and the product's selling plans.

Mini-Cart (Sidebar) ​

Snippet files: snippets/cart.liquid, snippets/mini-cart.liquid

The mini-cart is a slide-out drawer (400px wide on desktop, full width on mobile) opened by the header cart icon. The drawer is rendered inside snippets/cart.liquid:

liquid
<store-cart
  :cart="{% render 'helper-cart-js' %}"
  :fixed="true"
  upsale_products="{% render 'helper-best-sellers' data: settings.upsale %}"
  :anouncements="[ ...cart announcement settings... ]"
>

Clicking outside the drawer closes it. While open, page scrolling is locked.

Drawer layout (top to bottom) ​

  1. Announcement slider -- the two cart announcements from Theme Settings (announcementLabel / announcementLabel2), falling back to the site announcement bar texts.
  2. Free shipping bar -- see Free Shipping Progress Bar.
  3. "Your Cart" title with item count and close button.
  4. Line items -- image, title, price (with the one-time price struck through when a subscription or discount lowers it), quantity stepper, remove icon, and subscription controls (see Subscriptions in the Cart).
  5. Gift note (if enable_note).
  6. Upsell carousel -- "You might also like" (one product per slide, arrows).
  7. Subtotal -- with the full one-time total struck through when subscriptions or discounts lower the price.
  8. Savings row (Theme B only) -- see Total Savings.
  9. Discount code field.
  10. Checkout button -- a plain link to /checkout.
  11. GWP progress bar and gift list (if gwp_enabled).

When the cart is empty, the drawer shows "Looks like your cart is empty", the line "Add your pet's favorite items to the cart!" (the component's empty_cart_label default -- no Liquid overrides it) and a Shop Now button linking to /collections/shop-all.

TIP

The Theme Settings emptyCartLabel and emptyCartLink / emptyCartLinkUrl (x3) are serialized by helper-cart-js, but the cart components do not render them. Likewise gwp_subscription_in_cart, gwp_mini_cart_disclaimer and gwp_mini_cart_removal_notification are not read anywhere; the GWP subscription note is hard-coded.

Wholesale Override ​

For Wholesale Gorilla customers (window.isWsgCustomer), snippets/wsg-custom.liquid points the cart icon link at /cart (full page) and hides Shopify Pay / additional checkout buttons.

"Item Added" Popup ​

Snippet file: snippets/mini-cart-single-product.liquidComponent: src/vue/components/StoreCart/StoreCartSingleProduct.vue

When a product is added and the drawer is closed, a small panel drops down under the header instead of opening the full drawer. It shows:

  • The free shipping bar (the snippet passes :cart from helper-cart-js, which carries the threshold).
  • "Item added to your cart" with the line that was just added.
  • View Cart (N) -- opens the drawer.
  • Checkout -- link to /checkout.
  • Continue Shopping -- closes the popup.

Full Cart Page ​

Section file: sections/main-cart.liquidTemplate: templates/cart.json

The full cart page renders the same <store-cart> component with :fixed="false":

liquid
<store-cart
  :cart="{% render 'helper-cart-js' %}"
  :fixed="false"
  upsale_products="{% render 'helper-best-sellers' data: settings.upsale %}"
>

Layout on desktop: line items on the left; a 35% right column with the free shipping bar, "You might also like" list (not a carousel), subtotal, savings (Theme B only), discount code and Checkout button.

GWP Product Display ​

The cart page (and the drawer) include a #gwplist template slot that renders up to 3 gift products. Each GWP product shows:

  • Product thumbnail image (with variant-specific image support)
  • Product title and variant name
  • Action button: "Add" (available, not in cart), "Added" (already in cart), or "Sold" (out of stock)

The component tracks GWP state through scoped slot variables: addGWPtoCart, cartHasGWP, cartHasGWP1, cartHasGWP2.

Cart Configuration Data ​

Snippet file: snippets/helper-cart-js.liquid

This snippet serializes all cart settings into a JSON-like object consumed by <store-cart> and <store-cart-single-product>:

PropertySource SettingPurpose
freeShippsettings.free_shipping_amtFree shipping threshold
upsale_enabledsettings.enable_upsaleUpsell toggle
upsale_headlinesettings.upsale_headlineUpsell section heading (drawer only)
gwp_enabledsettings.gwp_enabledGWP master toggle
gwp_productsettings.gwp_product variant IDFirst GWP product
gwp_product_1settings.gwp_product_1 variant IDSecond GWP product
gwp_product_2settings.gwp_product_2 variant IDThird GWP product
thresholdsettings.gwp_thresholdFirst GWP spending threshold
threshold_settings.gwp_threshold_Second GWP spending threshold
promocodesettings.gwp_discount_codeFirst discount code
promocode_settings.gwp_discount_code_Second discount code
emptysettings.gwp_empty_cart_textEmpty cart GWP message
approachingsettings.gwp_approaching_textProgress message (with [XX] placeholder)
congratssettings.gwp_congrats_textThreshold reached message
lineItemsettings.gwp_line_item_typeGWP line item label
disclamersettings.gwp_line_item_disclaimerDiscount disclaimer
gwpActivatedsettings.gwp_added_gift_textGift claimed message
emptyCartHeadlinesettings.emptyCartLabelEmpty cart headline (not rendered by the cart components)
emptyCartLink/Urlsettings.emptyCartLink/Url (x3)Empty cart navigation links (not rendered by the cart components)
note_lablesettings.note_lableGift note label
note_placeholdersettings.note_placeholderGift note placeholder
enable_notesettings.enable_noteGift note toggle

Free Shipping Progress Bar ​

Component: src/vue/components/StoreCart/FreeShippingBar.vue

One shared component renders the bar in the drawer (top), on the cart page (right column) and in the "Item added" popup.

  • Threshold: Theme Settings > Cart > Free Shipping Amount (free_shipping_amt, currently $50).
  • Compared against: the cart total_price (after discounts).
  • Messages (hard-coded in the component): "You are $X.XX away from free shipping!" and, once reached, "Congrats! You get free shipping."
  • Hidden when the cart is empty or the threshold is 0.

Subscriptions in the Cart ​

Component: src/vue/components/StoreCart/CartItem.vue.vue

Each line uses the product's selling plans (from /products/HANDLE.js):

  • Subscription line -- a dropdown lists every selling plan; picking another plan switches the line in place (updatePlan → /cart/change.js).
  • One-time line -- a "+ Upgrade to Subscription and Save 10%" link converts the line to a subscription. It picks the second selling plan in the list (the 4-week plan).
  • The upgrade link is hidden for products whose first variant has custom.disable_subscription = true (the window.Shopify.hide_product_ids list built by snippets/products-hidde-subscription.liquid).
  • The struck-through price under a line is the one-time price of that line's variant, not the product's lowest variant price.

WARNING

The upgrade link assumes the product has at least two selling plans (computedPlans[1]). A product with a single plan would throw on click.

Total Savings ​

Theme B only (staging). Theme A (master) has no Savings row.

Component: src/vue/components/StoreCart/StoreCartBody.vue (totalSavings)

A Savings row under the subtotal (green, text-ss3_green, semibold) shows how much the buyer saves compared with buying everything one-time at full price:

savings = Σ (one-time price × quantity) − cart total_price

It therefore includes subscription discounts and discount codes / automatic discounts. The row is hidden when the saving is $0. The same saving is shown in checkout by the Checkout Savings extension.

WARNING

totalSavings uses the product's price from /products/HANDLE.js, which is the cheapest variant's price. For a larger size the "full price" is understated, so the savings row can be too low or hidden. The per-line struck-through price, by contrast, uses the variant price.

Checkout Savings (Theme ID) ​

Theme B only (staging). Theme A (master) does not write the attribute.

Super Snouts uses the custom checkout UI extension Checkout Savings (block name in the checkout editor: Subscription savings) to show subscription savings in checkout. See Checkout Savings for the app itself (shop metafield custom.shipping_cost, message placeholders, setup).

What the theme writes ​

Checkout cannot tell which theme the buyer shopped on. So the theme copies the theme ID into a hidden cart attribute:

AttributeValueWritten by
_theme_idwindow.Shopify.theme.id (e.g. 173548077363 on Theme B)syncThemeAttribute action in src/vue/store/cart.js
  • It runs once per page load, after the first successful /cart.js read, and only when the cart has items (an empty cart is retried after the first add).
  • If the attribute already holds the right ID, nothing is sent. Otherwise it posts attributes: { _theme_id: ... } to /cart/update.js. On error it is retried on the next cart read.
  • The leading underscore keeps the attribute out of Shopify's default cart/order displays.

Why ​

The extension's Theme ID setting can limit the savings block to carts that came from one theme. This is what lets the block run only on one arm of an Intelligems theme test (Theme A 176347447603 vs Theme B 173548077363, see Deployment & Branching). A cart without the attribute never matches a Theme ID filter; carts from Theme A (master) carry no attribute.

Keep the block placed in checkout

The extension removes _theme_id from the cart as soon as checkout loads (so it never lands on orders), whatever the Theme ID setting. If the Subscription savings block is removed from the checkout editor, nothing strips the attribute and it shows up in the order's Additional details. Keep the block placed on this store as long as the theme writes the attribute.

No accelerated checkout buttons on PDP / cart

Apple Pay / Google Pay / Shop Pay buttons started from a product or cart page skip the checkout extension, so the attribute would survive onto the order. The SSHC theme renders no dynamic/accelerated checkout buttons (the product form and cart use plain "Add to Cart" / /checkout links, and wsg-custom.liquid hides .shopify-payment-button / .additional-checkout-buttons for wholesale). Do not add payment_button or content_for_additional_checkout_buttons to the theme -- or stop writing the attribute if you do.

Discount Codes ​

Component: src/vue/components/StoreCart/DiscountCode.vue

  • Placeholder: "Discount Code or Gift Card". Apply with the APPLY button or Enter.
  • Applying waits for Shopify. The component calls cart/applyDiscount; if the returned cart has no cart_level_discount_applications, it shows "The discount code you entered is invalid or cannot be applied to the items in your cart."
  • An applied code shows as a purple chip with an X. Removing it is optimistic (chip and total update immediately).
  • The last applied code is remembered in localStorage (discountCode).

Upsell System ​

When enable_upsale is true:

  1. Products from the upsale product list are displayed (currently 4 configured).
  2. The drawer heading uses upsale_headline (default: "You might also like"); the cart page always says "You might also like".
  3. Products are serialized via the helper-best-sellers snippet.
  4. Products already in the cart (matched by handle) are excluded.
  5. Each upsell card has an Add button that adds the first available variant (optimistically).

Gift with Purchase (GWP) ​

The GWP system is a tiered promotional feature with two spending thresholds.

GWP Flow ​

  1. Empty cart: Displays gwp_empty_cart_text (currently: "Spend $85 to get a free gift!")
  2. Approaching threshold: Shows gwp_approaching_text with remaining amount replacing [XX] (currently: "Only $[XX] away from free gift!")
  3. Threshold 1 reached (gwp_threshold, currently $85): Shows gwp_congrats_text, reveals GWP product selection
  4. Threshold 2 reached (gwp_threshold_, currently $0 / disabled): Applies second discount code
  5. Gift added: Shows gwp_added_gift_text confirmation (currently: "You have claimed your free gift!")

Subscription lines do not count towards the GWP total; a note "*subscription products do not count towards gift with purchase" appears when the cart contains them. A gift is removed automatically if the rest of the cart drops below the threshold.

INFO

The GWP feature is currently disabled (gwp_enabled: false) and no gift product is selected (gwp_product is blank). To activate it, pick products and enable it in Theme Settings > Gift with Purchase.

GWP Products ​

Up to 3 products can be configured as free gifts. Each product:

  • Is selected via a product picker in Theme Settings
  • Has a configurable variant (by order number, 1-indexed)
  • Shows with "Add" / "Added" / "Sold" button states
  • Displays the gwp_line_item_type label (default: "Free Gift!") and gwp_line_item_disclaimer

GWP Discount Codes ​

Two discount codes can be configured (gwp_discount_code, gwp_discount_code_) and are passed to the checkout. The discount is reflected at checkout, not in the cart subtotal.

Gift Note ​

When enable_note is true:

  • A text area appears in the cart (max 150 characters, emojis are stripped, a counter shows remaining characters)
  • Label: note_lable (default: "Is This a Gift? Add a Note!")
  • Placeholder: note_placeholder (default: "Enter a message for your lucky, furry friend here.")
  • The note is saved as the cart note on blur and passed to the order; it is cleared when the cart is emptied

Current status: Gift note is disabled (enable_note: false)

Cart Announcements ​

Two announcement slots are available for the cart drawer:

  • announcementLabel / announcementLink -- First announcement
  • announcementLabel2 / announcementLink2 -- Second announcement

They rotate in a green slider at the top of the drawer. If both are blank, the drawer reuses the site-wide announcement bar texts.

Antelope Themes Documentation

Enter the password to access this site.