Product Protection API

Complete API reference for warranty and protection plan methods.

Extend.buttons.render()

Display inline warranty offers on product pages.

Signature

Extend.buttons.render(selector, options)

Parameters

Parameter	Type	Required	Description
`selector`	`string \| HTMLElement`	Yes	CSS selector or DOM element
`options`	`object` (RenderOptions)	Yes	Render configuration

RenderOptions

Property	Type	Required	Description
`referenceId`	`string`	Yes*	This is the unique product identifier that you had specified in your product catalog upload. We will use this identifier to know which warranty offer to display. Generally this is the product SKU or similar, however the choice of product reference ID is up to a merchant to decide. If you are having trouble finding out what your product referenceId is, please file a support request through the Extend Merchant Portal.
`price`	`number`	No	Product price in cents
`category`	`string`	No	Product category (recommended for better offer matching)
`storeId`	`string`	No	Store ID (uses global config if not provided)
`products`	`object[]` (ProductInput)	No	Array of components for bundles (e.g., Shopify Bundles app). The `referenceId` in this case should be the parent bundle ID.
`theme`	`object` (Theme)	No	Theme configuration
`preview`	`boolean`	No	Enable preview mode - renders hard-coded mock offers for testing purposes instead of fetching real offers

*Required unless products array is provided or preview: true

Example

Extend.buttons.render('#extend-offer', {
  referenceId: 'headphones-001',
  price: 29999,
  category: 'Electronics'
})

Multiple Products (Variants)

Extend.buttons.render('#extend-offer', {
  products: [
    { referenceId: 'headphones-black', quantity: 1, price: 29999, category: 'Electronics' },
    { referenceId: 'headphones-white', quantity: 1, price: 31999, category: 'Electronics' },
    { referenceId: 'headphones-red', quantity: 1, price: 32999, category: 'Electronics' }
  ]
})

Bundle Products (Shopify Bundles)

For product bundles created with Shopify’s official Bundles app, use the products array to specify individual bundle components while referenceId represents the parent bundle.

Extend.buttons.render('#extend-offer', {
  referenceId: 'camera-starter-bundle', // Parent bundle ID
  products: [
    { referenceId: 'camera-body-dslr', quantity: 1, price: 59999, category: 'Electronics' },
    { referenceId: 'lens-50mm-prime', quantity: 1, price: 29999, category: 'Electronics' },
    { referenceId: 'memory-card-64gb', quantity: 2, price: 1999, category: 'Electronics' },
    { referenceId: 'camera-bag', quantity: 1, price: 4999, category: 'Electronics' }
  ]
})

Extend.buttons.renderSimpleOffer()

Display warranty offers with immediate add-to-cart functionality (for cart pages).

Product Protection Simple Offer

Signature

Extend.buttons.renderSimpleOffer(selector, options)

Parameters

Parameter	Type	Required	Description
`selector`	`string \| HTMLElement`	Yes	CSS selector or DOM element
`options`	`object` (SimpleOfferOptions)	Yes	Render configuration

SimpleOfferOptions

Property	Type	Required	Description
`referenceId`	`string`	Yes	Product SKU/ID
`price`	`number`	Yes	Product price in cents
`category`	`string`	Yes	Product category (required for offer matching)
`storeId`	`string`	No	Store ID (uses global config if not provided)
`products`	`object[]` (ProductInput)	No	Array of components for bundles (e.g., Shopify Bundles app). The `referenceId` in this case should be the parent bundle ID.
`theme`	`object` (Theme)	No	Theme configuration
`preview`	`boolean`	No	Enable preview mode - renders hard-coded mock offers for testing purposes instead of fetching real offers
`onAddToCart`	`(options: AddToCartOpts) => void \| Promise<void>`	Yes	Called when plan is selected

Example

Extend.buttons.renderSimpleOffer('#cart-warranty', {
  referenceId: 'headphones-001',
  price: 29999,
  category: 'Electronics',
  onAddToCart: function(options) {
    const { plan, product, quantity, token } = options
    addWarrantyToCart(plan.planId, quantity || 1)
    updateCartTotals()
  }
})

Bundle Example

Extend.buttons.renderSimpleOffer('#cart-bundle-warranty', {
  referenceId: 'office-essentials-bundle', // Parent bundle ID
  products: [
    { referenceId: 'desk-lamp', quantity: 1, price: 4999, category: 'Electronics' },
    { referenceId: 'wireless-charger', quantity: 1, price: 2999, category: 'Electronics' },
    { referenceId: 'bluetooth-speaker', quantity: 1, price: 7999, category: 'Electronics' }
  ],
  onAddToCart: function(options) {
    const { plan, product, quantity, token, products } = options
    console.log('Bundle warranty added:', plan.title)
    console.log('Bundle components:', products)
    addWarrantyToCart(plan.planId, quantity || 1)
    updateCartTotals()
  }
})

Extend.buttons.instance()

Get a component instance for interaction.

Signature

Extend.buttons.instance(selector): ComponentInstance | null

Parameters

Parameter	Type	Required	Description
`selector`	`string \| HTMLElement`	Yes	CSS selector or DOM element

ComponentInstance Methods

Method	Return Type	Description
`getActiveProduct()`	`ProductDetails \| null`	Get currently active product
`setActiveProduct(referenceId)`	`void`	Change active product (for variants)
`getPlanSelection()`	`PlanSelection \| null`	Get user’s warranty selection
`getOfferToken()`	`string \| null`	Get the offer token for the current selection
`destroy()`	`void`	Remove the component from the DOM

Example

const component = Extend.buttons.instance('#extend-offer')

if (component) {
  // Get user's selection
  const selection = component.getPlanSelection()
  
  if (selection) {
    console.log('User selected:', selection.title)
    console.log('Plan ID:', selection.planId)
    console.log('Price:', selection.price)
    
    // Get offer token for cart/checkout
    const token = component.getOfferToken()
    console.log('Offer token:', token)
  }
  
  // Change active product (for variants)
  component.setActiveProduct('new-sku-123')
  
  // Clean up component when done
  // component.destroy()
}

Extend.setActiveProduct()

If your store has multiple product variants for a single product page (for example, if you have a product that allows a customer to select a color or size option) you’ll need to pass the new product reference id to the SDK when the change occurs. This prevents a customer from accidentally purchasing the wrong warranty for an incorrect product.

Signature

Extend.setActiveProduct(selector, referenceId)

Parameters

Parameter	Type	Required	Description
`selector`	`string \| HTMLElement`	Yes	CSS selector or DOM element
`referenceId`	`string`	Yes	Product SKU/ID to set as active

Example

// Set active product for variant switching
Extend.setActiveProduct('#extend-offer', 'headphones-black')

// Equivalent to using instance method
const component = Extend.buttons.instance('#extend-offer')
if (component) {
  component.setActiveProduct('headphones-black')
}

Extend.modal.open()

Display product protection offers in modal overlays.

Signature

Extend.modal.open(options)

Parameters

Parameter	Type	Required	Description
`options`	`object` (ModalOptions)	Yes	Modal configuration

ModalOptions

Property	Type	Required	Description
`referenceId`	`string`	Yes	Product SKU/ID
`price`	`number`	No	Product price in cents
`category`	`string`	No	Product category (recommended for better offer matching)
`storeId`	`string`	No	Store ID (uses global config if not provided)
`products`	`object[]` (ProductInput)	No	Array of components for bundles (e.g., Shopify Bundles app). The `referenceId` in this case should be the parent bundle ID.
`modalOrigin`	`string` (ModalOriginType)	No	Origin context for analytics
`theme`	`object` (Theme)	No	Theme configuration
`element`	`string \| HTMLElement` (ElementRef)	No	Container element for modal
`onClose`	`function` (OnModalClose)	No	Called when modal closes

Example

Extend.modal.open({
  referenceId: 'headphones-001',
  price: 29999,
  category: 'Electronics',
  modalOrigin: 'offer_modal',
  onClose: function(plan, product, quantity, token) {
    if (plan && product) {
      console.log('User selected warranty:', plan.title)
      console.log('Quantity:', quantity)
      console.log('Token:', token)
      addWarrantyToCart(plan.planId, quantity || 1)
    } else {
      console.log('User declined warranty')
    }
    // Continue to cart
    window.location.href = '/cart'
  }
})

Bundle Example

Extend.modal.open({
  referenceId: 'gaming-setup-bundle', // Parent bundle ID
  products: [
    { referenceId: 'gaming-laptop', quantity: 1, price: 149999, category: 'Electronics' },
    { referenceId: 'gaming-mouse', quantity: 1, price: 7999, category: 'Electronics' },
    { referenceId: 'mechanical-keyboard', quantity: 1, price: 12999, category: 'Electronics' }
  ],
  modalOrigin: 'offer_modal',
  onClose: function(plan, product, quantity, token, products) {
    if (plan && product && products) {
      console.log('Bundle warranty selected:', plan.title)
      console.log('Bundle components:', products)
      addWarrantyToCart(plan.planId, quantity || 1)
    }
    window.location.href = '/cart'
  }
})

Product Protection Modal

Extend.modal.close()

Close the modal programmatically.

Signature

Extend.modal.close()

Example

// Close modal after 30 seconds
setTimeout(() => {
  Extend.modal.close()
}, 30000)

Extend.learnMoreModal.open()

Display detailed information about product protection plans.

Signature

Extend.learnMoreModal.open(options)

Parameters

Parameter	Type	Required	Description
`options`	`object` (LearnMoreModalOptions)	Yes	Modal configuration

LearnMoreModalOptions

Property	Type	Required	Description
`referenceId`	`string`	Yes	Product SKU/ID
`storeId`	`string`	No	Store ID (uses global config if not provided)
`category`	`string`	No	Product category (recommended for better offer matching)
`price`	`number`	No	Product price in cents
`products`	`object[]` (ProductInput)	No	Array of components for bundles (e.g., Shopify Bundles app). The `referenceId` in this case should be the parent bundle ID.
`planUrl`	`string`	No	Specific plan URL to display
`element`	`string \| HTMLElement` (ElementRef)	No	Container element for modal
`isEmbedded`	`boolean`	No	Whether the selected plan is an embedded (pre-included) warranty plan

Example

Extend.learnMoreModal.open({
  referenceId: 'headphones-001',
  category: 'Electronics',
  price: 29999,
  planUrl: 'https://example.com/plan-details'
})

Extend.learnMoreModal.close()

Close the learn more modal programmatically.

Signature

Extend.learnMoreModal.close()

Extend.learnMoreModal.isOpen()

Check if the learn more modal is currently open.

Signature

Extend.learnMoreModal.isOpen()

Returns

Type: boolean
Description: True if modal is open, false otherwise

Extend.aftermarketModal.open()

Ability to purchase product protection for a previously purchased product.

Signature

Extend.aftermarketModal.open(options)

Parameters

Parameter	Type	Required	Description
`options`	`object` (AftermarketOptions)	Yes	Aftermarket modal configuration

AftermarketOptions

Property	Type	Required	Description
`leadToken`	`string`	Yes	Lead token
`storeId`	`string`	No	Store ID (uses global config if not provided)
`theme`	`object` (Theme)	No	Theme configuration
`element`	`string \| HTMLElement` (ElementRef)	No	Container element for modal
`onClose`	`function` (OnModalClose)	No	Called when modal closes

Example

// Lead token must be obtained from Extend
Extend.aftermarketModal.open({
  leadToken: 'lead_token',
  onClose: function(plan, product, quantity, token) {
    if (plan && product) {
      console.log('Post-purchase warranty selected:', plan.title)
      console.log('Quantity:', quantity)
      console.log('Token:', token)
      // Handle warranty purchase
    }
  }
})

Type Definitions

AddToCartOpts

interface AddToCartOpts {
  plan: PlanSelection      // Selected warranty plan
  product: ProductDetails  // Product details
  products?: ProductDetails[] // Bundle components (when using bundles)
  quantity?: number        // Warranty quantity
  token?: string          // Optional token
}

ModalOriginType

type ModalOriginType = 'simple_offer_modal' | 'offer_modal' | 'post_purchase_modal'

OnModalClose

type OnModalClose = (
  plan?: PlanSelection,
  product?: ProductDetails,
  quantity?: number,
  token?: string,
  products?: ProductDetails[],
) => void

PlanSelection

interface PlanSelection {
  planId: string         // Unique plan identifier
  price: number          // Warranty price in cents
  term: number           // Coverage term in months
  title: string          // Display title (e.g., "2 Year Protection")
  coverageType: 'adh' | 'base'  // Type of coverage
  token?: string         // Token for cart/checkout
  offerPlanId?: string   // Offer-specific plan ID
  isEmbedded?: boolean   // Whether plan is embedded
}

ProductDetails

interface ProductDetails {
  id: string             // Product SKU/ID
  referenceId: string    // Product SKU/ID
  name: string          // Product display name
  category?: string     // Product category
  price?: number        // Price in cents
  quantity?: number     // Quantity of item
}

ProductInput

interface ProductInput {
  referenceId?: string   // Product SKU/ID
  category?: string      // Product category
  price?: number         // Price in cents
  quantity?: number      // Product quantity
}

Theme

interface Theme {
  primaryColor: string        // Primary brand color
}