For Whole System Warranty

This endpoint generates warranty quotes for a whole system order. Provide your store, product line items, and installer warranty duration to receive available warranty plans, prices, product coverage details, and terms and conditions. When quotes are available, SureBright saves them and your product details as a proposal that you can update or use to create a contract.

For the whole flow, from the first quote to a cancelled plan, read the Whole System Warranty guide.

Headers#

HeaderDescriptionRequired
X-SureBright-Access-TokenAccess token for authenticationNo
Content-Typeapplication/jsonYes

Country#

This endpoint prices plans for the United States only. The request carries no country or state field. If your account has no United States Whole System Warranty set up, the call returns 512. If you sell in Canada, ask your SureBright contact.


Request fields#

FieldRequiredNotes
storeIdYesYour SureBright store id
lineItemListYesEvery line on the proposal. See the next table
installerWarrantyDurationYesThe installer's own installation warranty, as a number of months. See Installer warranty duration
partnerProposalIdNoYour own proposal reference. Keep it unique to one proposal on your storeId
sbProposalIdNoLeave out of the first request. Send it to re-quote an existing proposal. A non-empty string of at most 200 characters
sbAccountIdNoFor platforms quoting for a connected installer: the installer's sbAccountId. It is stored with the proposal as a reference and does not change the price. See Acting for an installer
partnerIdNoFor platforms: your client_id. When sent, SureBright takes your store from it, and a storeId sent with it must be that same store
sbSalesLeadIdNoOlder name for sbProposalId. See the backward-compatibility note

Each lineItemList entry:

FieldRequiredNotes
titleYesThe product name
unitPriceYesPrice of one unit
quantityYesNumber of units
descriptionNoHelps SureBright recognise the product
categoryTagNoYour own category for the product. Helps SureBright recognise it
productId, variantIdNoYour own ids for the line. Stored with the proposal

Installer warranty duration#

You sendResult
3, 6 or 12Priced on that length
Any other value above 3Priced on the nearest length below it: 9 is priced as 6, 24 as 12. A plan created from the quote is dated with that same length
Less than 3513 with No Quote Found
Nothing511 with installerWarrantyDuration is required

Requesting Quotes#

Send storeId, lineItemList, and installerWarrantyDuration to request warranty quotes for your products. Leave sbProposalId out of the initial request.

You can include a new partnerProposalId to associate the proposal with an ID from your system. Reusing an existing ID on the same storeId updates that proposal, so never use one reference for two different jobs.

When quotes are available, the response includes the warranty plans and sbProposalId. Save this ID to request updated quotes or create a contract.

How line items are priced#

Each line is assessed for eligibility, and only eligible lines are priced.

Response fieldMeaning
lineItemList[].isCoveredtrue when the line is eligible and counts towards the price. false when it is not: the line is not part of the plan
lineItemList[].sbCategoryNameThe SureBright category of a covered line. Empty for a line that is not covered
totalCoveredAmountunitPrice times quantity, added up across the covered lines only. The plans are priced on this figure
warrantyQuoteItemList[]One entry per plan term (2, 3 and 5 years) with warrantyQuoteItemId, coverageYears and quotePrice, the suggested customer price
warrantyQuoteItemList[].planCostWhat SureBright charges you for that plan. Left out when it is not available

If no line is covered the call returns 516. If the covered lines add up to zero it returns 515. There is no separate line type for installation labour on this endpoint: a labour line is assessed like any other line, so read its isCovered value.

Updating Quotes for an Existing Proposal#

Include sbProposalId or partnerProposalId with your current line items and installer warranty duration to request updated quotes for the same proposal. If you provide both, they must refer to the same proposal. A conflicting partnerProposalId returns HTTP 409 with code PROPOSAL_ID_MISMATCH.

Quotes are recalculated using the submitted product details and current pricing and coverage. If the products, classification, installer warranty duration, pricing, and coverage are unchanged, the existing quote and plan IDs are returned. If these details change, the proposal and its quotes are updated, and the IDs from the earlier quote for that installer warranty duration can no longer be used to create a contract.

A proposal keeps one quote per installer warranty duration. Quoting the same proposal with a different duration adds a quote for that duration and leaves the others in place. The warrantyQuoteId you send when you create the contract decides which one applies.

Once a platform has created a contract for a connected installer from a proposal, re-quote that proposal with sbProposalId. A request that carries only partnerProposalId does not find it and starts a new proposal.

To create or update a contract, submit sbProposalId, warrantyQuoteId, and the selected warrantyQuoteItemId to the Create / Update Contracts for Whole System Warranty endpoint. Use the quote and plan IDs from the same response. Updating quotes does not automatically update an existing contract.

Backward compatibility: The response also includes sbSalesLeadId with the same value as sbProposalId. Existing integrations can use it to request updated quotes or create and update contracts. Leave it out of the initial quote request. If you provide both sbProposalId and sbSalesLeadId, their values must match; otherwise, this quote endpoint returns HTTP 409 with code SB_PROPOSAL_ID_MISMATCH. Any supplied partnerProposalId must refer to the same proposal. For new integrations, use sbProposalId.

Errors#

Error bodies are {"isError": true, "message": "..."}. They carry no errorType field. A code is added on the rows that show one; on the 403, 404, 409 and 502 rows it is present when the request carried sbProposalId or sbSalesLeadId.

StatuscodemessageCause and what to do
511Insufficient ParametersThe body, storeId or lineItemList is missing
511installerWarrantyDuration is requiredSend the installer warranty duration in months
512A message that the store has no active Whole System Warranty set up for the countryYour account is not set up for Whole System Warranty in the United States. Ask your SureBright contact
513No Quote FoundinstallerWarrantyDuration is below 3, a line has no title, or no plan matched the covered total
514Store Not FoundstoreId is not known
515Not EligibleThe covered lines add up to zero. Check unitPrice and quantity
516Category Not FoundNo line was recognised as eligible
400INVALID_SB_PROPOSAL_IDsbProposalId must be a non-empty string of at most 200 charactersFix sbProposalId, or leave it out to start a new proposal
400INVALID_SB_SALES_LEAD_IDsbSalesLeadId must be a non-empty string of at most 200 charactersFix sbSalesLeadId, or leave it out
404SB_PROPOSAL_NOT_FOUNDProposal Not FoundNo proposal has that sbProposalId
409PROPOSAL_ID_MISMATCHsbProposalId and partnerProposalId must identify the same proposalSend the pair that belongs together, or only sbProposalId
409SB_PROPOSAL_ID_MISMATCHsbProposalId and sbSalesLeadId must identify the same proposalSend one of the two, or the same value in both
409PARTNER_PROPOSAL_RESERVEDContract creation is in progress. Retry the proposal update after it finishes.A contract is being created from this proposal. Retry when the create call has returned
403PARTNER_PROPOSAL_ACCESS_DENIEDProposal does not belong to the supplied partner storeThe proposal has moved to a connected installer, and the storeId you sent is not the one the contract was created with
502QUOTE_PERSISTENCE_FAILEDCould not persist the partner quoteThe quote could not be saved. Request quotes again before you create or update a contract
500QUOTE_REQUEST_FAILEDUnable to process the quote requestA re-quote failed unexpectedly. Send it again
500Something Unexpectedly Went WrongUnexpected failure. Send it again

Requests that carry partnerId can also return:

StatuscodemessageCause
400INVALID_PARTNER_IDpartnerId must be a valid client identifierpartnerId is not a well-formed client_id
404PARTNER_NOT_FOUNDPartner is unavailableNo active application has that client_id
409PARTNER_STORE_MISMATCHpartnerId and storeId must identify the same partnerThe storeId you sent is not your application's store. Leave storeId out or correct it
503PARTNER_STORE_UNAVAILABLE or PARTNER_LOOKUP_UNAVAILABLESureBright could not look your application up. Retry

511 to 516 are application codes on this endpoint, not gateway errors. Read the message before you retry: only 500, 502 and 503 are worth retrying unchanged.

POSThttps://api.surebright.com/quote/api/whole-system/listQuotes

This endpoint generates warranty quotes for a whole system order. Provide your store, product line items, and installer warranty duration to receive available warranty plans, prices, product coverage details, and terms and conditions. When quotes are available, SureBright saves them and your product details as a proposal that you can update or use to create a contract. For an initial quote request, omit sbProposalId. You can include a new partnerProposalId to associate the proposal with an ID from your system. Save the returned sbProposalId for updated quotes and contract creation. To update quotes for an existing proposal, include sbProposalId or partnerProposalId with your current line items and installer warranty duration. Any supplied partnerProposalId must refer to the same proposal. Quotes are recalculated using the submitted details and current pricing and coverage. Unchanged products, classification, installer warranty duration, pricing, and coverage retain the existing quote and plan IDs; changed details update the proposal and its quotes. Use the quote and plan IDs from the same response when creating or updating a contract. Updating quotes does not automatically update an existing contract.

Backward compatibility: Existing integrations can use sbSalesLeadId to request updated quotes or create and update contracts. It has the same value as sbProposalId in the response. Omit it from the initial quote request. If both identifiers are supplied, their values must match; otherwise, the quote endpoint returns HTTP 409 with code SB_PROPOSAL_ID_MISMATCH. Any supplied partnerProposalId must refer to the same proposal. For new integrations, use sbProposalId.

Body

application/json
json
{
  "storeId": "test-store-id",
  "partnerProposalId": "9f3e21c6-6bdb-4c7f-9b91-2a4f9a2c7d11",
  "lineItemList": [
    {
      "title": "PMC Prophecy5 2-Way Floorstanding Speaker (Pair)",
      "unitPrice": 6500,
      "categoryTag": "Speaker Floorstanding",
      "quantity": 1,
      "description": "High-performance floorstanding speaker pair for immersive audio systems."
    }
  ],
  "installerWarrantyDuration": 3
}