Shipping Protection

addSpPlanToCart

Adds a shipping protection plan to the Shopify cart.

Syntax

ExtendShopify.addSpPlanToCart(options)

Parameters

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

Callback Parameters

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

Examples

// Add shipping protection to cart
const quote = {
  id: 'quote-123',
  premium: 299, // Price in cents
  currency: 'USD'
}

ExtendShopify.addSpPlanToCart({
  quote: quote,
  callback: (error, result) => {
    if (error) {
      console.error('Failed to add shipping protection:', error)
    } else {
      console.log('Shipping protection added:', result.isAdded)
    }
  }
})

shippingProtectionInCart

Checks if shipping protection is already present in the cart.

Syntax

const spData = ExtendShopify.shippingProtectionInCart(cartItems)

Parameters

Parameter	Type	Required	Default	Description
`cartItems`	CartLineItem[]	Yes	-	Array of cart items to check

Returns

Type	Description
`boolean`	`true` if shipping protection exists in cart, `false` otherwise

Examples

// Check for shipping protection in cart
fetch('/cart.js')
  .then(response => response.json())
  .then(cart => {
    const hasShippingProtection = ExtendShopify.shippingProtectionInCart(cart.items)
    
    if (hasShippingProtection) {
      console.log('Shipping protection found in cart')
    } else {
      console.log('No shipping protection in cart')
    }
  })

updateSpPlanInCart

Updates an existing shipping protection plan in the cart.

Syntax

ExtendShopify.updateSpPlanInCart(options)

Parameters

Parameter	Type	Required	Default	Description
`options`	UpdateSpPlanOptions	Yes	-	Update configuration

Callback Parameters

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

Examples

// Update shipping protection
const updatedQuote = {
  id: 'quote-123',
  premium: 598, // Updated price in cents
  currency: 'USD'
}

ExtendShopify.updateSpPlanInCart({
  quote: updatedQuote,
  callback: (error, result) => {
    if (error) {
      console.error('Update failed:', error)
    } else {
      console.log('Shipping protection updated:', result)
    }
  }
})

spCartMapper

Maps cart items to shipping protection format for quote generation.

Syntax

const mappedItems = ExtendShopify.spCartMapper(cartItems)

Parameters

Parameter	Type	Required	Default	Description
`cartItems`	CartLineItem[]	Yes	-	Shopify cart items

Returns

Type	Description
CartLineItemSP[]	Mapped items for shipping protection (see Cart Management)

Examples

// Map cart items for shipping protection
fetch('/cart.js')
  .then(response => response.json())
  .then(cart => {
    const mappedItems = ExtendShopify.spCartMapper(cart.items)
    
    console.log('Mapped items:', mappedItems)
    
    // Use mapped items to get shipping protection quote
    Extend.shippingProtection.getQuote({
      items: mappedItems
    })
  })

createCartChangeDetector

Creates an automatic cart change detection system for monitoring shipping protection cart changes.

Syntax

const detector = ExtendShopify.createCartChangeDetector(detectCartChange)

Parameters

Parameter	Type	Required	Default	Description
`detectCartChange`	`boolean`	Yes	-	Whether to enable cart change detection

Returns

Type	Description
CartChangeDetector	Cart change detector instance

Examples

// Create cart change detector for shipping protection
const detector = ExtendShopify.createCartChangeDetector(true)

// Subscribe to shipping protection cart changes
detector.subscribeToCartChanges({
  callback: (items, error) => {
    if (error) {
      console.error('Cart change detection error:', error)
      return
    }
    
    console.log('Shipping protection cart items changed:', items)
    
    // Handle shipping protection specific cart changes
    items.forEach(item => {
      console.log(`Item: ${item.title} - Quantity: ${item.quantity}`)
      if (item.isShippingProtection) {
        console.log('Shipping protection item detected')
      }
    })
    
    // Auto-update shipping protection quotes when cart changes
    if (items.length > 0) {
      Extend.shippingProtection.getQuote({
        items: ExtendShopify.spCartMapper(items)
      }).then(quote => {
        console.log('Updated shipping protection quote:', quote)
      })
    }
  }
})

// Disabled detector (won't monitor changes)
const disabledDetector = ExtendShopify.createCartChangeDetector(false)

convertQuoteToFormattedDisplayPrice

Converts a shipping protection quote price to a formatted display string.

Syntax

const formattedPrice = await ExtendShopify.convertQuoteToFormattedDisplayPrice(quote)

Parameters

Parameter	Type	Required	Default	Description
`quote`	ShippingOffersQuote	Yes	-	The shipping protection quote

Returns

Type	Description
`Promise<string>`	Promise resolving to formatted price string

Examples

// Format shipping protection price when store currency matches quote currency (USD)
const quote = {
  premium: 299, // Price in cents (USD)
  currency: 'USD'
}

try {
  const formattedPrice = await ExtendShopify.convertQuoteToFormattedDisplayPrice(quote)
  console.log('Formatted price:', formattedPrice) // "$2.99"
  
  // Display in UI
  document.getElementById('sp-price').textContent = formattedPrice
} catch (error) {
  console.error('Failed to format price:', error)
}

// Format shipping protection price with currency conversion
// Note: Quote is always in USD, but will be converted to store's presentment currency
const usdQuote = {
  premium: 299, // Price in USD cents
  currency: 'USD'
}

// If store's presentment currency is EUR (window.Shopify.currency.active = 'EUR')
try {
  const formattedPrice = await ExtendShopify.convertQuoteToFormattedDisplayPrice(usdQuote)
  console.log('Converted to EUR:', formattedPrice) // "€2,50" (example - actual format depends on browser locale)
  
  // Display in UI
  document.getElementById('sp-price-eur').textContent = formattedPrice
} catch (error) {
  console.error('Failed to format EUR price:', error)
}

// If store's presentment currency is GBP (window.Shopify.currency.active = 'GBP')
try {
  const formattedPrice = await ExtendShopify.convertQuoteToFormattedDisplayPrice(usdQuote)
  console.log('Converted to GBP:', formattedPrice) // "£1.99" (example - actual format depends on browser locale)
} catch (error) {
  console.error('Failed to format GBP price:', error)
}

// Currency conversion is handled automatically based on Shopify's presentment currency
// The function fetches the converted price from Shopify to ensure accuracy

Type Definitions

AddSpPlanOptions

Configuration options for the addSpPlanToCart function.

Property	Type	Required	Default	Description
`quote`	ShippingOffersQuote	Yes	-	The shipping protection quote to add
`cart`	Cart	No	-	Initial cart data (uses current cart if not provided)
`callback`	`function`	Yes	-	Callback function executed after operation

UpdateSpPlanOptions

Configuration options for the updateSpPlanInCart function.

Property	Type	Required	Default	Description
`action`	`'update' \\| 'remove'`	Yes	-	Action to perform on the shipping protection plan
`quote`	ShippingOffersQuote	No	-	Updated shipping protection quote (required for ‘update’ action)
`cart`	Cart	No	-	Initial cart data (uses current cart if not provided)
`callback`	`function`	Yes	-	Callback function executed after operation

ShippingOffersQuote

Shipping protection quote object from the Extend SDK.

Property	Type	Required	Description
`id`	`string`	Yes	Unique quote identifier
`premium`	`number`	Yes	Quote price in cents
`currency`	`string`	Yes	Currency code (e.g., ‘USD’)
`excludedProducts`	`string[]`	No	Array of excluded product IDs
`charityDonations`	`CharityDonations`	No	Charity donation information
`offerType`	`ShippingAttachBehavior`	Yes	Shipping protection behavior type

CharityDonations

Charity donation information for shipping protection.

Property	Type	Required	Description
`amount`	`number`	Yes	Total donation amount in cents
`charities`	Charity[]	Yes	Array of selected charities

Charity

Individual charity information.

Property	Type	Required	Description
`charityId`	`string`	Yes	Unique charity identifier
`charityName`	`string`	Yes	Display name of the charity

CartAdditions

Result object for shipping protection additions.

Property	Type	Required	Description
`isAdded`	`boolean`	Yes	Whether the shipping protection was successfully added

Note: For CartUpdates and other shared cart types, see the Cart Management API Reference.

CartChangeDetector

Cart change detection system for monitoring shipping protection changes.

Method	Description
`subscribeToCartChanges(options)`	Subscribe to cart changes with callback function

SubscribeToCartChangesOptions

Configuration options for the subscribeToCartChanges method.

Property	Type	Required	Default	Description
`callback`	`function`	Yes	-	Callback function called when cart changes. Receives `(items, error)` parameters