Every other page on this site is written for merchants. This section is not. It is for theme developers and agencies customising a store that runs CartSella: what the app puts in the cart, how to read it, and what will break if you change it.
Everything here is storefront-side and readable from Liquid or from /cart.js. Nothing on these pages requires an API key, an app proxy call, or access to the CartSella admin.

​
How CartSella works, in one paragraph

CartSella stores its offer and upsell configuration in shop metafields, and a script in the theme app embed reconciles the cart against that configuration. When a shopper adds a qualifying product, the script adds the gift line. When they change quantity, remove the trigger, or drop below a spend threshold, the same script removes or resizes the gift line. Discounting happens later, in Shopify Functions at checkout, which read the same markers off the cart lines. The markers are ordinary Shopify line item properties and cart note attributes. There is no hidden channel. This is the whole contract: Both are documented in full in Cart line properties.

​
The one rule

CartSella reconciles the cart from these properties. A gift line is recognised as a gift because of what is on it, not because of what it is. Strip the properties, rename them, or rewrite them, and the line stops being a gift: the sync engine will not manage it, the discount Function at checkout will not discount it, and the shopper pays full price for something the storefront promised was free.
This cuts both ways. Reading the properties is entirely safe and is the supported way to build custom cart UI. Writing them is not.

​
What you can safely change

1

Rendering

Render CartSella lines however you like. Hide the price on a gift, swap in a badge, hide the quantity stepper, move the line, restyle it. Read the properties, branch on them, output your own markup.
2

Hiding the properties from the shopper

All CartSella properties begin with an underscore, so a theme that follows the standard convention already hides them from the line item property loop. If yours does not, filter them out.
3

Reacting to cart changes

CartSella dispatches cart:updated, cart:refresh and cart:change on both document and window after every cart mutation it makes, with event.detail.cart holding the fresh cart and event.detail.source naming the writer. Listen to those instead of polling.
4

Custom cart sections

If your theme renders the cart through the Section Rendering API, CartSella refreshes it after each mutation. If your cart is a hand-rolled snippet the API cannot reach, CartSella falls back to a full reload. Either way you can rebuild your own UI from /cart.js.

​
What you must not change

Each of these is spelled out with its consequence on the gift with purchase page.

​
Legacy property names

CartSella renamed its properties in 2026 to reduce clutter in the Shopify admin. Every old name is still read, permanently. A shopper with a tab that has been open since before the rename keeps running the cached script and keeps writing the old names, so both formats coexist in live carts indefinitely. If you read these properties, accept both spellings. The reference tables mark every legacy name, and each recipe on the gift with purchase page reads both.

​
Where to go next

Cart line properties

The full reference: every property and note attribute, its format, who writes it and who reads it.

Gift with purchase

How trigger and reward lines are marked, and code you can paste into a theme.