Custom platform integration

Offer SureBright protection on a custom-built or unsupported store platform: create the plan products from your SKUs, add the SureBright SDK to your storefront, and send your orders to SureBright.

Use this page when your store runs on a platform SureBright has no app or plugin for, such as a custom-built site, an in-house commerce stack or a platform not on Supported platforms. The integration has three parts:

  1. Plan products in your store. SureBright shares your plan SKUs, and you create one product for each in your catalogue.

  2. The SureBright SDK on your storefront. It shows the protection offer on product and cart pages, and tells your code which plan the shopper picked.

  3. Your orders sent to SureBright. Each order that includes a plan is sent to SureBright's order webhook, and SureBright creates the contracts and emails your customer.

Who does what#

StepWhoWhat happens
Set up your store in SureBrightSureBrightYour catalogue is categorised, plan prices are set, and you get your store ID and API key.
Share the plan SKUsSureBrightYou get the SKU list as a CSV. You can also download it from the Merchant Portal.
Create the plan productsYouOne product per plan SKU in your store catalogue.
Design the offerSureBright, with youThe look and placement of the offer, set in the Merchant Portal's widget designer.
Add the SDK and handle plan selectionYour developersOne script tag, plus a few lines of code that add the plan product to the cart.
Send ordersYour developersA call to SureBright's order webhook when an order is paid, and again when it is cancelled or refunded.
Create contracts and email customersSureBrightOne contract per plan unit sold, emailed to the customer.

Step 1: create the plan products#

SureBright shares a CSV with one row per plan SKU: the SKU, a description and the price. Each SKU stands for a plan length, region, coverage type and price band, for example SBW-1U-CEAD-49999. See Download your plan SKUs for every column.

Create one product in your store for each row:

SettingSet it toWhy
SKUThe InventoryID value, exactlySureBright matches the plan line on your orders by this SKU.
TitleThe Description value, or your own wordingShown on the cart, the checkout and the order confirmation.
PriceThe BasePrice valueThe price the shopper pays for the plan.
ShippingNot shipped, no weightThere is nothing to pick, pack or deliver.
TaxYour setting for service or warranty itemsAgree it with your accountant.
VisibilityHidden from search, collections and product listingsShoppers add a plan through the SureBright offer, never from a product page.
DiscountsExcluded from store-wide discounts and couponsA discounted plan still costs you the full plan price.

If your platform has product variants, you can also create one plan product with one variant per SKU. What matters is that each SKU exists exactly once.

When SureBright adds new price bands later, it tells you. Download the SKUs again and create the new rows.

Step 2: add the SureBright SDK to your storefront#

Add the SDK script to every page of your storefront, with your store ID and the CUSTOM platform:

html
<script id="sbsimxsdk" async
        src="https://cdn.surebright.com/sbsimxsdk.js"
        data-sb-store-id="YOUR_STORE_ID"
        data-sb-platform="CUSTOM"></script>

On product and cart pages the SDK shows the offer where SureBright has placed it for your store. It needs to know which product the shopper is looking at, and it tells your code when a plan is chosen. Your developers wire both, following Headless and custom storefronts.

Add the plan to the cart#

When the shopper picks a plan, the SDK calls your handler with the plan and the product it covers:

javascript
window.SureBright.onSelectionChange(function (change) {
  if (change.action === "selected" && change.quote) {
    // Add the plan product whose SKU matches the selected plan,
    // linked to the cart line of the product it covers.
    addPlanToCart(change.quote, change.product);
  } else if (change.action === "deselected") {
    removePlanFromCart(change.product);
  }
});

Keep the plan's quote details with the plan line (at least quoteId, quoteItemId and the covered product's ID), and carry them through to the order. SureBright needs them to know which product the plan covers. The full payload is in the JavaScript API reference.

A plan line that reaches the order without its quote details cannot be matched to the product it covers, so no contract is created for it. Test that your cart, checkout and any app that edits orders keep them.

Step 3: send your orders to SureBright#

When an order that includes a plan is paid, your system sends it to SureBright's order webhook with your API key. SureBright creates one contract per plan unit and emails the customer their cover.

WhenSendReference
The order is paidThe order, its customer and line items, and for each covered line the plan boughtCreate contracts
A plan is cancelled, refunded or its quantity changesThe order ID and the plan lines that changedUpdate or cancel contracts
The covered product ships, on stores where cover starts at fulfilmentThe fulfilment date, once SureBright turns this on for your storeSet fulfilment dates

What every order needs:

  • the order ID, date and currency;

  • the customer's name, email and address, so the customer can be sent their plan and can claim;

  • each covered product line, with its product ID, title, price and quantity;

  • each plan line, with its SKU, price, quantity and the quote details from Step 2.

Send each order once when it is paid. Sending the same order again does not create duplicate contracts. After a server error, look the order up with Get contracts before you send it again. If your system cannot call a webhook yet, you can start with a spreadsheet of orders and switch later.

Step 4: test before you launch#

  1. Check the offer

    On a product page that should show protection, the offer appears where SureBright placed it. Pick a plan and check the plan product is added to the cart with the right SKU and price.

  2. Place a test order

    Complete an order with one product and one plan. Check that your system sent it to SureBright and got a success response.

  3. Find the contract

    The plan shows in Sales in the Merchant Portal, and the test customer receives the plan email.

  4. Cancel it

    Cancel or refund the test order and check the contract is cancelled.

Tell your SureBright contact when the test passes. SureBright checks the contract details with you before your store goes live.