By Category

Get the protection plans and prices for a SureBright category and product price, without a product in your catalogue. Parameters, example request and response, and errors.

GET https://{HOST_NAME}/quote/api/quote/category/listQuotes

Use this endpoint to price protection plans from a category and a product price, when the item is not a product SureBright can look up in your store's catalogue. It suits quoting tools, in-store sales and custom checkouts. One call can price several items, and the IDs it returns are the ones Create Contracts for Order accepts.

Get the category IDs from List Category first. If the item is in your store's catalogue, By Product or By Url is simpler, and for a whole cart use Cart quotes.

Note#

All quote inputs go inside the payload JSON, which is sent Base64-encoded (UTF-8) as a query parameter. Send quoteSyncMode=SYNC when you will record an order with the returned quoteId and quoteItemId.

Headers#

No authentication header is needed for this endpoint.

Query parameters#

NameTypeRequiredDescription
payloadstringYesThe JSON object described below, UTF-8, Base64-encoded, then URL-encoded like any query value.
quoteSyncModestringNoSYNC saves the quote before the response returns. Any other value, or none, is treated as ASYNC, which saves it in the background. Send SYNC when you will pass the IDs to Create Contracts for Order straight away.

Payload fields#

NameTypeRequiredDescription
countrystringYesTwo-letter country code of the customer, for example US or CA. It has to match the country of the category you are quoting, or that entry returns no plan.
visitIdstringYesAny unique identifier for the shopper session.
platformstringYesThe platform you are calling from, for example OFFLINE_PORTAL as in the example below. SHOPIFY changes the response format (see Behaviour notes).
storeIdstringYes, unless storeParentId is sentYour store identifier.
storeParentIdstringYes, unless storeId is sentYour SureBright account identifier. Required when an entry is quoted by sbCategoryId.
provincestringNoState or province of the customer.
storeCategoryListobject[]YesOne entry per item to quote. Must not be empty.
storeCategoryList[].sbCategoryIdstringOne of sbCategoryId or storeCategoryIdSureBright category ID from List Category. Used only when the payload also carries storeParentId.
storeCategoryList[].storeCategoryIdstringOne of sbCategoryId or storeCategoryIdStore category ID from List Category.
storeCategoryList[].productPricenumberNoPrice of the item. With it, you get the plans for the price band that contains it. Without it, you get every price band of the category.
storeCategoryList[].sbProductIdstringNoA product reference. It is stored on the quote and returned with it.
storeCategoryList[].manufacturerWarrantyDurationintegerNoManufacturer warranty of the item, in months.

Example request#

The payload before encoding:

json
{
  "storeParentId": "{storeParentId}",
  "country": "US",
  "visitId": "3d99a4ae-5cf0-4d87-8436-46c0cdc03676",
  "platform": "OFFLINE_PORTAL",
  "storeCategoryList": [
    { "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f", "productPrice": 899.99 }
  ]
}

Encode it and call the endpoint. --data-urlencode takes care of the +, / and = characters in the Base64 string.

bash
PAYLOAD=$(printf '%s' '{"storeParentId":"{storeParentId}","country":"US","visitId":"3d99a4ae-5cf0-4d87-8436-46c0cdc03676","platform":"OFFLINE_PORTAL","storeCategoryList":[{"sbCategoryId":"4c3103e4-38dc-4171-96e5-b4b77ab0e96f","productPrice":899.99}]}' | base64 | tr -d '\n')

curl -G 'https://{HOST_NAME}/quote/api/quote/category/listQuotes' \
  --data-urlencode "payload=${PAYLOAD}" \
  --data-urlencode 'quoteSyncMode=SYNC'

Example response#

200, trimmed to the fields you are most likely to use:

json
{
  "quoteList": [
    {
      "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537",
      "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f",
      "storeCategoryId": "ecca4210-09a4-446c-ad87-5e65bd50df12",
      "country": "US",
      "productPrice": 899.99,
      "coverageType": "AD",
      "quoteItemList": [
        {
          "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537",
          "quoteItemId": "a7defcbd-aa07-4e01-9076-c1935af20a98",
          "coverageYears": "1",
          "policyPrice": "79",
          "lowerPrice": 749.99,
          "upperPrice": 999.99,
          "storeProductVariantPrice": "899.99"
        }
      ],
      "coverageList": [
        {
          "optionType": "COVERAGE_OPTION",
          "info": "Coverage bullet shown to the shopper",
          "popup": "Coverage bullet shown in the details popup"
        }
      ]
    }
  ]
}
FieldTypeMeaning
quoteListobject[]The quotes for the entries that could be priced.
quoteList[].quoteIdstringIdentifies the quote. Send it as planDetails.quoteId when you create the contract.
quoteList[].sbCategoryId, storeCategoryIdstringThe category the quote was priced under. Use these to match a quote back to the entry you sent.
quoteList[].coverageTypestringCoverage type of the plan, for example AD.
quoteList[].quoteItemListobject[]One entry per plan, sorted by tenure.
quoteItemList[].quoteItemIdstringIdentifies the plan. Send it as planDetails.quoteItemId when you create the contract.
quoteItemList[].coverageYearsstringLength of the plan in years.
quoteItemList[].policyPricestringPrice of the plan.
quoteItemList[].lowerPrice, upperPricenumberThe product price band this plan price applies to. Most useful when you did not send productPrice.
quoteItemList[].storeProductVariantPricestringThe productPrice you sent.
quoteItemList[].deductibleAmountnumberAmount the customer pays per claim, when the plan has one.
quoteList[].coverageListobject[]Coverage text for display. Each entry has an optionType (COVERAGE_OPTION or WHY_SUREBRIGHT_OPTION) and the text in info and popup.

Errors#

StatusBodyCause and what to do
400{"isError": true, "message": "Insufficient params"}country, visitId or platform is missing, neither storeId nor storeParentId was sent, or storeCategoryList is missing or empty.
200{"quoteList": []}, or fewer quotes than entriesNo plan for one or more entries. See Behaviour notes.
200A plain-text message instead of JSONpayload is missing or does not decode to JSON. Treat any response without a quoteList array as a failure and fix the encoding.

Behaviour notes#

  • An entry with no plan is left out. The call still returns 200. If nothing can be priced, quoteList is empty. Do not match quotes to entries by position; use sbCategoryId or storeCategoryId.

  • What stops an entry being priced. The category ID is not set up for your store, country differs from the category's country, no price band contains productPrice, or the entry carries sbCategoryId while the payload has no storeParentId.

  • Every call creates new quotes. Each priced entry gets a fresh quoteId on every call.

  • Use SYNC before creating contracts. With the default mode the quote is saved in the background, so a create call sent immediately afterwards may not find it.

  • sbCategoryId wins. When an entry has both IDs and the payload has storeParentId, the entry is quoted by sbCategoryId.

  • platform: SHOPIFY. Each quote comes back in the storefront widget format instead, with plans under PolicyData as described on Cart quotes.

Country and State Codes#

GEThttps://api.surebright.com/quote/api/quote/category/listQuotes

Lists warranty quote options for one or more products, by category and product price. Each quoteItemList entry carries a quoteId and quoteItemId; send these in planDetails when recording the order.

Query parameters

payloadstringrequired

Base64-encoded (UTF-8) JSON object. All quote inputs go inside this object, not as separate query parameters.

| Field | Type | Required | Description |
|---|---|---|---|
| country | string | Yes | Alpha-2 country code of the customer, e.g. US |
| visitId | string | Yes | Any unique identifier for the shopper session |
| platform | string | Yes | Calling platform, e.g. OFFLINE_PORTAL |
| storeParentId | string | Yes, unless storeId is sent | Unique identifier for the store parent. Required when quoting by sbCategoryId |
| storeId | string | Yes, unless storeParentId is sent | A unique identifier for a store |
| province | string | No | State or province code of the customer |
| storeCategoryList | array | Yes | One entry per product to quote. Must not be empty |
| storeCategoryList[].sbCategoryId | string | sbCategoryId or storeCategoryId | SureBright category ID from List Categories |
| storeCategoryList[].storeCategoryId | string | sbCategoryId or storeCategoryId | Store category ID from List Categories |
| storeCategoryList[].productPrice | number | Yes | Price of the product being protected |
| storeCategoryList[].sbProductId | string | No | SureBright product ID |
| storeCategoryList[].manufacturerWarrantyDuration | integer | No | Manufacturer warranty, in months |

Example: JSON before Base64 encoding

json
{
  "storeParentId": "13612f29-8ec5-49ad-bab1-5ab09b51367e",
  "country": "US",
  "visitId": "3d99a4ae-5cf0-4d87-8436-46c0cdc03676",
  "platform": "OFFLINE_PORTAL",
  "storeCategoryList": [
    {
      "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f",
      "productPrice": 199.99
    }
  ]
}
Example
eyJzdG9yZVBhcmVudElkIjoiMTM2MTJmMjktOGVjNS00OWFkLWJhYjEtNWFiMDliNTEzNjdlIiwiY291bnRyeSI6IlVTIiwidmlzaXRJZCI6IjNkOTlhNGFlLTVjZjAtNGQ4Ny04NDM2LTQ2YzBjZGMwMzY3NiIsInBsYXRmb3JtIjoiT0ZGTElORV9QT1JUQUwiLCJzdG9yZUNhdGVnb3J5TGlzdCI6W3sic2JDYXRlZ29yeUlkIjoiNGMzMTAzZTQtMzhkYy00MTcxLTk2ZTUtYjRiNzdhYjBlOTZmIiwicHJvZHVjdFByaWNlIjoxOTkuOTl9XX0=
quoteSyncModestring

Send SYNC to save the quote before the response returns, so its quoteId and quoteItemId can be used to record an order straight away.

Example: SYNC