Cart Management

The Shopify Addon provides enhanced cart management functionality specifically designed for Shopify’s cart system.

normalizeCart

Ensures warranty and shipping protection items in the cart match the quantities of their associated products. This function should be executed every time the cart is updated to ensure customers cannot purchase warranties for products not in their cart.

Syntax

ExtendShopify.normalizeCart(callback)
ExtendShopify.normalizeCart(options, callback)

Parameters

Parameter	Type	Required	Default	Description
`options`	NormalizeCartOptions	No	`{}`	Optional configuration
`callback`	`function`	Yes	-	Callback function

Callback Parameters

Parameter	Type	Required	Default	Description
`error`	`Error \| null`	Yes	-	Error if operation failed
`result`	NormalizeCartResult	No	-	Normalization results

Examples

// Basic usage
ExtendShopify.normalizeCart((error) => {
  if (error) {
    console.error('Cart normalization failed:', error)
  } else {
    console.log('Cart normalized successfully')
  }
})

// With options
ExtendShopify.normalizeCart({ balance: true }, (error, result) => {
  if (!error) {
    console.log('Cart normalized and balanced')
  }
})

updateExtendLineItems

Updates warranty and shipping protection items in the cart to maintain proper synchronization.

Syntax

ExtendShopify.updateExtendLineItems(options)

Parameters

Parameter	Type	Required	Default	Description
`options`	UpdateExtendLineItemsOptions	Yes	-	Configuration object

Callback Parameters

Parameter	Type	Required	Default	Description
`error`	`Error \| null`	Yes	-	Error if operation failed
`result`	UpdateExtendLineItemsResult	No	-	Update results

Examples

// Update extend line items
ExtendShopify.updateExtendLineItems({
  balanceCart: true,
  callback: (error, result) => {
    if (error) {
      console.error('Update failed:', error)
    } else {
      console.log('Line items updated successfully')
      console.log('Updated cart:', result.cart)
    }
  }
})

Type Definitions

UpdateExtendLineItemsOptions

Configuration options for the updateExtendLineItems function.

Property	Type	Required	Default	Description
`balanceCart`	`boolean`	No	`false`	Whether to force Extend Product Protection quantities to match the covered product quantities
`callback`	`function`	Yes	-	Callback function executed after operation completes

NormalizeCartOptions

Configuration options for the normalizeCart function.

Property	Type	Required	Default	Description
`balance`	`boolean`	No	`false`	Whether to force warranty quantities to match product quantities
`cart`	Cart	No	-	Initial cart data to use instead of fetching. Useful when cart state is managed locally
`update`	`boolean \\| function`	No	`true`	Whether to update the cart automatically. Can be `true`, `false`, or a custom update function

NormalizeCartResult

Result object returned by normalizeCart callback.

Property	Type	Required	Description
`updates`	`CartUpdates`	No	Cart updates that were applied
`cart`	`Cart`	Yes	Updated cart data

UpdateExtendLineItemsResult

Result object returned by updateExtendLineItems callback.

Property	Type	Required	Description
`additions`	CartSPAddition	No	Items that were added to cart
`updates`	CartUpdates	No	Cart updates that were applied
`cart`	Cart	Yes	Updated cart data

Cart

The main cart object containing all cart information.

Property	Type	Required	Description
`token`	`string`	Yes	Unique cart identifier
`note`	`string`	Yes	Cart note
`attributes`	`object`	Yes	Cart-level attributes
`total_price`	`number`	Yes	Total cart price in cents
`total_weight`	`number`	Yes	Total cart weight
`item_count`	`number`	Yes	Total number of items
`requires_shipping`	`boolean`	Yes	Whether cart requires shipping
`currency`	`string`	Yes	Cart currency code
`items`	CartLineItem[]	Yes	Array of cart line items

CartLineItem

Individual line item in the cart.

Property	Type	Required	Description
`id`	`number`	Yes	Line item ID
`title`	`string`	Yes	Product title
`price`	`number`	Yes	Item price in cents
`quantity`	`number`	Yes	Item quantity
`sku`	`string`	No	Product SKU
`vendor`	`string`	Yes	Product vendor
`properties`	CartLineItemProperties	No	Line item properties
`variant_id`	`number`	Yes	Product variant ID
`key`	`string`	Yes	Unique line item key

CartLineItemProperties

Properties attached to cart line items for Extend functionality.

Property	Type	Required	Description
`Ref`	`number`	No	Deprecated (v1 only) - Extend reference ID
`Product`	`string`	No	Extend product identifier
`Term`	`string`	No	Warranty term
`Extend.LeadToken`	`string`	No	Lead token for tracking
`Extend.LeadQuantity`	`number`	No	Lead quantity
`__Extend.IsExtendWarranty`	`boolean`	No	Whether item is a warranty
`_Extend.ProductId`	`string`	No	Product ID
`_Extend.IsPricePoint`	`boolean`	No	Whether using price points
`_Extend.PlanId`	`string`	No	Plan ID
`__Extend.OfferPlanId`	`string`	No	Offer plan ID
`__Extend.IsEmbedded`	`boolean`	No	Whether embedded
`__Extend.IsShippingProtection`	`boolean`	No	Whether shipping protection
`__Extend.ShippingQuoteId`	`string`	No	Shipping quote ID
`__Extend.CharityId`	`string`	No	Deprecated - Charity ID
`__Extend.DonationAmount`	`string`	No	Deprecated - Donation amount
`_Extend.BundleId`	`string`	No	Bundle ID
`__Extend.IsBundle`	`boolean`	No	Whether item is a bundle

CartUpdates

Object mapping cart item keys to new quantities for updates.

Property	Type	Required	Description
`[itemKey]`	`number`	Yes	New quantity for the item (0 to remove)

CartSPAddition

Shipping protection addition details.

Property	Type	Required	Description
`variantId`	`number`	Yes	Variant ID to add
`quoteId`	`string`	Yes	Shipping protection quote ID
`donationAmount`	`number`	No	Donation amount
`charityId`	`string`	No	Charity ID