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:
Plan products in your store. SureBright shares your plan SKUs, and you create one product for each in your catalogue.
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.
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#
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:
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:
<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:
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.
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#
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.
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.
Find the contract
The plan shows in Sales in the Merchant Portal, and the test customer receives the plan email.
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.
Related#
If your platform is not listed: the smaller ways to start, and other checkouts, apps and native mobile apps.
Request a platform: ask SureBright to build an app for your platform.
Headless and custom storefronts: the developer guide for the SDK.