Bigcommerce Headless SDK

In order to integrate the Shipped Widget in a headless Bigcommerce store, please follow these instructions:

1. Add the Shipped Suite JS SDK right before the closing </head> tag

<script defer src="https://js.shippedsuite.com/bigcommerce/headless-widget.js?store_hash=your_store_hash"></script>

Change your_store_hash in the URL with your Bigcommerce store hash. It can be derived from your Bigcommerce store dashboard URL. For example, if your URL is https ://store-xxxxxxxxx.mybigcommerce.com/ then your_store_hash value is xxxxxxxxx.

📘

Staging JS SDK

For staging environment, use https://js-staging.shippedsuite.com/bigcommerce/headless-widget.js?store_hash=your_store_hash

2. Add the div snippet where you would like the widget to appear in the cart or checkout flow.

<div class="shipped-widget"></div>

3. Add a new <script></script> and instantiate the JS SDK:

<script>
window.addEventListener('shipped:script-loaded', () => {
  var shippedWidget = new Shipped.Widget({
    widgetSelector: '.shipped-widget'
  })
})
</script>

5. 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 frontend.

shippedWidget.onChange((details) => {
 
  // Example 'details':
  // {
  //   "isSelected": true,
  //   "totalFee": "2.23",
  //   "shippedProducts": [] // see shippedProducts details under `onShipped` method below
  // }

})

6. When the cart changes, for example products are added or removed, product quantity is changed, you need to trigger update method. The widget will update its state and price offer based on the new cart total.

shippedWidget.update()

7. Optionally, you can choose not to have Shipped product(s) added automatically to cart when the widget is loaded, so you can add them manually. For this, you need to implement a handler for onShipped method.

shippedWidget.onShipped((shippedProducts) => {
 
  // shippedProducts example:
  // [
  //     {
  //         "variantId": 184,
  //         "productId": 142,
  //         "productTitle": "Shipped Shield Package Assurance",
  //         "productDescription": [
  //             "Shipped Shield offers premium package assurance for shipments that are lost, damaged or stolen.\nInstantly track and resolve shipment issues hassle-free with the app.\n"
  //         ],
  //         "productImageURL": "https://cdn11.bigcommerce.com/s-gp0jesx31h/products/142/images/405/shield-be9ba978feb179704666141db2d825d1f9d9cc55787fdcbf9885dff04b0dd644__51892.1666107765.386.513.png?c=1",
  //         "price": "3.94",
  //         "type": "shield",
  //         "mandatory": false
  //     }
  // ]

})

8. Whitelist *.shippedsuite.com domain.

   Shipped Widget is making requests to js.shippedsuite.com and admin.shippedsuite.com 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 localizecdn.com domain.