Integrate with the API
The end-to-end path for a custom storefront or back office: list categories, get quotes, show the offer, create contracts when the order is paid, report fulfilment, update or cancel, and look contracts up.
This page walks one order through the SureBright API, from the first quote to a cancelled plan. It is for teams selling from their own storefront, app or back office rather than through one of SureBright's platform integrations.
Each step names the endpoint, shows a minimal request and lists the response fields the next step needs. The linked reference pages carry the full field lists.
Before you start#
You need the API host (HOST_NAME), your storeId and an API key. Authentication says where each comes from. The category and quote calls in steps 1 to 3 take no key. Make the Order calls from your server, never from the browser, so the key stays private.
While you build, keep "isTestOrder": true in the order body in step 4. The order is recorded as a test order with a Test badge on Sales. See Live keys and testing.
The integration, step by step#
Get your store's categories
List Category:
GET /quote/api/storeCategory/listStoreCategoriesbashcurl 'https://{HOST_NAME}/quote/api/storeCategory/listStoreCategories?storeId={storeId}'The response is an array. From each entry keep:
If your store uses the category tree, the same endpoint returns one level per call, or every priced leaf with
view=leaves. The reference page explains both.Get quotes for a product
By Category:
GET /quote/api/quote/category/listQuotesAll inputs go in one JSON object, sent Base64-encoded as the
payloadquery parameter. SendquoteSyncMode=SYNCso the quote is saved before the response returns and can be used in step 4 straight away.bashPAYLOAD=$(printf '%s' '{ "storeParentId": "{storeParentId}", "country": "US", "visitId": "3d99a4ae-5cf0-4d87-8436-46c0cdc03676", "platform": "OFFLINE_PORTAL", "storeCategoryList": [ { "sbCategoryId": "{sbCategoryId}", "productPrice": 199.99 } ] }' | base64 | tr -d '\n') curl -G 'https://{HOST_NAME}/quote/api/quote/category/listQuotes' \ --data-urlencode 'quoteSyncMode=SYNC' \ --data-urlencode "payload=${PAYLOAD}"country,visitId,platformand a non-emptystoreCategoryListare required, andstoreParentIdmust be present when you quote bysbCategoryId.visitIdis any identifier you generate for the shopper's session. Addprovincewhen you know the shopper's state or province. EachstoreCategoryListentry quotes one product.From
quoteList[]keep:An empty
quoteListmeans no plan matched that category and price. Show no offer.To quote by your own product and variant ids instead, see By Product. It only works for products SureBright already knows.
Show the offer and let the shopper pick
There is no API call in this step. Render one option per
quoteItemListentry with its term and price, plus a way to decline. When the shopper picks a plan, store itsquoteId,quoteItemIdand price on your cart line.To read a saved quote back later, use Get a quote. When you render the offer yourself, post shopper interactions to the Event Collector if you want them in Sales analytics. If you would rather not build the offer UI, see Headless and custom storefronts.
Create the contracts when the order is paid
Create Contracts for Order:
POST /partner/api/v1/orderCall this once payment has succeeded. Contracts are created as soon as the request is accepted. If the request times out, send it again with the same
orderId; see Limits, idempotency and versioning.bashcurl -X POST 'https://{HOST_NAME}/partner/api/v1/order' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{storeId}", "orderId": "ORDER-1001", "orderPurchaseDate": "2026-11-12T10:15:30Z", "orderLineItemList": [ { "lineItemId": "LINE-1", "productId": "PROD-1", "productSKU": "SKU-1", "productTitle": "Sample product", "quantity": 1, "salePrice": 199.99, "totalPrice": 199.99, "planDetails": { "policyPurchaseDate": "2026-11-12T10:15:30Z", "quoteId": "{quoteId}", "quoteItemId": "{quoteItemId}" } } ], "customerDetails": { "firstName": "Test", "lastName": "Customer", "customerEmail": "test.customer@example.com", "addressLine1": "123 Main St", "city": "Austin", "state": "TX", "country": "US", "zipCode": "78701" }, "isTestOrder": true }'What the request must carry:
Dates are ISO 8601 with
Zor a timezone offset. PutplanDetailsonly on the lines that carry a plan; a line without it creates nothing. One contract is created per unit ofquantity.In the response,
contractList[]has one entry per contract (lineItemId,contractId,isCancelled). Store eachcontractIdagainst your order line.errorList[]is present when something failed.200means no line failed.207means some contracts were created and some lines failed.400means nothing was created. SureBright emails the customer the plan confirmation; see Emails your customers receive.Report fulfilment (only if coverage starts at shipment)
Set or revert fulfillment dates:
POST /order/api/v1/contract/fulfillmentSkip this step unless your store is set up so that coverage starts when the product ships. The endpoint is enabled per store by SureBright and uses its own server-to-server token, not your API key. Ask your SureBright contact before you build it.
bashcurl -X POST 'https://{HOST_NAME}/order/api/v1/contract/fulfillment' \ -H 'Authorization: Bearer {SERVICE_TOKEN}' \ -H 'Content-Type: application/json' \ -d '{ "contractIds": ["{contractId}"], "action": "SET", "fulfillmentDate": "2026-11-14T09:00:00Z" }'Check
results[]: each entry carries thecontractId, itseffectiveDateandexpirationDate, andskipped: truewhen the contract already had dates."action": "REVERT"clears the dates after a cancelled shipment.Update or cancel
Cancel / Update contracts for Order:
PUT /partner/api/v1/orderSend the whole order again with the same
orderId, changed to how it stands now. The body has the same shape and required fields as step 4; it is not a partial update.To cancel a whole order, do this for every plan line. Keep
productIdandoptionIdthe same as in step 4, because a line's existing contracts are found by them. Cancelled contracts come back incontractListwithisCancelled: trueand cannot be reactivated. The customer receives a cancellation email.Look contracts up
Get Contracts for Order:
GET /partner/api/v1/orderbashcurl -G 'https://{HOST_NAME}/partner/api/v1/order' \ --data-urlencode 'storeId={storeId}' \ --data-urlencode 'partnerOrderId=ORDER-1001' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY'partnerOrderIdis theorderIdyou sent in step 4.data.orderis the order as SureBright stored it anddata.contractslists its active contracts; cancelled contracts are left out. A404witherrorCode: ORDER_NOT_FOUNDmeans there is no order with that id on that store.The lookup is one order per call. To see all contracts for a period, use the export on Sales.
Where claims are filed#
There is no claims step to build: the API has no claim endpoints. Customers file a claim in the customer portal or by email, as described in Filing a claim.