Whole System Warranty API
How a proposal platform or an installer's own system quotes, creates, changes and cancels a Whole System Warranty plan through the SureBright API.
This guide shows how to add the Whole System Warranty to a proposal through the API: quote the plan from the proposal's line items, create it when the customer has bought, change it afterwards and cancel it. Each step names the endpoint and shows a minimal request. The linked reference pages carry the full field lists.
Which reader you are#
If your platform creates a plan without sbAccountId and sbStoreId, the plan is recorded under your platform's own account, not the installer's. To record each sale under the installer who made it, connect the installer first.
Before you start#
The quote call takes no key. The create and cancel calls take your key in the X-SureBright-Access-Token header. Make every call from your server, never from the browser.
The quote endpoint prices plans for the United States only. If you sell in Canada, ask your SureBright contact before you build.
The model: one proposal, one plan#
A proposal is one installation job. SureBright keeps one proposal record for it and creates at most one plan from it. The plan covers every eligible line on the proposal as a whole. There are no per-product plans to track.
Store sbProposalId and contractId against your own proposal. sbSalesLeadId in responses is an older name for sbProposalId and carries the same value.
The flow, step by step#
Quote from the proposal's line items
For Whole System Warranty:
POST /quote/api/whole-system/listQuotesSend every line on the proposal and the length of the installation warranty the installer gives, in months. Leave
sbProposalIdout of the first request.bashcurl -X POST 'https://{HOST_NAME}/quote/api/whole-system/listQuotes' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{storeId}", "partnerProposalId": "{yourProposalReference}", "installerWarrantyDuration": 12, "lineItemList": [ { "title": "{productName}", "description": "{productDescription}", "unitPrice": 2400, "quantity": 2 }, { "title": "{productName}", "unitPrice": 180, "quantity": 6 } ] }'storeId,lineItemListandinstallerWarrantyDurationare required. Each line needstitle,unitPriceandquantity.descriptionandcategoryTagare optional and help SureBright recognise the product.From the response keep:
Re-quote when the proposal changes
Same endpoint. Send the proposal's current lines and installation warranty length again, this time with
sbProposalId.bashcurl -X POST 'https://{HOST_NAME}/quote/api/whole-system/listQuotes' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{storeId}", "sbProposalId": "{sbProposalId}", "installerWarrantyDuration": 12, "lineItemList": [ { "title": "{productName}", "description": "{productDescription}", "unitPrice": 2400, "quantity": 3 } ] }'The response always carries the same
sbProposalId. A re-quote changes the proposal only. A plan that already exists stays as it is until you send step 4.Create the plan when the customer has bought
Create / Update Contracts for Whole System Warranty:
POST /partner/api/v1/order/whole-systemCall this once the customer has bought the plan and the installation is complete. The plan is dated from the day you create it, so do not create it for a proposal that is still open.
bashcurl -X POST 'https://{HOST_NAME}/partner/api/v1/order/whole-system' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{storeId}", "sbProposalId": "{sbProposalId}", "warrantyQuoteId": "{warrantyQuoteId}", "warrantyQuoteItemId": "{warrantyQuoteItemId}", "warrantyCoverageYears": 3, "warrantyPrice": {priceChargedToTheCustomer}, "customerDetails": { "customerFirstName": "{firstName}", "customerLastName": "{lastName}", "customerEmail": "{email}", "customerAddress1": "{streetAddress}", "customerCity": "{city}", "customerState": "{state}", "customerZipCode": "{zipCode}", "customerCountry": "US" } }'You do not send line items. The covered lines, the covered total and the installation warranty length come from the proposal as it was last quoted.
A
200response carriesisError: falseand the plan'scontractId. Store it.Cover begins on the day you create the plan and runs to the end of the term. For a breakdown, the manufacturer warranty and the installer's installation warranty apply first. See When coverage starts.
Change the covered items after the sale
This takes two calls. First re-quote as in step 2, with the same
sbProposalIdand the lines as they stand now. Then send step 3 again with the samesbProposalIdand the newwarrantyQuoteIdandwarrantyQuoteItemId. Because the proposal already has a plan, the call updates that plan and returns the samecontractId.After the 90 days, a call that would change the covered items returns HTTP
400witherrorType: 517and the messageLine items cannot be updated after 90 days of purchase date. Nothing on the plan changes.Cancel the plan
Cancel Contracts for Whole System Warranty:
POST /partner/api/v1/order/whole-system/cancelbashcurl -X POST 'https://{HOST_NAME}/partner/api/v1/order/whole-system/cancel?contractId={contractId}' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "cancellationReason": "{reason}" }'The request is the same for both readers. The rule that applies depends on how the plan was created:
A successful response is
200withisError: falseandcancelledContractId. CheckisErroron every200, because a plan that was already cancelled is also answered with200. Cancelling ends cover for every line on the plan. You cannot cancel one product; change the covered items with step 4 instead.cancellationReasonis optional and is recorded for plans created for a connected installer.After a cancellation, do not call create again for that proposal. If the customer buys again, quote the job as a new proposal.
Know what the customer and the installer see afterwards
There is no call in this step.
How line items are judged#
SureBright assesses every line you send for eligibility. Only eligible lines are priced.
Show the customer which lines are covered. A line that comes back with isCovered: false is not part of the plan and does not count towards its price. If a line you expected to be covered is not, check its title and description, add a categoryTag, and ask your SureBright contact if it still is not covered.
Labour lines. This endpoint has no separate line type for installation labour. A labour line is assessed like any other line, from its title, description and categoryTag. Check its isCovered value to see whether it counted towards totalCoveredAmount.
Installation warranty length. installerWarrantyDuration is a number of months.
Plan terms. Plans are quoted for 2, 3 and 5 years. Each warrantyQuoteItemList entry is one term.
Country. The endpoint prices for the United States only. An account with no United States Whole System Warranty set up gets status 512.
What makes a product eligible is described for installers on What a plan can cover.
Acting for an installer: Connect to SureBright#
A platform never holds an installer's API key. Each installer connects their SureBright account to your platform once, and you then create plans for them with your own key. The reference pages call this SureBright Connect.
The installer signs in and approves your platform
Send the installer to SureBright with the flow on Partner sign-in (OIDC). They sign in to SureBright and see a screen headed Connect to followed by your platform's name. Under Select locations they tick the locations you may act for. Under Permissions they see what you asked for. They finish with Allow and continue, or Cancel to decline.
The person who approves must be an owner or administrator of the installer's SureBright account.
Ask for the permission you need
To create and cancel plans you need the
sales.writescope. The installer sees it as "Record warranty sales for the authorized locations". Without it every create and cancel for that installer is refused.Store what you receive
sbAccountIdidentifies the connection between that installer and your platform. It is not a credential and it does not expire with the tokens.Create with your own key and the installer's ids
Quote with your own
storeIdas in step 1 of the flow. On create, add the two ids:bashcurl -X POST 'https://{HOST_NAME}/partner/api/v1/order/whole-system' \ -H 'X-SureBright-Access-Token: sb_live_YOUR_PLATFORM_KEY' \ -H 'Content-Type: application/json' \ -d '{ "storeId": "{yourPlatformStoreId}", "sbAccountId": "sb_int_{uuid}", "sbStoreId": "{locationId}", "sbProposalId": "{sbProposalId}", "warrantyQuoteId": "{warrantyQuoteId}", "warrantyQuoteItemId": "{warrantyQuoteItemId}", "warrantyCoverageYears": 3, "warrantyPrice": {priceChargedToTheCustomer}, "customerDetails": { "customerFirstName": "{firstName}", "customerLastName": "{lastName}", "customerEmail": "{email}" } }'sbStoreIdis always required on a connected create, including when the installer approved a single location.storeIdstays your own store id.
On a successful create, the proposal and its plan move into the installer's account, under the location you named. The plan appears in the installer's portal under Sold plans. After that:
Re-quote that proposal with
sbProposalId. A re-quote that carries onlypartnerProposalIddoes not find it and starts a new proposal.Keep sending the same
sbAccountIdandsbStoreIdwhen you update the plan. A proposal stays with the connection and location it was first created under.A proposal that already has a plan under your own account cannot be moved to an installer afterwards. Decide before the first create.
What makes a connected create fail#
The full list is on the create reference page.
Idempotency and duplicates#
A repeat create is safe. The create call takes no idempotency key. The proposal is what makes a repeat safe: if the proposal already has a plan, a second create with the same sbProposalId updates that plan with what you sent and returns the same contractId. It does not create a second plan. If a create times out, send it again unchanged. Send creates for one proposal one at a time, and wait for the response before you retry.
Keep partnerProposalId unique. A quote that reuses a partnerProposalId on the same storeId re-quotes the existing proposal. Reusing one reference for two different jobs overwrites the first job's quote. If you send both sbProposalId and partnerProposalId they must point at the same proposal, or the quote returns 409 with PROPOSAL_ID_MISMATCH.
SureBright does not match a plan you create through the API against a sale the installer records by hand. If the installer records a job in the installer portal and your platform also sends it, two plans are created for the same job and both are billed. Agree with each installer which route records the sale, and use only that route for a given job. See Choose how you sell.
Testing#
There is no separate test key. See Live keys and testing.
isTestOrder must be a boolean. Any other type is rejected with 400 and isTestOrder must be a boolean.
A plan created with isTestOrder: true is flagged as a test plan and its charge is waived. The customer email can still be sent, so put an address you control in customerEmail. Send the same isTestOrder value each time you call create for that proposal. For a connected installer, the plan keeps the value from its first create.
Errors#
These endpoints use their own codes. Read the body as well as the status: on create, most failures are HTTP 400 with the code in errorType.
On these endpoints 503, 504 and 505 on cancel and 511 to 516 on quote are application codes, not gateway errors. Each reference page lists every code with its exact message.
What the API does not do today#
Related#
Every request and response field of the quote call.
Fields and errors for create and update.
The two cancellation rules and every error.
The Connect to SureBright sign-in and consent flow.
Keys, the header and testing.
How installers sell the plan, with and without the API.