By Product

Get the protection plans and prices for a platform product and variant in a given country. Parameters, example request and response, and errors.

GET https://{HOST_NAME}/quote/api/quote/listWarrantyQuotes

Use this endpoint to price protection plans for one product variant, for example on a product page. You identify the product by the productId and variantId it has in your store. SureBright returns the plans it can offer for that variant, each with a price, a tenure and the plan product to add to the cart.

The product has to be in the catalogue SureBright holds for your store. Pick the quote endpoint by what you know about the item:

You haveUse
The product ID and variant IDThis page
Only the product page URLBy Url. It is the same endpoint with productUrl in place of the two IDs
A category and a price, with no product in the catalogueBy Category
A cart, and you want one plan across its eligible itemsCart quotes

Headers#

HeaderDescriptionRequired
X-SureBright-Access-TokenAccess token for authenticationNo

Query parameters#

NameTypeRequiredDescription
storeIdstringYesYour store identifier. On Shopify this is the myshopify.com domain.
productIdstringYesThe product's ID in your store. Not needed when you send productUrl instead (see By Url).
variantIdstringYesThe variant's ID in your store. Send it with productId.
countrystringYesCountry of the shopper. Must be exactly US or CA, in upper case. Any other value returns 502.
platformstringNoYour store platform: SHOPIFY, BIGCOMMERCE, SHIFT4SHOP, LIGHTSPEED, LIGHTSPEED_R_SERIES, MAGENTO or WOOCOMMERCE. Defaults to SHOPIFY.
statestringNoState code of the shopper. Accepted, but not used to price the quote.

Example request#

bash
curl 'https://{HOST_NAME}/quote/api/quote/listWarrantyQuotes?platform=SHOPIFY&storeId=example-store.myshopify.com&productId=8606368530686&variantId=45667967238398&country=US'

Example response#

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

json
{
  "warrantyQuoteId": "929d14dd-2937-4290-9818-8fca2a00a9a3",
  "productTitle": "Example Espresso Machine",
  "categoryName": "Small Home Appliance",
  "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f",
  "coverageWidgetHeading": "Add premium product protection",
  "warrantyQuoteItemList": [
    {
      "warrantyQuoteItemId": "8c78bc1a-0790-4cd3-a3f9-5ed97bbe59f5",
      "warrantyTenure": 2,
      "warrantyPrice": 64.99,
      "warrantyProductId": 7080029454439,
      "warrantyVariantId": 40937702359143,
      "policyProductSKU": "SBW-1U-SHAB-2900"
    }
  ],
  "coverageList": [
    {
      "coverageItemType": "COVERAGE_OPTION",
      "coverageItemTitle": "Your warranty plan provides,",
      "coverageItemList": ["Coverage bullet shown to the shopper"]
    },
    {
      "coverageItemType": "WHY_SUREBRIGHT_OPTION",
      "coverageItemTitle": "Why Surebright?",
      "coverageItemList": ["Benefit bullet shown to the shopper"]
    }
  ],
  "tncLink": "https://customer.surebright.com/t-c/..."
}
FieldTypeMeaning
warrantyQuoteIdstringIdentifies this quote.
warrantyQuoteItemListobject[]One entry per plan on offer.
warrantyQuoteItemList[].warrantyQuoteItemIdstringIdentifies the plan within the quote.
warrantyQuoteItemList[].warrantyTenurenumberLength of the plan in years.
warrantyQuoteItemList[].warrantyPricenumberPrice of the plan.
warrantyQuoteItemList[].warrantyProductId, warrantyVariantIdnumber or stringThe plan product and variant in your store's catalogue. Add this variant to the cart when the shopper picks the plan.
warrantyQuoteItemList[].policyProductSKUstringSKU of the plan product.
warrantyQuoteItemList[].deductibleAmountnumberAmount the customer pays per claim, when the plan has one.
coverageListobject[]Coverage text grouped for display. coverageItemType is COVERAGE_OPTION or WHY_SUREBRIGHT_OPTION; coverageItemList holds the bullet points.
coverageWidgetHeading, coveragePopupHeadingstringHeadings for the offer and for the details popup.
productTitle, productImageURLstringTitle and image of the product being covered.
categoryName, sbCategoryIdstringThe SureBright category the product was priced under.
tncLinkstringLink to the plan's terms.

Errors#

Every error has the shape below. The HTTP status code and errorType carry the same value.

json
{ "isError": true, "errorType": 504, "errorMessage": "PRODUCT_NOT_ELIGIBLE" }
StatuserrorMessageCause and what to do
501Insufficient Params. Mandatory Params missingstoreId or country is missing, or you sent neither productUrl nor both productId and variantId.
502Validation failed for input paramscountry is not exactly US or CA.
504PRODUCT_DETAILS_NOT_FOUNDSureBright has no record of that product for the store, or the variant has no price. Check the IDs and the platform value.
504PRODUCT_NOT_ELIGIBLEThe product is marked as not eligible for a plan. Do not show an offer.
505POLICY_BAND_NOT_FOUNDNo plan is priced for this product's category at its price. Do not show an offer.
500UNKNOWN_EXCEPTIONNo plan can be offered for another reason, for example the store is not recognised, protection is switched off for the product, the price is zero, or plans are not offered in that country for your store. Retrying returns the same answer.
500Something unexpectedly went wrongUnexpected failure, or a platform value that is not in the list above.

See HTTP status codes for the full list shared with By Url.

Behaviour notes#

  • No plan is an error, not an empty list. When a product cannot be covered you get one of the 504, 505 or 500 bodies above instead of an empty warrantyQuoteItemList. Hide the offer on any status other than 200.

  • What makes a product ineligible. The product is missing from the catalogue SureBright holds for your store, it is marked as not eligible, protection is switched off for it, its price is zero or missing, there is no plan priced for its category and price, or plans are not offered in the shopper's country for your store.

  • Quotes can be reused. Calling again for the same store, product, variant and country can return the same warrantyQuoteId and item IDs.

  • state does not change the price on this endpoint.

  • Recording the sale yourself. This endpoint takes no quoteSyncMode. If you create contracts through Create Contracts for Order, quote with By Category, which can save the quote before it responds.

Country and State Codes#

GEThttps://api.surebright.com/quote/api/quote/listWarrantyQuotes

This endpoint retrieves a list of warranty quotes for a specific product and its price.

Query parameters

platformstring

The platform of the merchant's store. Defaults to SHOPIFY when omitted.

Example: SHOPIFY
storeIdstringrequired

The unique identifier for the merchant's store. This is typically the store's domain name (e.g., 'yourstore.myshopify.com' for Shopify stores).

Example: strictlyapple.myshopify.com
productIdstringrequired

The ID of the product that is shown to the customer

Example: 8606368530686
variantIdstringrequired

The ID of the variant that is shown to the customer

Example: 45667967238398
countrystringrequired

The country code of the identified customer location

Example: US
statestring

The state code of the identified customer location. Accepted but not currently used by this endpoint.

Example: AL