Shield Widget - JavaScript SDK

In order to integrate the Shipped Shield/Green Widget in your website, please follow these instructions:

  1. Add the Shipped Suite JS SDK right before the closing </head> tag
<script defer src=""></script>


Staging JS SDK

For staging environment, use

  1. Add the div snippet where you would like the widget to appear in the cart or checkout flow.
<div class="shipped-widget"></div>
  1. Add a new <script></script> and instantiate the JS SDK:
window.addEventListener('shipped:script-loaded', () => {
  const shippedWidget = new Shipped.Widget({
    publicKey: 'your_publishable_key_here',
    widgetSelector: '.shipped-widget'


How to obtain API keys

Please reference Authentication section for information about how to obtain your API key.


Ensure correct key

Make sure you are using a public key, not a secret key, and that it is for the correct environment (staging vs production)

  1. Update the order value when the cart loads/changes. This value should be the sum of the selling price (prior to any discounts) of all the items in the cart, excluding adjustments like shipping and tax.
  1. Listen and react to onChange. When a user opts in or opts out of Shipped Widget, or when the offer changes, we will trigger the onChange callback. Your code should provide a handler for this callback, and ensure any necessary processing required by your backend server. For example:
shippedWidget.onChange((details) => {
  // Example 'details':
  // {
  //   "isSelected": true,
  //   "totalFee": "2.23"
  // }
  if (details.isSelected) {
    // ajax call to add Shipped product to the cart
    fetch('/api/add-product', {
      method: 'POST',
      body: JSON.stringify({
        productName: 'Shipped Shield - Package Assurance for unexpected issues',
        productPrice: details.totalFee
  } else {
    // ajax call to remove Shipped product from the cart
  1. Whitelist * domain.

    Shipped Widget is making requests to and in order to load the widget script and to fetch Shipped fee information.

    If you configure the widget to support other languages, you'll also need to whitelist domain.