---
title: "Whole System Warranty API"
description: "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 installers | You are an installer connecting your own system |
|---|---|---|
| Whose plans you create | Each installer's, with that installer's approval | Your own |
| API key you send | Your platform's own key | Your own key |
| `storeId` you send | Your platform's SureBright store id | Your own SureBright store id |
| How SureBright knows the installer | `sbAccountId` and `sbStoreId`, which you receive when the installer connects | Not needed. Leave both out |
| Extra work | Build the Connect to SureBright sign-in once, then connect each installer | None |
| Where the plan is recorded | In the installer's account. They see it in the installer portal under **Sold plans** | In your own account |
| Cancelling by API | While the plan is active, subject to the checks in step 5 | Within 30 days of creating the plan |
| What to read | Every section | Skip [Acting for an installer](#acting-for-an-installer-connect-to-surebright) |

<Note>
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.
</Note>

## Before you start

| You need | Where it comes from |
|---|---|
| The API host (`HOST_NAME`), your `storeId` and an API key | [Authentication](/api-reference/authentication). If you do not have them, ask your SureBright contact |
| Whole System Warranty set up on your account | SureBright does this. Until it is done the quote call returns `512` or `514` |
| For platforms: a `client_id` for Connect to SureBright | SureBright registers your application. See [Partner sign-in (OIDC)](/api-reference/endpoint/partner/sso) |

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.

| Identifier | Who issues it | What it is for |
|---|---|---|
| `sbProposalId` | SureBright, in the first quote response | Ties the job together. Send it on every re-quote and on every create or update |
| `partnerProposalId` | You, on the quote request | Your 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 |
| `warrantyQuoteId` | SureBright, in each quote response | The quote you are buying from. Sent on create |
| `warrantyQuoteItemId` | SureBright, one per plan term | The term the customer chose. Sent on create |
| `contractId` | SureBright, in the create response | The 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

<Steps>
  <Step title="Quote from the proposal's line items">
    [For Whole System Warranty](/api-reference/endpoint/quote/list-warranty-quotes-for-whole-system): `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:

    | Field | Use |
    |---|---|
    | `sbProposalId` | The proposal. Store it. Sent in steps 2, 3 and 4 |
    | `warrantyQuoteId` | The 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` |
    | `totalCoveredAmount` | The total of the covered lines. The plan is priced on this figure |
    | `coverageList`, `tncLink` | Coverage wording and a link to the plan's documents, to show the customer |
  </Step>
  <Step title="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 sent | What comes back |
    |---|---|
    | The same lines and the same installation warranty length, and SureBright's pricing and coverage have not changed | The same `warrantyQuoteId` and `warrantyQuoteItemId` values as before |
    | Anything priced has changed: a line, a price, a quantity or the way a line is classified | New `warrantyQuoteId` and `warrantyQuoteItemId` values. Use these from now on. The earlier ids for that installation warranty length stop working |
    | A different installation warranty length | A 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.
  </Step>
  <Step title="Create the plan when the customer has bought">
    [Create / Update Contracts for Whole System Warranty](/api-reference/endpoint/order/create-contract-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"
        }
      }'
    ```

    | Field | Required | Notes |
    |---|---|---|
    | `storeId` | Yes | The same `storeId` you quoted with |
    | `sbProposalId` | Yes | From step 1 |
    | `warrantyQuoteId` | Yes | From the latest quote for the installation warranty length the installer is giving |
    | `warrantyQuoteItemId` | Yes | The term the customer chose |
    | `warrantyCoverageYears` | Yes | Must equal that term's `coverageYears` |
    | `warrantyPrice` | Yes | What the customer was charged for the plan. A number, zero or more |
    | `customerDetails` | Yes | `customerFirstName`, `customerLastName` and `customerEmail` are required. Send the address fields too: without `customerAddress1` the plan waits for the customer's address |
    | `isTestOrder` | No | `true` while you test. See [Testing](#testing) |
    | `sbAccountId`, `sbStoreId` | Platforms only | Both 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](/contracts/effective-dates).
  </Step>
  <Step title="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`.

    | Change | Allowed |
    |---|---|
    | The covered items | For 90 days from the day the plan was created. Updating the plan does not restart the 90 days |
    | The customer's details only | At 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.
  </Step>
  <Step title="Cancel the plan">
    [Cancel Contracts for Whole System Warranty](/api-reference/endpoint/order/cancel-contract-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 created | You can cancel | A refused cancellation looks like |
    |---|---|---|
    | With your own key, under your own account | Within 30 days of the plan's order being created. The plan must belong to the account that owns the key | `505` with `errorCode: CANCELLATION_WINDOW_EXPIRED` after 30 days. `503` with `CONTRACT_ACCESS_DENIED` for another account's plan |
    | For a connected installer, with `sbAccountId` | While 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 it | `400` 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.
  </Step>
  <Step title="Know what the customer and the installer see afterwards">
    There is no call in this step.

    | Who | What they see |
    |---|---|
    | The customer | SureBright 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](/installers/your-customer) |
    | A connected installer | The 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 key | The plan is recorded under the account that owns the key. Keep the `contractId`: there is no call that reads a plan back |
  </Step>
</Steps>

## How line items are judged

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

| What happens | In the response |
|---|---|
| A line is recognised as an eligible product | `isCovered: true` and its `sbCategoryName` |
| A line is not recognised, or is not eligible | `isCovered: false` and an empty `sbCategoryName` |
| The covered lines are added up | `totalCoveredAmount`: `unitPrice` times `quantity` across the covered lines only |
| No line is covered | No quote. Status `516` with `Category Not Found` |
| The covered lines add up to zero | No 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 send | Result |
|---|---|
| `3`, `6` or `12` | Priced on that length |
| Any other value above `3` | Priced on the nearest length below it. `9` is priced as `6`, and `24` as `12` |
| Less than `3` | No quote. Status `513` with `No Quote Found` |
| Nothing | Status `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](/installers/eligibility).

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

<Steps>
  <Step title="The installer signs in and approves your platform">
    Send the installer to SureBright with the flow on [Partner sign-in (OIDC)](/api-reference/endpoint/partner/sso). 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.
  </Step>
  <Step title="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.
  </Step>
  <Step title="Store what you receive">
    | You receive | Format | Send it as |
    |---|---|---|
    | `sbAccountId` | `sb_int_` followed by a UUID, for example `sb_int_3f9d2c7b-1a4e-4b6d-9c0f-5e8a7d6b2c10` | `sbAccountId` |
    | `locations[]`, one entry per approved location, each with a `locationId`, `name` and `address` | `locationId` is an opaque string | The `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.
  </Step>
  <Step title="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.
  </Step>
</Steps>

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

| Cause | Status and body | What to do |
|---|---|---|
| `sbStoreId` is missing | `400`, `sbStoreId is required` | Send the `locationId` of the location that made the sale |
| The connection is not active, or it was not made with your application | `401`, `code: invalid_api_key`, `Partner authentication failed` | Ask the installer to connect again |
| The installer did not grant `sales.write` | `403`, `code: insufficient_scope`, `The sales.write scope is required` | Request `sales.write` and ask the installer to approve again |
| `sbStoreId` is not a location the installer approved | `403`, `code: access_denied`, `The selected location is not authorized` | Use a `locationId` from the `locations` you received, or ask the installer to approve the location |
| The location has since been closed or deactivated | `403`, `code: access_denied`, `The selected location is not active` | Ask the installer which location to use |
| The person who approved is no longer an active owner or administrator of the installer's account | `403`, `code: access_denied`, `The merchant authorization is no longer active` | Ask a current owner or administrator to connect again |
| `storeId` is not your own store id | `403`, `code: access_denied`, `The supplied storeId does not belong to the authenticated partner` | Send your platform's `storeId` |
| The proposal was not quoted with your `storeId` | `403`, `Proposal does not belong to the authenticated partner account` | Quote with your own `storeId` first |
| The proposal already belongs to another connection or location | `403`, `Proposal is not available to this connection` | Send the `sbAccountId` and `sbStoreId` it was first created with |

The full list is on the [create reference page](/api-reference/endpoint/order/create-contract-whole-system-warranty).

## 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`.

<Warning>
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](/installers/ways-to-sell).
</Warning>

## Testing

There is no separate test key. See [Live keys and testing](/api-reference/authentication#live-keys-and-testing).

| You want to | What to do |
|---|---|
| Check your line items and see real prices without creating anything | Call the quote endpoint. It creates a proposal, not a plan |
| Try create without recording a real sale | Send `"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`.

| Call | Status | Code in the body | Meaning | What to do |
|---|---|---|---|---|
| Quote | `511` | | `storeId`, `lineItemList` or `installerWarrantyDuration` is missing | Send all three |
| Quote | `512` | | The account is not set up for Whole System Warranty in the United States | Ask your SureBright contact |
| Quote | `513` | | No quote: `installerWarrantyDuration` is below `3`, a line has no `title`, or no plan matched | Check the installation warranty length and the lines |
| Quote | `514` | | `storeId` is not known | Check the `storeId` |
| Quote | `515`, `516` | | No covered line, or the covered lines total zero | See [How line items are judged](#how-line-items-are-judged) |
| Quote | `404` | `SB_PROPOSAL_NOT_FOUND` | `sbProposalId` is not known | Quote without it to start a new proposal |
| Quote | `409` | `PROPOSAL_ID_MISMATCH` | `sbProposalId` and `partnerProposalId` point at different proposals | Send the pair that belongs together |
| Quote | `409` | `PARTNER_PROPOSAL_RESERVED` | A plan is being created from this proposal right now | Retry once the create has finished |
| Quote | `403` | `PARTNER_PROPOSAL_ACCESS_DENIED` | The proposal has moved to a connected installer, and the `storeId` you sent is not the one it was created with | Quote with the `storeId` you created the plan with |
| Quote | `502` | `QUOTE_PERSISTENCE_FAILED` | The quote could not be saved | Quote again before you create |
| Create | `400` | `errorType: 512` | A required field is missing or malformed. `errors` lists each one | Fix the fields listed |
| Create | `400` | `errorType: 515` | The proposal was not found on that `storeId` | Check `sbProposalId` and `storeId`. For a connected installer's proposal, send `sbAccountId` and `sbStoreId` |
| Create | `400` | `errorType: 518`, `519`, `520` | The quote, the term or `warrantyCoverageYears` does not match the proposal's latest quote | Re-quote and send the ids from that response |
| Create | `400` | `errorType: 517` | The covered items cannot change after 90 days | Nothing changed. Ask your SureBright contact |
| Create | `401`, `403` | `invalid_api_key`, `insufficient_scope`, `access_denied` | A connected create was not authorised | See [What makes a connected create fail](#what-makes-a-connected-create-fail) |
| Create | `409` | | `Proposal changed. Reload the quote before submitting.` or `Contract creation is still in progress` | Re-quote, or wait, then retry |
| Cancel | `505` | `CANCELLATION_WINDOW_EXPIRED` | More than 30 days since the plan's order was created | Ask your SureBright contact |
| Cancel | `503`, `504` | `CONTRACT_ACCESS_DENIED`, `CONTRACT_NOT_FOUND` | The plan is not yours, or the `contractId` is not known | Check the `contractId` and the key |
| Cancel | `403` | | `Store integration is inactive`: the installer has disconnected | Ask the installer to connect again, or to cancel in their portal |
| Cancel | `400` | | A connected plan could not be cancelled: an active claim, no refund due, or already cancelled. `message` says which | Read `message` |
| Any | `401` | | `X-SureBright-Access-Token header is required`, or the key was not accepted | See [Authentication](/api-reference/authentication) |
| Any | `500`, `502`, `503` | | SureBright could not complete the request | Retry. 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 available | What to do instead |
|---|---|
| Filing or reading a claim | The 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](/installers/claims) |
| Push notifications | SureBright does not send plan or claim events to your systems. See [Notifications and webhooks](/api-reference/notifications-and-webhooks) |
| Reading a plan back, or listing plans | There 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 plan | Cancel ends the whole plan. Change the covered items with step 4 |

## Related

<CardGroup cols={2}>
  <Card title="Whole-system quotes" href="/api-reference/endpoint/quote/list-warranty-quotes-for-whole-system" icon="layers">
    Every request and response field of the quote call.
  </Card>
  <Card title="Create or update contracts" href="/api-reference/endpoint/order/create-contract-whole-system-warranty" icon="file-text">
    Fields and errors for create and update.
  </Card>
  <Card title="Cancel contracts" href="/api-reference/endpoint/order/cancel-contract-whole-system-warranty" icon="settings">
    The two cancellation rules and every error.
  </Card>
  <Card title="Partner sign-in (OIDC)" href="/api-reference/endpoint/partner/sso" icon="plug">
    The Connect to SureBright sign-in and consent flow.
  </Card>
  <Card title="Authentication" href="/api-reference/authentication" icon="shield">
    Keys, the header and testing.
  </Card>
  <Card title="Choose how you sell" href="/installers/ways-to-sell" icon="book">
    How installers sell the plan, with and without the API.
  </Card>
</CardGroup>
