Shipping Protection

Shipping protection offer methods.

Extend.shippingProtection.render()

Render shipping protection offers.

Signature

Extend.shippingProtection.render(options)

Parameters

Property	Type	Required	Description
`selector`	`string`	Yes	The CSS selector for the container element
`items`	`object[]` (ShippingOffersItem)	Yes	An array of items currently in the cart
`isShippingProtectionInCart`	`boolean`	Yes	Indicates if shipping protection is already in the cart, to set the initial checkbox state
`onEnable`	`function`	Yes	Callback when the user opts into shipping protection. Receives a `quote` object
`onDisable`	`function`	Yes	Callback when the user opts out of shipping protection
`onUpdate`	`function`	Yes	Callback when the shipping protection offer changes (e.g., due to quantity/price/shippable changes)
`offerType`	`string`	No	Determines UI behavior. Values: `"OPT_IN"`, `"OPT_OUT"`, `"OPT_MERCHANT"`, `"SAFE_PACKAGE"`
`convertQuoteToFormattedDisplayPrice`	`function`	No	An async function to convert the quote premium into a localized, formatted string for display
`cartId`	`string`	No	A unique identifier for the cart session. Required for merchants performing A/B testing

Offer Type Examples:

Extend Choice (Opt In) - The Shipping Protection offer is unchecked and is not added to the cart by default. The customer must elect to check the checkbox in order to include Extend Shipping Protection in their purchase.

Opt-In Shipping Protection

Extend Choice (Opt Out) - The Shipping Protection offer is checked and added to the cart by default. The customer must elect to uncheck the checkbox in order to exclude it from their purchase.

Opt-Out Shipping Protection

Extend Complete (Opt Merchant or Safe Package) - The Shipping Protection offer is added to the cart by default. The customer will not be able to exclude it from their purchase.

Merchant Shipping Protection

Callback Functions

All callbacks receive a ShippingOffersQuote object:

function onEnable(quote) {
  // quote: ShippingOffersQuote
  console.log('Shipping protection enabled:', quote.id)
  console.log('Protection cost:', quote.premium)
}

function onDisable(quote) {
  console.log('Shipping protection disabled')
}

function onUpdate(quote) {
  console.log('Shipping protection updated:', quote.id)
}

Example

Extend.shippingProtection.render({
  selector: '#shipping-protection-offer',
  items: [
    {
      referenceId: 'PRODUCT_SKU_123',
      quantity: 1,
      purchasePrice: 29999,
      productName: 'Wireless Headphones',
      category: 'Electronics',
      shippable: true
    }
  ],
  isShippingProtectionInCart: false,
  onEnable: function(quote) {
    // Add shipping protection to cart
    addShippingProtectionToCart(quote)
    updateCartTotals()
  },
  onDisable: function(quote) {
    // Remove shipping protection from cart
    removeShippingProtectionFromCart()
    updateCartTotals()
  },
  onUpdate: function(quote) {
    // Update shipping protection in cart
    updateShippingProtectionInCart(quote)
    updateCartTotals()
  }
})

Extend.shippingProtection.update()

Update existing shipping protection offer. Call this method when cart items change (quantities, additions, removals) to fetch a new quote and update the displayed offer.

Signature

Extend.shippingProtection.update(options)

Parameters

Property	Type	Required	Description
`items`	`object[]` (ShippingOffersItem)	Yes	Updated array of items in the cart
`offerType`	`string`	No	Updated offer type behavior
`isShippingProtectionInCart`	`boolean`	No	Updated shipping protection cart state
`cartId`	`string`	No	Updated cart session identifier

Example

// When cart items change
function onCartUpdate(newItems) {
  Extend.shippingProtection.update({
    selector: '#shipping-protection-offer',
    items: newItems,
    isShippingProtectionInCart: hasShippingProtection(),
    onEnable: handleShippingProtectionEnable,
    onDisable: handleShippingProtectionDisable,
    onUpdate: handleShippingProtectionUpdate
  })
}

Extend.shippingProtection.destroy()

Remove a shipping protection component.

Signature

Extend.shippingProtection.destroy()

Example

// Clean up when leaving cart page
Extend.shippingProtection.destroy('#shipping-protection-offer')

Extend.shippingProtection.getUpdatedSPQuote()

Get an updated shipping protection quote for new cart items.

Signature

Extend.shippingProtection.getUpdatedSPQuote(options)

Parameters

Property	Type	Required	Description
`items`	`object[]` (ShippingOffersItem)	Yes	Cart items to get quote for
`onUpdate`	`function`	Yes	Callback with updated quote data
`merchantOfferType`	`string` (ShippingAttachBehavior)	No	Merchant offer type override

Example

Extend.shippingProtection.getUpdatedSPQuote({
  items: newCartItems,
  onUpdate: function(data) {
    if (data) {
      console.log('Updated quote:', data.quote)
      console.log('Attach behavior:', data.attachBehavior)
    } else {
      console.log('Failed to get updated quote')
    }
  }
})

Extend.shippingProtection.modal.open()

Display shipping protection information in a modal overlay.

Signature

Extend.shippingProtection.modal.open(offerType?)

Parameters

Property	Type	Required	Description
`offerType`	`string` (ShippingAttachBehavior)	No	Specific offer type to display

Example

// Open modal with default offer type
Extend.shippingProtection.modal.open()

// Open modal with specific offer type
Extend.shippingProtection.modal.open('OPT_IN')

Extend.shippingProtection.modal.close()

Close the shipping protection modal.

Signature

Extend.shippingProtection.modal.close()

Example

// Close the modal
Extend.shippingProtection.modal.close()

Extend.shippingProtection.modal.isOpen()

Check if the shipping protection modal is currently open.

Signature

Extend.shippingProtection.modal.isOpen()

Returns

Type	Description
`boolean`	`true` if modal is open, `false` otherwise

Example

// Check modal state
if (Extend.shippingProtection.modal.isOpen()) {
  console.log('Modal is currently open')
} else {
  console.log('Modal is closed')
}

Additional Methods

Method	Description
`destroy()`	Removes the shipping protection component from the DOM
`getShippingQuote()`	Returns the current `ShippingOffersQuote` from API call cache
`getCachedShippingQuoteItems()`	Returns the cached `Array<ShippingOffersItem>` associated with quote request
`setSPUserConfig({ isUserOptOut })`	Sets the user’s opt-out preference in session storage
`getSPUserConfig()`	Retrieves the user’s opt-out preference from session storage
`setSPUserLoyaltyStatus({ loyaltyStatus })`	Sets the user’s loyalty status for quote calculation. Loyalty status will be passed in while retrieving shipping-offer quote
`getSPUserLoyaltyStatus()`	Retrieves the user’s loyalty status from session storage

User Configuration Methods

// Set user opt-out preference
Extend.shippingProtection.setSPUserConfig({
  isUserOptOut: boolean
})

// Get user opt-out preference
const config = Extend.shippingProtection.getSPUserConfig()
// Returns: ShippingProtectionUserConfig | null

Loyalty Status Methods

// Set user loyalty status
Extend.shippingProtection.setSPUserLoyaltyStatus({
  loyaltyStatus: 'premium' // or other loyalty tier
})

// Get user loyalty status
const loyaltyStatus = Extend.shippingProtection.getSPUserLoyaltyStatus()
// Returns: ShippingProtectionUserLoyaltyStatus | null

Integration Patterns

Cart Page Integration

// Initialize shipping protection on cart page
function initializeShippingProtection() {
  const cartItems = getCartItems().map(item => ({
    referenceId: item.sku,
    quantity: item.quantity,
    purchasePrice: item.price,
    productName: item.name,
    category: item.category,
    shippable: item.shippable !== false
  }))

  Extend.shippingProtection.render({
    selector: '#shipping-protection',
    items: cartItems,
    isShippingProtectionInCart: cart.hasShippingProtection(),
    onEnable: addShippingProtection,
    onDisable: removeShippingProtection,
    onUpdate: updateShippingProtection
  })
}

function addShippingProtection(quote) {
  cart.addShippingProtection(quote)
  updateCartDisplay()
  
  // Track analytics
  Extend.trackSPOfferAddedToCart({
    quote: quote,
    products: getCartItems()
  })
}

Dynamic Cart Updates

// Update shipping protection when cart changes
function onCartItemAdded(newItem) {
  const updatedItems = getCartItems()
  
  Extend.shippingProtection.update({
    selector: '#shipping-protection',
    items: updatedItems,
    isShippingProtectionInCart: cart.hasShippingProtection(),
    onEnable: addShippingProtection,
    onDisable: removeShippingProtection,
    onUpdate: updateShippingProtection
  })
}

function onCartItemRemoved(removedItem) {
  const updatedItems = getCartItems()
  
  if (updatedItems.length === 0) {
    // No items left, destroy shipping protection
    Extend.shippingProtection.destroy('#shipping-protection')
  } else {
    // Update with remaining items
    Extend.shippingProtection.update({
      selector: '#shipping-protection',
      items: updatedItems,
      isShippingProtectionInCart: cart.hasShippingProtection(),
      onEnable: addShippingProtection,
      onDisable: removeShippingProtection,
      onUpdate: updateShippingProtection
    })
  }
}

Type Definitions

ShippingAttachBehavior

type ShippingAttachBehavior = 'OPT_IN' | 'OPT_OUT' | 'OPT_MERCHANT' | 'SAFE_PACKAGE'

ShippingOffersItem

interface ShippingOffersItem {
  referenceId: string
  quantity: number
  purchasePrice: number // Price in cents
  productName: string
  category?: string
  shippable?: boolean
}

ShippingOffersQuote

interface ShippingOffersQuote {
  id: string
  premium: number // Premium in cents
  currency: string
  excludedProducts?: string[]
}