Cart line properties

CartSella marks the cart with ordinary Shopify line item properties and cart note attributes. Everything on this page is visible in /cart.js, in Liquid via item.properties and cart.attributes, and on the order in the Shopify admin.

All property names begin with an underscore. Shopify treats underscore-prefixed line item properties as private: they are not shown to the shopper in checkout, and themes conventionally skip them in the line item property loop.

Line item properties

Read these freely. Do not write, rename or strip them. See the rules.

Property	Written by	Read by	Format	Example	Legacy read-only
`_cs`	Theme app embed on `/cart/add.js`, the gift sync engine, bundle and upsell blocks, the campaign link loader	Theme runtime, checkout extensions, discount Functions, order attribution	`id:type:subtype`, joined with `\|` when one line belongs to more than one entity	`9f3c…:offer:gift_with_purchase`	No
`_cs_role`	Same writers as `_cs`	Theme runtime, checkout extensions, all three discount Functions	`item` or `reward`. Comma-separated if a line somehow carries both	`reward`	No
`_cs_slot`	Bundle builder and pick-your-bundle blocks	Theme runtime, gift discount Function	Slot key string. Comma-separated positional list when a line was reconciled into several slots	`slot-1`	No
`_cs_gift_for`	Gift sync engine, campaign gift pre-add	Gift sync engine, when reconciling gift quantity per trigger	Variant id of the trigger product that earned this gift. Absent for spend-threshold gifts and when only one trigger product is in the cart	`43210987654321`	No
`_cs_gift_prefix`	Gift sync engine	Cart Transform, which rewrites the gift line title at checkout; the theme runtime, which mirrors the same prefix in the cart DOM	String. `""` means “no prefix”. Absent means the default gift emoji	`🎁`	No
`_cs_cids`	Theme app embed on `/cart/add.js`, when the product page exposes its collections	Theme runtime, to decide whether an already-in-cart line belongs to a collection an offer targets	Comma-separated bare numeric collection ids	`287654321098,287654321099`	No
`_trigger_offer_id`	Theme app embed on `/cart/add.js`, the gift sync engine’s self-heal pass, the campaign link loader	Theme runtime, checkout guard extension, order attribution	Comma-separated, sorted list of offer ids this line qualifies for	`9f3c…,2b71…`	No
`_cs_subtotal_gift` / `_cs_subs_subtotal_gift`	Gift sync engine, on gifts earned by a spend threshold	Nothing. Write-only marker	`"true"`	`true`	No
`_cs_campaign_slug` / `_cs_campaign_link_id`	Campaign link loader	Theme runtime and order attribution, to credit the campaign	String	`spring-drop`	No
`_cartsella_product_id`	The fixed bundle block, and any theme that adds it by hand as a hidden cart form field	Theme runtime, to resolve a line’s product id when Shopify has not returned one yet	Product id or `gid://shopify/Product/N`	`7654321098765`	No, and deliberately never renamed
`_gift_triggered_by`	Only the checkout guard extension, when it self-heals a gift line	Theme runtime and the checkout guard	Comma-separated offer ids. On a self-healed line this can be the union of several offers sharing one trigger line	`9f3c…`	No, but treat as optional
`_cartsella_id` / `_cartsella_type` / `_cartsella_subtype`	Nothing writes these any more	Everything that reads `_cs` falls back to them	Three parallel comma-separated lists, paired by position	`9f3c…` / `offer` / `gift_with_purchase`	Yes
`_cartsella_role`	Nothing	Fallback for `_cs_role`	`item` or `reward`	`reward`	Yes
`_cartsella_slot`, `cartsella_slot`	Nothing	Fallback for `_cs_slot`	Slot key	`slot-1`	Yes
`_cartsella_gift_for`	Nothing	Fallback for `_cs_gift_for`	Variant id	`43210987654321`	Yes
`_cartsella_gift_prefix`	Nothing	Fallback for `_cs_gift_prefix`	String	`🎁`	Yes
`_cartsella_product_collection_ids`	Nothing	Fallback for `_cs_cids`	JSON array of full `gid://shopify/Collection/N` strings	`["gid://shopify/Collection/287654321098"]`	Yes
`_cartsella_campaign_slug` / `_cartsella_campaign_link_id`, and the older `_ca_campaign` / `_ca_campaign_link_id`	Nothing	Fallbacks for the `_cs_campaign_*` pair	String	`spring-drop`	Yes
`_cartsella_experiment_id` / `_cartsella_experiment_variant`, `_cs_experiment_id` / `_cs_experiment_variant`	Nothing. A/B testing was removed from the product	Order attribution, for historical orders only	String	`control`	Yes, all four
`_cartsella_source`, `_cartsella_gift_worth`, `_cartsella_creator_page_id`, `_cartsella_creator_slug`	Nothing	Nothing meaningful	—	—	Yes, and dead. Do not build on them

The `_cs` value format

_cs collapses what used to be three separate properties into one value.

<entity id>:<entity type>:<entity subtype>

entity id is the offer, upsell or campaign link id.
entity type is offer, upsell or campaign_link.
entity subtype is the specific kind, for example gift_with_purchase, fixed_bundle, cart_drawer_cross_sell, campaign_link_checkout.

One line can belong to several entities at once, for example a cart drawer upsell product that also happens to trigger a gift with purchase. Those are joined with a pipe:

9f3c1a…:offer:gift_with_purchase|2b71e4…:upsell:cart_drawer_cross_sell

When _cs is missing, fall back to the parallel legacy lists _cartsella_id, _cartsella_type and _cartsella_subtype, which are comma-separated and paired by position. See parsing recipes for both.

`_cs_role`

_cs_role is the fastest test in the cart. reward means the line is free or discounted merchandise CartSella put there. item means it is a normal paid line that CartSella tagged.

A reward line never counts as a trigger for another offer and never counts toward a spend threshold. An item line can trigger as many offers as it matches.

Cart note attributes

Attribute	Written by	Read by	Format	Example	Legacy read-only
`_cs_attr`	Theme runtime, on every cart mutation it makes	Order attribution, which credits the order to the right offers and counts usage limits	JSON array of objects with short keys. Written as `"[]"` when there is nothing to attribute, never as an empty string	`[{"t":"offer","i":"9f3c…","st":"shipping_discount","s":"cart_reconcile"}]`	No
`_cs_removed_gifts`	Theme runtime, when a gift removal reaches Shopify	The gift sync engine and the checkout guard, so the gift is not immediately re-added. Cleared per offer once the trigger goes away or the gift is added back	Comma-separated offer ids	`9f3c…,2b71…`	No
`_cartsella_attributions`	Nothing	Fallback for `_cs_attr`, with the long key names below	JSON array	—	Yes
`_cartsella_order`, `cartsella_processed`	Nothing. Both only ever meant “CartSella touched this cart”, which `_cs_attr` already says by existing	Nothing. Cleared when found	—	—	Yes, and dead
`_cartsella_removed_gifts`	Nothing	Unioned with `_cs_removed_gifts`, not just checked after it, because it is a running set	Comma-separated offer ids	—	Yes

_cs_attr is written as the two-character string "[]" when there is nothing to attribute, never as "". Shopify deletes a note attribute whose value is an empty string, so an empty write would be undone and rewritten on every single cart mutation. If you ever mirror or rewrite cart attributes, preserve "[]" verbatim.

`_cs_attr` keys

The array holds one object per attributed entity. Keys are shortened to keep the merchant’s order “Additional details” panel readable.

Short	Long	Meaning
`t`	`entity_type`	`offer`, `upsell` or `campaign_link`
`i`	`entity_id`	The entity id
`st`	`entity_subtype`	The specific type, for example `gift_with_purchase`
`s`	`source`	Which surface wrote the entry
`cli`	`campaign_link_id`	Present only when a campaign link was involved
`csl`	`campaign_slug`	Same
`ei`	`experiment_id`	Historical orders only
`ev`	`experiment_variant`	Historical orders only
`lf`	`legacy_fallback`	`true` when the entity type had to be inferred

Both spellings are read forever, so a parser should accept t or entity_type, i or entity_id, and so on.

Reading everything off one line

const cart = await fetch("/cart.js", { credentials: "same-origin" })
  .then((r) => r.json());

/** Splits a CartSella `_cs` value, falling back to the legacy triple. */
function csEntities(properties = {}) {
  const raw = String(properties._cs || "").trim();
  if (raw) {
    return raw
      .split("|")
      .map((entry) => entry.split(":"))
      .filter(([id]) => id)
      .map(([id, type, subtype]) => ({
        id,
        type: type || "offer",
        subtype: subtype || type || "offer",
      }));
  }
  const csv = (v) =>
    String(v || "")
      .split(",")
      .map((s) => s.trim())
      .filter(Boolean);
  const ids = csv(properties._cartsella_id);
  const types = csv(properties._cartsella_type);
  const subtypes = csv(properties._cartsella_subtype);
  return ids.map((id, i) => ({
    id,
    type: types[i] || "offer",
    subtype: subtypes[i] || types[i] || "offer",
  }));
}

/** Comma-separated role list, accepting the legacy name. */
function csRoles(properties = {}) {
  return String(properties._cs_role ?? properties._cartsella_role ?? "")
    .split(",")
    .map((s) => s.trim())
    .filter(Boolean);
}

for (const line of cart.items) {
  console.log(line.key, csRoles(line.properties), csEntities(line.properties));
}

{%- assign cs_role = item.properties['_cs_role'] | default: item.properties['_cartsella_role'] -%}
{%- assign cs_raw = item.properties['_cs'] | default: item.properties['_cartsella_id'] -%}

{%- comment -%} First entity only. Split the pipe for the full list. {%- endcomment -%}
{%- assign cs_first = cs_raw | split: '|' | first | split: ':' -%}
{%- assign cs_id = cs_first[0] -%}
{%- assign cs_type = cs_first[1] | default: 'offer' -%}
{%- assign cs_subtype = cs_first[2] | default: cs_first[1] -%}

{%- if cs_role contains 'reward' -%}
  <span class="my-gift-badge">Gift</span>
{%- endif -%}

In Liquid, use bracket access (item.properties['_cs']) rather than dot access for names that start with an underscore. Bracket access is unambiguous across Liquid implementations and reads better next to the legacy fallbacks.

Gift with purchase walks through the one case most themes need: telling a gift line from a trigger line, and rendering it differently.

Get started

Offers

Upsells

Campaigns

Storefront

Measure & manage

Help

For developers

Cart line properties

Line item properties

The `_cs` value format

`_cs_role`

Cart note attributes

`_cs_attr` keys

Reading everything off one line

Next

​Line item properties

​The _cs value format

​_cs_role

​Cart note attributes

​_cs_attr keys

​Reading everything off one line

​Next

Line item properties

The `_cs` value format

`_cs_role`

Cart note attributes

`_cs_attr` keys

Reading everything off one line

Next