Cart

Description

The cart variable provides access to the current customer’s shopping cart data within the Superfans SDK.
It allows you to read line items, quantities, prices, discounts, and totals directly from Shopify’s cart.
This variable is available globally whenever a user has an active cart session. If no items have been added, cart will be empty or null.

Properties of cart

Properties of appliedDiscounts

Properties of cartLevelDiscounts

Properties of cart items

Properties of lineLevelDiscounts

Sample cart object

{"cartId":"gid://shopify/Cart/cart_id","appliedDiscounts":[{"code":"SAVE10","title":null,"targetType":"LINE_ITEM"},{"code":"BXGY","title":null,"targetType":"LINE_ITEM"}],"cartLevelDiscounts":[{"code":"SAVE10","amount":2.00,"targetType":"CART_LEVEL"}],"subtotal":20.99,"currency":"USD","items":[{"variantId":"12345","productId":"123456789","quantity":1,"lineItemId":"gid://shopify/CartLine/line_item_id","title":"Product title","price":"10.0","currency":"USD","compareAtAmountPerQuantity":null,"image":"https://cdn.shopify.com/image.jpg","amountPerQuantity":"10.0","variantName":"Small","sellingPlanId":"gid://shopify/SellingPlan/selling_plan_id","lineLevelDiscounts":[{"code":"BXGY","amount":10}],"attributes":[{"key":"custom_key","value":"custom_value"}]}]}}

Example Usage

const cart = Superfans.variables.cart;

if (cart && cart.items?.length > 0) {
  const firstItem = cart.items[0];
  const appliedCodes = (cart.appliedDiscounts || []).map((discount) => discount.code);
  const cartDiscountTotal = (cart.cartLevelDiscounts || []).reduce((sum, discount) => {
    return sum + (discount.amount || 0);
  }, 0);
  const lineDiscountTotal = (firstItem.lineLevelDiscounts || []).reduce((sum, discount) => {
    return sum + (discount.amount || 0);
  }, 0);

  console.log(`Cart ID: ${cart.cartId}`);
  console.log(`Items: ${cart.items.length}`);
  console.log(`First item: ${firstItem.title} - ${firstItem.variantName}`);
  console.log(`Subtotal: ${cart.subtotal} ${cart.currency}`);
  console.log(`Applied codes: ${appliedCodes.join(", ")}`);
  console.log(`Cart-level discount: ${cartDiscountTotal}`);
  console.log(`First item line-level discount: ${lineDiscountTotal}`);
  if (firstItem.sellingPlanId) {
    console.log(`Selling plan GID: ${firstItem.sellingPlanId}`);
  }
} else {
  console.log("Your cart is empty.");
}

Best Practices

1. Check for null or empty carts: Always verify that cart exists and has items before accessing its properties.
2. Re-read live cart data: Inside Superfans.listeners.onCartUpdated, read Superfans.variables.cart again instead of using a cached cart object.
3. Use the new discount objects: Read code and targetType from appliedDiscounts. Use cartLevelDiscounts and lineLevelDiscounts for amounts. Do not treat appliedDiscounts as an array of strings.
4. Avoid direct modification: Cart data is read-only via this variable. Use cart actions such as addToCart and removeFromCart to change contents.

Caveats

1. Discount shape: appliedDiscounts is an array of objects (code, title, targetType), not an array of strings.
2. Split allocations: A code can appear in appliedDiscounts as LINE_ITEM and also in cartLevelDiscounts as CART_LEVEL. Line-item amounts live in items[].lineLevelDiscounts.
3. Zero amounts: lineLevelDiscounts.amount can be 0 on some line items even when the code is present.
4. Nullable fields: compareAtAmountPerQuantity and appliedDiscounts.title can be null. variantName can be an empty string.
5. Price rounding: Shopify handles rounding and currency precision; do not manually round floats.
6. Subscriptions: If using Shopify selling plans, sellingPlanId is present only on subscription line items and is a GID (gid://shopify/SellingPlan/...).