Overview

The Spot Widget (referred to as SpotWidget in code) allows you to embed Spot’s Refund Guarantee quoting experience directly in your checkout or product page. It supports single and multi-item carts, theming, callbacks, and works with any frontend environment (vanilla JS, React, Vue).

For visual reference - here's an example of our widget with basic styling options applied:

🚧
Version Notice: For the latest info and versions of the Spot Widget, visit the package page on npm.

Embed in One Script Tag

Embed with one script tag, no install required:

<div id="spot-widget"></div> <!-- Where the widget will appear -->
<script src="https://unpkg.com/@getspot/[email protected]/dist/index.umd.js"></script> // See NPM docs for latest widget version
<script>
  const widget = new SpotWidget({
    location: "#spot-widget",
    apiConfig: {
      environment: "sandbox",
      partnerId: "your-partner-id"
    },
    quoteRequestData: {
      startDate: "2025-05-01T12:00:00.000Z",
      endDate: "2025-05-05T12:00:00.000Z",
      currencyCode: "USD",
      eventType: "Skiing",
      productType: "Registration",
      productDuration: "Event",
      productPrice: 100,
      productId: "abc123",
      productName: "Test Product"
    }
  });
</script>

💡
💡 The widget automatically fetches a quote and renders the Refund Guarantee offer once retrieved.

Full Example:

This snippet includes theming and callbacks (described below) for complete visibility during testing:

<div id="spot-widget"></div>
<script src="https://unpkg.com/@getspot/[email protected]/dist/index.umd.js"></script> // See NPM docs for latest widget version
<script>
  const widget = new SpotWidget({
    location: "#spot-widget",
    apiConfig: {
      environment: "sandbox",
      partnerId: "your-partner-id"
    },
    quoteRequestData: {
      startDate: "2025-05-01T12:00:00.000Z",
      endDate: "2025-05-05T12:00:00.000Z",
      currencyCode: "USD",
      eventType: "Skiing",
      productType: "Registration",
      productDuration: "Event",
      productPrice: 100,
      productId: "abc123",
      productName: "Test Product"
    },
    theme: {
      "spot-background-color": "#f8f8f8",
      "spot-font-family": "Inter, sans-serif",
      "spot-title-font-color": "#004aad"
    },
    callbacks: {
      onQuoteRetrieved: (quote) => console.log("Quote retrieved:", quote),
      onOptIn: (data) => console.log("User opted in:", data),
      onOptOut: (data) => console.log("User opted out:", data),
      onError: (err) => console.error("Widget error:", err)
    }
  });
</script>

🚧
Always reference npm for the latest version.

Quote Request Data

quoteRequestData defines what the customer is purchasing and drives the widget’s display.

Provided by Spot during integration:

A sandbox partnerId
Pre-configured test offers
Guidance on what values to send for productType, productDuration, and productId

Single vs Multi-Item Carts:

quoteRequestData can be passed as either a single product or a cart with multiple items, depending on your checkout experience. The widget will automatically adjust its quote display and pricing behavior.

Single Item:

    quoteRequestData: {
      startDate: "2025-05-01T12:00:00.000Z",
      endDate: "2025-05-05T12:00:00.000Z",
      currencyCode: "USD",
      eventType: "Skiing",
      productType: "Registration",
      productDuration: "Event",
      productPrice: 100,
      productId: "abc123",
      productName: "Test Product"
    }

Multiple Items:

The widget automatically calculates combined coverage and total premium across all items.

    quoteRequestData: {
      cartInfo: {
        cartId: "cart123",
        cartName: "My Shopping Cart",
        currencyCode: "USD"
      },
      items: [
        {
          cartItemId: "item1",
          productPrice: 299,
          productType: "Pass",
          productDuration: "Daily",
          productId: "ski-pass-vail",
          productName: "Vail Ski Pass",
          participantDescription: "Adult",
          eventType: "Snow Sports",
          startDate: "2025-01-15T00:00:00Z",
          endDate: "2025-01-22T00:00:00Z"
        },
        {
          cartItemId: "item2",
          productPrice: 150,
          productType: "Trip",
          productDuration: "Trip",
          productId: "hotel-booking",
          productName: "Mountain Lodge",
          participantDescription: "2 Adults",
          eventType: "Accommodation",
          startDate: "2025-01-15T00:00:00Z",
          endDate: "2025-01-22T00:00:00Z"
        }
      ]
    }

Installation Options

CDN (UMD)

This format is useful for quick integration into any HTML page.

<script src="https://unpkg.com/@getspot/[email protected]/dist/index.umd.js"></script> // See NPM docs for latest widget version
<div id="spot-widget"></div>
<script>
  const spotWidget = new SpotWidget({
    location: "#spot-widget",
    apiConfig: {
      environment: "sandbox",
      partnerId: "your-partner-id",
    },
    quoteRequestData: {},
    // Other configuration options...
  });
</script>

ES Module Format (for modern JavaScript projects)

For modern JS projects that use bundlers like Webpack, Rollup, or Vite, use this format .

<script type="module">
  import SpotWidget from "https://unpkg.com/@getspot/[email protected]/dist/spot-widget.es.js";  // See NPM docs for latest widget version

  const spotWidget = new SpotWidget({
    location: "#spot-widget",
    apiConfig: {
      environment: "sandbox",
      partnerId: "your-partner-id",
    },
    quoteRequestData: {},
    // Other configuration options...
  });
</script>

If using one of the framework-specific packages, the script URLs will look like:

https://unpkg.com/@getspot/[email protected]/dist/index.umd.js

https://unpkg.com/@getspot/[email protected]/dist/spot-widget-vue2.umd.js

https://unpkg.com/@getspot/[email protected]/dist/spot-widget-vue.umd.js

NPM

To install the Spot Widget via npm, run:

npm install @getspot/spot-widget

If you want to install the widget for a specific framework, you can use one of the following:

npm install @getspot/spot-widget-react

npm install @getspot/spot-widget-vue2

npm install @getspot/spot-widget-vue

Framework Options

The Spot Widget is currently available in React, Vue 2, and Vue 3. Additional frameworks can be provided upon request. These framework-specific builds expose the same core Quoting API, wrapped for each framework’s component model.

import React, { useEffect } from 'react';
import SpotWidget from '@getspot/spot-widget-react';

function App() {
  return (
    <div className="App">
      <h1>Testing Spot Widget</h1>
      <SpotWidget
        apiConfig={{
          environment: "sandbox",
          partnerId: "your-partner-id",
        }}
        quoteRequestData={{
          eventType: "",
          // other request fields
        }}
        // other props
      />
    </div>
  );
}

export default App;

<template>
  <div>
    <SpotWidget 
      :apiConfig="{
        environment: 'sandbox',
        partnerId: 'your-partner-id'
      }"
      :quoteRequestData="{
        eventType: ''
        // other fields
      }"
      :callbacks="{}"
    />    
  </div>
</template>

<script>
import SpotWidget from "@getspot/spot-widget-vue2";

export default {
  name: "Vue2SpotWidget",
  components: {
    SpotWidget
  }
};
</script>

<template>
  <div>
    <SpotWidget 
      :apiConfig="{
        environment: 'sandbox',
        partnerId: 'your-partner-id'
      }"
      :quoteRequestData="{
        eventType: '',
        // other fields
      }"
      :callbacks="{}"
    />
  </div>
</template>

<script>
import SpotWidget from "@getspot/spot-widget-vue";

export default {
  name: "VueSpotWidget",
  components: {
    SpotWidget
  }
};
</script>

Configuration Options

Widget Options

Key	Type	Description	Default	Required
`location`	`string`	`HTMLElement`	CSS selector or DOM element where the widget should be mounted	`"body"`
`showTable`	`boolean`	Whether to show the payout schedule table	`true`	❌
`logoPosition`	`string`	Determines where the "Powered by Spot" logo is positioned. Accepted values are `bottom-right` or `top-right`	`bottom-right`	❌
`optInSelected`	`boolean`	If `true`, the "yes" option is selected by default	`false`	❌
`state`	`string`	Customer's 2-letter US state code (e.g., `"TX"`). Only applies to Pass/Trip offers — ignored for Registration. When provided, hides the state selector and passes the value through to downstream calls. When omitted on a Pass/Trip offer, a state selector is shown automatically above the yes/no radio buttons, and those buttons are disabled until the customer makes a selection.	—	❌
`apiConfig`	`object`	Configuration for the quote API. See apiConfig table below	—	✅
`quoteRequestData`	`object`	Data used to generate a quote. See quoteRequestData tables below.	—	✅
`callbacks`	`object`	Event handlers. See Callbacks table below	`{}`	❌
`theme`	`object`	CSS custom properties to override the default theme. See Theming table below	`{}`	❌

`apiConfig` Parameters

Key	Type	Description	Required
`environment`	`string`	The environment used to fetch quotes (one of `"sandbox"`,`"production"`)	✅
`partnerId`	`string`	Unique partner identifier	✅

Single Quote `quoteRequestData` Parameters

Key	Type	Description	Required
`startDate`	`string`	ISO8601 date-time indicating the date and time the product starts	✅
`endDate`	`string`	ISO8601 date-time indicating the date and time the product ends	✅
`currencyCode`	`string`	Currency code (e.g., `"USD"`)	✅
`eventType`	`string`	Type of event being sold (e.g., `"Skiing Activities"`, `"Kayaking/SUP"`)	✅
`productType`	`string`	The product type being sold (one of `"Pass"`, `"Trip",` `"Registration"`)	✅
`productDuration`	`string`	The product duration being sold (one of `"Daily"`, `"Seasonal",` `"Trip"`, `"Event"`)	✅
`productPrice`	`number`	Total price of the product (e.g., `200.00`)	✅
`productId`	`string`	Unique identifier for the product	✅
`productName`	`string`	Description or display name for the product	✅
`cartId`	`string`	Unique identifier for the cart session	✅
`isPartialPayment`	`boolean`	Indicates whether this quote is for a deposit-based booking. When the user opts in and `isPartialPayment` is `true`, additional payment terms regarding the deposit-based booking will also be displayed	❌

Batch Quote `quoteRequestData` Parameters

For multiple items in a single cart, use this structure:

Key	Type	Description	Required
cartInfo	object	Cart-level information. See `cartInfo` table below	✅
items	array	Array of items in the cart. See `items` table below	✅

`cartInfo` Parameters

Key	Type	Description	Required
cartId	string	Unique identifier for the cart session	✅
cartName	string	Display name for the cart	✅
currencyCode	string	Currency code (e.g., "USD", "CAD", "AUD", etc)	✅

`items` Parameters

Key	Type	Description	Required
cartItemId	string	Unique identifier for the item within the cart	✅
productPrice	number	Price of this specific item	✅
productType	string	One of "Pass", "Trip", "Registration"	✅
productDuration	string	One of "Daily", "Seasonal", "Trip", "Event"	✅
productId	string	Unique identifier for the product	✅
productName	string	Display name for the product	✅
participantDescription	string	Description of participants/product (e.g., "Adult", "GA")	✅
eventType	string	Type of event (e.g., "Skiing", "Full Marathon")	✅
startDate	string	ISO8601 date-time indicating when this item starts	✅
endDate	string	ISO8601 date-time indicating when this item ends	✅

Callbacks

Callback	Description	Callback Data
onQuoteRetrieved	Quote successfully retrieved	Full quote object (see Quote Object Fields table)
onOptIn	User opted in	`{ status: "QUOTE_ACCEPTED", quoteId: string, spotPrice: number, batchQuoteDetails?: array }`
onOptOut	User opted out	`{ status: "QUOTE_DECLINED", quoteId: string, batchQuoteDetails?: array }`
noMatchingQuote	No matching quote found	`{ status: "NO_MATCHING_QUOTE", data: quoteRequestData }`
onError	Widget errors during fetch or initialization	`{ message: string, status?: number, responseBody?: object }`

Example:

callbacks: {
  onOptIn: (data) => console.log("Opted in:", data),
  onError: (err) => console.error(err)
}

Notes:

onError will be triggered for any caught exceptions, such as network issues or malformed configuration.
- The widget will fail gracefully and not render any UI.
For batch quotes, quoteId will contain comma-separated quote IDs (e.g., "abc123,def456")
batchQuoteDetails is only present for batch quotes and contains: [{ quoteId: string, productPrice: number, cartItemId: string }, ...]
spotPrice represents the total combined premium for all items in batch quotes
The widget automatically displays a "Covered Items" section listing all products for batch quotes

SelectionData Fields

Field	Type	Description
`state`	`string \| undefined`	Customer's US state code (e.g., `"TX"`). Only set for Pass/Trip offers. Populated when the partner supplies a state prop, or when the user selects a state from the selector shown on Pass/Trip offers. Undefined for Registration offers, or when the selector is shown but no selection has been made yet.

Quote Object Fields

Field	Type	Description
`id`	`string`	Unique identifier for the quote
`expiresAt`	`string`	ISO8601 date-time indicating when the quote expires
`spotPrice`	`number`	Price of the Refund Guarantee
`currencyCode`	`string`	Currency in which the price is denominated
`communication`	`object`	Includes display name, description, legal disclaimer, etc.
`payoutSchedule`	`array` of objects	Refund schedule tiers with `text`, `percent`, and `amount` fields

Styling & Theming

To customize the widget's appearance, provide an object mapping any of the following CSS variables (without the -- prefix).

Variable	Description	Default
`spot-font-family`	Base font for all text	`Arial`
`spot-padding`	Padding inside the widget container	`1.25rem`
`spot-background-color`	Background color of the widget	`#ffffff`
`spot-font-color`	Default text color	`#000000`
`spot-border-radius`	Border radius for the widget container	`0.5rem`

Title and Description

Variable	Description	Default
`spot-title-font-size`	Font size of the title	`1.25rem`
`spot-title-font-weight`	Font weight of the title	`700`
`spot-title-padding`	Padding below the title	`0 0 1.25rem 0`
`spot-title-font-color`	Title text color	`var(--spot-font-color)`
`spot-title-font-family`	Title font	`var(--spot-font-family)`
`spot-description-font-size`	Font size of the description	`0.875rem`
`spot-description-font-weight`	Font weight of the description	`400`
`spot-description-padding`	Padding below the description	`0 0 0.5rem 0`
`spot-description-font-color`	Description text color	`var(--spot-font-color)`
`spot-description-font-family`	Description font	`var(--spot-font-family)`

Bullet List

Variable	Description	Default
`spot-bullets-font-size`	Font size of bullets	`0.875rem`
`spot-bullets-font-weight`	Font weight of bullets	`400`
`spot-bullets-font-color`	Bullet text color	`var(--spot-font-color)`
`spot-bullets-font-family`	Bullet font	`var(--spot-font-family)`
`spot-bullets-padding`	Padding around bullet list	`0.3125rem`

Payout Table

Variable	Description	Default
`spot-table-border-radius`	Border radius of the table	`0.625rem`
`spot-table-header-font-size`	Font size of table headers	`0.875rem`
`spot-table-header-font-weight`	Font weight of table headers	`700`
`spot-table-header-font-color`	Table header text color	`var(--spot-font-color)`
`spot-table-header-font-family`	Table header font	`var(--spot-font-family)`
`spot-table-header-padding`	Padding in table headers	`0 0.5rem 0.625rem`
`spot-table-cell-font-size`	Font size of table cells	`0.815rem`
`spot-table-cell-font-weight`	Font weight of table cells	`400`
`spot-table-cell-font-color`	Table cell text color	`var(--spot-font-color)`
`spot-table-cell-font-family`	Table cell font	`var(--spot-font-family)`
`spot-table-cell-padding`	Padding in table cells	`0 0.625rem`

Radio Options

Variable	Description	Default
`spot-radio-border`	Radio border color	`#000000`
`spot-radio-border-radius`	Radio button shape	`0.625rem`
`spot-radio-checked-background`	Background color when checked	`#000000`
`spot-radio-text-font-size`	Font size for radio labels	`0.875rem`
`spot-radio-text-font-weight`	Font weight for radio labels	`400`
`spot-radio-text-font-color`	Radio label color	`var(--spot-font-color)`
`spot-radio-text-font-family`	Font for radio labels	`var(--spot-font-family)`
`spot-radio-text-padding`	Padding in radio options	`0.625rem`
`spot-radio-selection-background`	Background of selected option	`#f4f4f4`
`spot-radio-selection-border-radius`	Border radius of selection	`0.625rem`
`spot-radio-selection-padding`	Padding of selection area	`0.625rem`

"Recommended" Tag

Variable	Description	Default
`spot-recommended-tag-background`	Background color	`#000000`
`spot-recommended-tag-font-color`	Text color	`#ffffff`
`spot-recommended-tag-font-size`	Font size	`0.875rem`
`spot-recommended-tag-font-weight`	Font weight	`700`
`spot-recommended-tag-padding`	Padding	`0.25rem 0.5rem`
`spot-recommended-tag-border-radius`	Border radius	`0.5rem`

Error Message

Variable	Description	Default
`spot-selection-error-font-color`	Text color for errors	`#ff0000`
`spot-selection-error-font-size`	Font size	`0.875rem`
`spot-selection-error-padding`	Padding	`0.5rem`

Terms and Links

Variable	Description	Default
`spot-terms-font-size`	Font size for terms text	`0.75rem`
`spot-terms-font-weight`	Font weight	`400`
`spot-terms-font-color`	Color	`#636569`
`spot-terms-font-family`	Font	`var(--spot-font-family)`
`spot-terms-padding`	Padding	`0`
`spot-terms-link-text-decoration`	Link decoration	`underline`
`spot-terms-link-font-size`	Font size	`0.75rem`
`spot-terms-link-font-weight`	Font weight	`400`
`spot-terms-link-font-color`	Link color	`#636569`
`spot-terms-link-font-family`	Font for links	`var(--spot-font-family)`
`spot-terms-link-padding`	Padding	`0`

Utility Methods

These methods are available on the widget instance after initialization:

Method	Description
`getSelection()`	Returns current selection – for ex: `{ selection: string, quoteId: string, spotPrice: number, state?: string, status: string}`
`validateSelection()`	Validates whether a selection has been made and if it's valid. Displays an error message (`"Please make a selection"`) otherwise
`destroy()`	Destroys the widget, cleans up any event listeners or references

Overview

Embed in One Script Tag

Quote Request Data

Single vs Multi-Item Carts:

Installation Options

CDN (UMD)

ES Module Format (for modern JavaScript projects)

NPM

Framework Options

Configuration Options

Widget Options

apiConfig Parameters

Single Quote quoteRequestData Parameters

Batch Quote quoteRequestData Parameters

cartInfo Parameters

items Parameters

Callbacks

SelectionData Fields

Quote Object Fields

Styling & Theming

Title and Description

Bullet List

Payout Table

Radio Options

"Recommended" Tag

Error Message

Terms and Links

Utility Methods

`apiConfig` Parameters

Single Quote `quoteRequestData` Parameters

Batch Quote `quoteRequestData` Parameters

`cartInfo` Parameters

`items` Parameters