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#

You run a proposal or quoting platform used by many installersYou are an installer connecting your own system
Whose plans you createEach installer's, with that installer's approvalYour own
API key you sendYour platform's own keyYour own key
storeId you sendYour platform's SureBright store idYour own SureBright store id
How SureBright knows the installersbAccountId and sbStoreId, which you receive when the installer connectsNot needed. Leave both out
Extra workBuild the Connect to SureBright sign-in once, then connect each installerNone
Where the plan is recordedIn the installer's account. They see it in the installer portal under Sold plansIn your own account
Cancelling by APIWhile the plan is active, subject to the checks in step 5Within 30 days of creating the plan
What to readEvery sectionSkip Acting for an installer

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#

You needWhere it comes from
The API host (HOST_NAME), your storeId and an API keyAuthentication. If you do not have them, ask your SureBright contact
Whole System Warranty set up on your accountSureBright does this. Until it is done the quote call returns 512 or 514
For platforms: a client_id for Connect to SureBrightSureBright registers your application. See Partner sign-in (OIDC)

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.

IdentifierWho issues itWhat it is for
sbProposalIdSureBright, in the first quote responseTies the job together. Send it on every re-quote and on every create or update
partnerProposalIdYou, on the quote requestYour own proposal reference. Optional. It must be unique to one proposal on your storeId, because a quote that reuses it updates that proposal instead of starting a new one
warrantyQuoteIdSureBright, in each quote responseThe quote you are buying from. Sent on create
warrantyQuoteItemIdSureBright, one per plan termThe term the customer chose. Sent on create
contractIdSureBright, in the create responseThe plan. Send it to cancel, and quote it to SureBright support

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#

  1. Quote from the proposal's line items

    For Whole System Warranty: POST /quote/api/whole-system/listQuotes

    Send every line on the proposal and the length of the installation warranty the installer gives, in months. Leave sbProposalId out of the first request.

    bash
    curl -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, lineItemList and installerWarrantyDuration are required. Each line needs title, unitPrice and quantity. description and categoryTag are optional and help SureBright recognise the product.

    From the response keep:

    FieldUse
    sbProposalIdThe proposal. Store it. Sent in steps 2, 3 and 4
    warrantyQuoteIdThe quote. Sent in step 3
    warrantyQuoteItemList[]One entry per plan term. warrantyQuoteItemId and coverageYears are sent in step 3. quotePrice is the suggested customer price. planCost, when present, is what SureBright charges you for that plan
    lineItemList[]Your lines back, each with isCovered and sbCategoryName
    totalCoveredAmountThe total of the covered lines. The plan is priced on this figure
    coverageList, tncLinkCoverage wording and a link to the plan's documents, to show the customer
  2. Re-quote when the proposal changes

    Same endpoint. Send the proposal's current lines and installation warranty length again, this time with sbProposalId.

    bash
    curl -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 }
        ]
      }'
    What you sentWhat comes back
    The same lines and the same installation warranty length, and SureBright's pricing and coverage have not changedThe same warrantyQuoteId and warrantyQuoteItemId values as before
    Anything priced has changed: a line, a price, a quantity or the way a line is classifiedNew warrantyQuoteId and warrantyQuoteItemId values. Use these from now on. The earlier ids for that installation warranty length stop working
    A different installation warranty lengthA new quote for that length. The proposal keeps one quote per length, and the warrantyQuoteId you send in step 3 decides which one applies

    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.

  3. Create the plan when the customer has bought

    Create / Update Contracts for Whole System Warranty: POST /partner/api/v1/order/whole-system

    Call 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.

    bash
    curl -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"
        }
      }'
    FieldRequiredNotes
    storeIdYesThe same storeId you quoted with
    sbProposalIdYesFrom step 1
    warrantyQuoteIdYesFrom the latest quote for the installation warranty length the installer is giving
    warrantyQuoteItemIdYesThe term the customer chose
    warrantyCoverageYearsYesMust equal that term's coverageYears
    warrantyPriceYesWhat the customer was charged for the plan. A number, zero or more
    customerDetailsYescustomerFirstName, customerLastName and customerEmail are required. Send the address fields too: without customerAddress1 the plan waits for the customer's address
    isTestOrderNotrue while you test. See Testing
    sbAccountId, sbStoreIdPlatforms onlyBoth are required when you create for a connected installer

    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 200 response carries isError: false and the plan's contractId. 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.

  4. Change the covered items after the sale

    This takes two calls. First re-quote as in step 2, with the same sbProposalId and the lines as they stand now. Then send step 3 again with the same sbProposalId and the new warrantyQuoteId and warrantyQuoteItemId. Because the proposal already has a plan, the call updates that plan and returns the same contractId.

    ChangeAllowed
    The covered itemsFor 90 days from the day the plan was created. Updating the plan does not restart the 90 days
    The customer's details onlyAt any time

    After the 90 days, a call that would change the covered items returns HTTP 400 with errorType: 517 and the message Line items cannot be updated after 90 days of purchase date. Nothing on the plan changes.

  5. Cancel the plan

    Cancel Contracts for Whole System Warranty: POST /partner/api/v1/order/whole-system/cancel

    bash
    curl -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:

    The plan was createdYou can cancelA refused cancellation looks like
    With your own key, under your own accountWithin 30 days of the plan's order being created. The plan must belong to the account that owns the key505 with errorCode: CANCELLATION_WINDOW_EXPIRED after 30 days. 503 with CONTRACT_ACCESS_DENIED for another account's plan
    For a connected installer, with sbAccountIdWhile the plan is active and the installer's connection is active. There is no 30-day limit. The call is refused while the plan has an active claim, or when no refund is due on it400 with isError: true and a message. 403 with Store integration is inactive when the installer has disconnected

    A successful response is 200 with isError: false and cancelledContractId. Check isError on every 200, because a plan that was already cancelled is also answered with 200. Cancelling ends cover for every line on the plan. You cannot cancel one product; change the covered items with step 4 instead. cancellationReason is 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.

  6. Know what the customer and the installer see afterwards

    There is no call in this step.

    WhoWhat they see
    The customerSureBright emails the customer at customerEmail to confirm the plan, and normally again if it is cancelled. Claims are filed by the customer with SureBright, or by the installer for them. See What your customer gets
    A connected installerThe plan appears in their installer portal under Sold plans, like a sale they recorded themselves. From there they can open it and file a claim for the customer
    You, with your own keyThe plan is recorded under the account that owns the key. Keep the contractId: there is no call that reads a plan back

How line items are judged#

SureBright assesses every line you send for eligibility. Only eligible lines are priced.

What happensIn the response
A line is recognised as an eligible productisCovered: true and its sbCategoryName
A line is not recognised, or is not eligibleisCovered: false and an empty sbCategoryName
The covered lines are added uptotalCoveredAmount: unitPrice times quantity across the covered lines only
No line is coveredNo quote. Status 516 with Category Not Found
The covered lines add up to zeroNo quote. Status 515 with Not Eligible

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.

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, and 24 as 12
Less than 3No quote. Status 513 with No Quote Found
NothingStatus 511 with installerWarrantyDuration is required

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.

  1. 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.

  2. Ask for the permission you need

    To create and cancel plans you need the sales.write scope. The installer sees it as "Record warranty sales for the authorized locations". Without it every create and cancel for that installer is refused.

  3. Store what you receive

    You receiveFormatSend it as
    sbAccountIdsb_int_ followed by a UUID, for example sb_int_3f9d2c7b-1a4e-4b6d-9c0f-5e8a7d6b2c10sbAccountId
    locations[], one entry per approved location, each with a locationId, name and addresslocationId is an opaque stringThe locationId of the location that made the sale, as sbStoreId

    sbAccountId identifies the connection between that installer and your platform. It is not a credential and it does not expire with the tokens.

  4. Create with your own key and the installer's ids

    Quote with your own storeId as in step 1 of the flow. On create, add the two ids:

    bash
    curl -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}"
        }
      }'

    sbStoreId is always required on a connected create, including when the installer approved a single location. storeId stays 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 only partnerProposalId does not find it and starts a new proposal.

  • Keep sending the same sbAccountId and sbStoreId when 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#

CauseStatus and bodyWhat to do
sbStoreId is missing400, sbStoreId is requiredSend the locationId of the location that made the sale
The connection is not active, or it was not made with your application401, code: invalid_api_key, Partner authentication failedAsk the installer to connect again
The installer did not grant sales.write403, code: insufficient_scope, The sales.write scope is requiredRequest sales.write and ask the installer to approve again
sbStoreId is not a location the installer approved403, code: access_denied, The selected location is not authorizedUse a locationId from the locations you received, or ask the installer to approve the location
The location has since been closed or deactivated403, code: access_denied, The selected location is not activeAsk the installer which location to use
The person who approved is no longer an active owner or administrator of the installer's account403, code: access_denied, The merchant authorization is no longer activeAsk a current owner or administrator to connect again
storeId is not your own store id403, code: access_denied, The supplied storeId does not belong to the authenticated partnerSend your platform's storeId
The proposal was not quoted with your storeId403, Proposal does not belong to the authenticated partner accountQuote with your own storeId first
The proposal already belongs to another connection or location403, Proposal is not available to this connectionSend the sbAccountId and sbStoreId it was first created with

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.

You want toWhat to do
Check your line items and see real prices without creating anythingCall the quote endpoint. It creates a proposal, not a plan
Try create without recording a real saleSend "isTestOrder": true in the create body

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.

CallStatusCode in the bodyMeaningWhat to do
Quote511storeId, lineItemList or installerWarrantyDuration is missingSend all three
Quote512The account is not set up for Whole System Warranty in the United StatesAsk your SureBright contact
Quote513No quote: installerWarrantyDuration is below 3, a line has no title, or no plan matchedCheck the installation warranty length and the lines
Quote514storeId is not knownCheck the storeId
Quote515, 516No covered line, or the covered lines total zeroSee How line items are judged
Quote404SB_PROPOSAL_NOT_FOUNDsbProposalId is not knownQuote without it to start a new proposal
Quote409PROPOSAL_ID_MISMATCHsbProposalId and partnerProposalId point at different proposalsSend the pair that belongs together
Quote409PARTNER_PROPOSAL_RESERVEDA plan is being created from this proposal right nowRetry once the create has finished
Quote403PARTNER_PROPOSAL_ACCESS_DENIEDThe proposal has moved to a connected installer, and the storeId you sent is not the one it was created withQuote with the storeId you created the plan with
Quote502QUOTE_PERSISTENCE_FAILEDThe quote could not be savedQuote again before you create
Create400errorType: 512A required field is missing or malformed. errors lists each oneFix the fields listed
Create400errorType: 515The proposal was not found on that storeIdCheck sbProposalId and storeId. For a connected installer's proposal, send sbAccountId and sbStoreId
Create400errorType: 518, 519, 520The quote, the term or warrantyCoverageYears does not match the proposal's latest quoteRe-quote and send the ids from that response
Create400errorType: 517The covered items cannot change after 90 daysNothing changed. Ask your SureBright contact
Create401, 403invalid_api_key, insufficient_scope, access_deniedA connected create was not authorisedSee What makes a connected create fail
Create409Proposal changed. Reload the quote before submitting. or Contract creation is still in progressRe-quote, or wait, then retry
Cancel505CANCELLATION_WINDOW_EXPIREDMore than 30 days since the plan's order was createdAsk your SureBright contact
Cancel503, 504CONTRACT_ACCESS_DENIED, CONTRACT_NOT_FOUNDThe plan is not yours, or the contractId is not knownCheck the contractId and the key
Cancel403Store integration is inactive: the installer has disconnectedAsk the installer to connect again, or to cancel in their portal
Cancel400A connected plan could not be cancelled: an active claim, no refund due, or already cancelled. message says whichRead message
Any401X-SureBright-Access-Token header is required, or the key was not acceptedSee Authentication
Any500, 502, 503SureBright could not complete the requestRetry. A repeated create is safe

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#

Not availableWhat to do instead
Filing or reading a claimThe API has no claim endpoints. The customer files with SureBright, or the installer files for them from the plan in the installer portal. See Claims on a system you installed
Push notificationsSureBright does not send plan or claim events to your systems. See Notifications and webhooks
Reading a plan back, or listing plansThere is no lookup call for whole-system plans. Store the contractId from the create response. A connected installer sees their plans under Sold plans
Cancelling part of a planCancel ends the whole plan. Change the covered items with step 4