Create / Update Contracts for Whole System Warranty

Headers#

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

Overview#

This endpoint creates or updates a warranty contract for a whole system order. It is used after obtaining warranty quotes from the List Quotes for Whole System Warranty endpoint. One proposal has at most one contract, and that contract covers every eligible line on the proposal.

For the whole flow, read the Whole System Warranty guide.

Flow#

  1. Call the List Quotes for Whole System Warranty endpoint to get available warranty plans for your proposal.

  2. Select the desired plan from the returned warrantyQuoteItemList.

  3. Submit sbProposalId, the selected warranty details, and customer information to this endpoint. The covered line items, total covered amount, and installer warranty duration come from the proposal.

Request Details#

FieldRequiredNotes
storeIdYesYour SureBright store id. The proposal must belong to it
sbProposalIdYesThe SureBright proposal ID returned by the List Quotes API. A non-empty string of at most 200 characters
warrantyQuoteIdYesThe quote ID returned by the List Quotes API. It must be a quote that is still on the proposal
warrantyQuoteItemIdYesThe ID of the selected plan within that quote
warrantyCoverageYearsYesMust equal the selected plan's coverageYears
warrantyPriceYesThe price the customer was charged for the plan. A number, zero or more. Your margin is this price less the plan's planCost from the quote
customerDetails.customerFirstNameYes
customerDetails.customerLastNameYes
customerDetails.customerEmailYesThe plan confirmation is sent here
customerDetails.customerPhone, customerAddress1, customerAddress2, customerCity, customerState, customerZipCode, customerCountryNoSend the address. A contract created without customerAddress1 waits for the customer's address. See Why a contract is on hold
isTestOrderNoBoolean. true records a test contract. See Test orders
sbAccountIdConnected platformsThe connected installer's account id. See Creating for a connected installer
sbStoreIdConnected platformsThe installer's location. Always required with sbAccountId
partnerIdNoFor platforms: your client_id. When sent, SureBright takes your store from it, and a storeId sent with it must be that same store

Provide sbProposalId and use the quote and plan IDs from the same quote response.

sbProposalId is required to identify the proposal whose covered products will be used for the contract, subject to the backward-compatibility exception below. Obtain this ID from the List Quotes for Whole System Warranty endpoint. Do not send lineItemList; any supplied value is ignored.

How the contract is dated#

The contract's purchase date is the day you create it. You do not send a date. Cover begins on that purchase date and runs to the end of the term. For a breakdown, the manufacturer warranty and the installer's installation warranty apply first. Create the contract when the customer has bought and the installation is complete. See When coverage starts.

Updating existing contracts#

If a contract already exists for the provided proposal, calling this endpoint updates that contract and returns the same contractId. It never creates a second contract for the proposal, so repeating a request that timed out is safe.

  • Covered line items can be updated within 90 days of the contract's purchase date, the day it was first created. Updating the contract does not restart this window.

  • After the window, a request that would change the covered line items returns HTTP 400 with errorType: 517 and nothing changes.

  • Customer details can still be updated after this window, subject to the usual request validations.

To change covered products, first request updated quotes for the same proposal, then submit the selected quote and plan details to this endpoint.

Test orders#

Send "isTestOrder": true to try the call without recording a real sale. The value must be a boolean; anything else returns 400 with isTestOrder must be a boolean. The contract is flagged as a test contract and its charge is waived. The customer email can still be sent, so use an address you control in customerEmail. There is no separate test key; see Live keys and testing.

Creating for a connected installer#

A platform that sells on behalf of installers does not use the installer's key. The installer connects to the platform once through Partner sign-in (OIDC), and the platform then calls this endpoint with its own key and two extra fields. Direct integrations leave both out.

FieldValue
sbAccountIdThe id returned to you when the installer connected. Its format is sb_int_ followed by a UUID, for example sb_int_3f9d2c7b-1a4e-4b6d-9c0f-5e8a7d6b2c10. At most 200 characters
sbStoreIdThe locationId of the installer's location that made the sale, taken from the locations you received. Always required, including when the installer approved one location only
storeIdStill your own store id, the one you quoted with
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}"
    }
  }'

A connected request succeeds only while all of these are true:

  1. The connection named by sbAccountId was made with your application and is active.

  2. The installer granted the sales.write scope, which allows you to create and cancel contracts for the locations they approved.

  3. sbStoreId is one of the locations the installer approved, and that location is still active.

  4. The person who approved the connection is still an active owner or administrator of the installer's account.

On success the proposal and its contract move into the installer's account under that location, and the contract appears in the installer's portal under Sold plans. From then on:

  • send the same sbAccountId and sbStoreId whenever you update the contract;

  • re-quote the proposal with sbProposalId, not with partnerProposalId alone;

  • an update keeps the contract's original purchase date and its test flag.

A proposal that already has a contract under your own account cannot be moved to an installer afterwards.

Backward compatibility: Existing integrations can provide sbSalesLeadId instead of sbProposalId when creating or updating contracts. If both are supplied, their values must match; otherwise, this endpoint returns HTTP 400 with errorType: 512. For new integrations, use sbProposalId.

Response#

On success (200), you will receive:

  • isError - false.

  • contractId - The unique identifier for the warranty contract created or updated. Store it: you need it to cancel, and there is no call that reads a whole-system contract back.

Errors#

Requests with your own key#

A failed check returns HTTP 400. The code is in the errorType field of the body, not in the HTTP status:

json
{ "isError": true, "errorType": 517, "message": "Line items cannot be updated after 90 days of purchase date" }
HTTP statuserrorTypemessageCheck that failed
400512Validation Failed for Input ParametersA required field is missing or malformed. The errors array names each one, for example warrantyPrice is required, customerEmail is required or isTestOrder must be a boolean
400513No Quote FoundThe selected quote no longer exists. Request quotes again
400514Store Not FoundstoreId is not a store set up for Whole System Warranty
400515Sales Lead Not FoundNo proposal has that sbProposalId on that storeId, or the proposal now belongs to a connected installer and the request did not carry sbAccountId and sbStoreId
400516Contract not foundThe proposal's existing contract could not be found when updating it
400517Line items cannot be updated after 90 days of purchase dateCovered line items changed after the 90-day window
400518Quote ID mismatchwarrantyQuoteId is not a quote on this proposal, for example because the proposal was re-quoted since
400519Quote item not foundwarrantyQuoteItemId is not a plan within the selected quote
400520Warranty coverage years do not match quote itemwarrantyCoverageYears differs from the selected plan's coverageYears
400 or 500500Something Unexpectedly Went WrongUnexpected failure. Send the request again; a repeat does not create a second contract
401401X-SureBright-Access-Token header is requiredThe key is missing. A key that is not valid returns the bodies listed on Authentication
403API credential does not belong to this partnerpartnerId was sent with a key that does not belong to that application
502502Unable to reach the target serviceSureBright could not complete the request. Send it again

Requests for a connected installer#

These bodies carry isError: true, a message and, where shown, a code.

HTTP statuscodemessageCause and what to do
400sbAccountId must be a non-empty identifiersbAccountId is empty, not a string or over 200 characters
400invalid_requestsbStoreId is requiredSend the installer's locationId as sbStoreId
400sbStoreId is only supported for a SureBright Connect accountsbAccountId is not an id returned by the installer's connection. Send the sbAccountId you received when the installer connected
400Use sbAccountId instead of merchantStoreIdmerchantStoreId is not accepted on this endpoint
401invalid_api_keyPartner authentication failedThe connection is not active, or it was not made with your application. Ask the installer to connect again
403insufficient_scopeThe sales.write scope is requiredThe installer did not grant sales.write. Request it and ask the installer to approve again
403access_deniedThe selected location is not authorizedsbStoreId is not a location the installer approved
403access_deniedThe selected location is not activeThe location has been closed or deactivated
403access_deniedThe merchant authorization is no longer activeThe person who approved is no longer an active owner or administrator. Ask a current owner or administrator to connect again
403access_deniedThe supplied storeId does not belong to the authenticated partnerstoreId must be your own store id
403Proposal does not belong to the authenticated partner accountThe proposal was not quoted with your storeId
403Proposal is not available to this connectionThe proposal already belongs to a different connection or location
400Sales Lead Not FoundNo proposal has that sbProposalId
409sbProposalId and sbSalesLeadId must identify the same proposalBoth were sent with different values. Send sbProposalId only
400PARTNER_QUOTE_SELECTION_INVALIDThe selected quote does not belong to this proposal or warrantyCoverageYears does not match the selected quoteRe-quote and send the IDs and term from that response
409PARTNER_QUOTE_SELECTION_INVALIDwarrantyPrice must be a non-negative numberFix warrantyPrice
400CUSTOMER_DETAILS_REQUIREDCustomer name and email are requiredSend the three required customerDetails fields
400Validation Failed for Input ParameterswarrantyPrice, warrantyCoverageYears or a required customerDetails field is missing
400isTestOrder must be a booleanSend true or false, or leave it out
400The selected quote has no covered productsNo line on the selected quote is covered
400INVALID_COVERED_LINE_ITEMSA message that covered items need a price and quantity above zeroCovered lines need a price and a quantity greater than zero, and product quantities must be whole numbers. Re-quote with corrected lines
400restrictionType: PRODUCT_ELIGIBILITY_BLACKLIST with an ineligibleItemListA line is a product SureBright does not accept. Remove it and re-quote
409Partner quote and merchant account currencies must matchThe proposal was quoted in a different currency from the installer's account
409A contracted proposal cannot be transferredThe proposal already has a contract under your own account
409Proposal changed. Reload the quote before submitting.The proposal was re-quoted while the request was in flight. Re-quote and send the request again
409Contract creation is still in progressAn earlier create for this proposal has not finished. Wait and send the request again
410PROPOSAL_EXPIRED or PROPOSAL_DELETEDThe proposal can no longer be sold. Quote the job again as a new proposal
502Unable to reach the target serviceSend the request again
503Merchant authorization is unavailable, or a code of PARTNER_LOOKUP_UNAVAILABLESureBright could not check the connection. Send the request again

An update of a contract that already exists for a connected installer returns the errorType codes 512 to 520 from the first table, with HTTP 400.

POSThttps://api.surebright.com/partner/api/v1/order/whole-system

This endpoint creates or updates a warranty contract for a whole system proposal. Provide sbProposalId, the selected warranty quote and plan details, and customer information. The covered line items, total covered amount, and installer warranty duration come from the proposal. If a contract already exists for the proposal, it is updated. Covered line items can be updated within 90 days from the original sale date; updates do not restart this window. Customer details and other non-line item fields can still be updated afterward, subject to the usual request validations.

Backward compatibility: Existing integrations can provide sbSalesLeadId instead of sbProposalId. If both are supplied, their values must match; otherwise, the endpoint returns HTTP 400 with errorType 512. For new integrations, use sbProposalId.

Authorizations

X-SureBright-Access-Tokenstringrequired

Merchant API key (sb_live_...) created on the Merchant Portal Developers page, or the integration-kit access token

Body

application/json
json
{
  "storeId": "test-store-id",
  "warrantyQuoteId": "36eaa6e3-ca1f-4bc1-86da-76caf7a7114d",
  "warrantyQuoteItemId": "a7defcbd-aa07-4e01-9076-c1935af20a98",
  "sbProposalId": "da5747e7-a60d-4625-a91d-ea2728ecf589",
  "warrantyPrice": 40,
  "warrantyCoverageYears": 2,
  "customerDetails": {
    "customerEmail": "john.doe@example.com",
    "customerPhone": "+1 (615) 555-0123",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "customerAddress1": "1234 Tulip Grove Rd",
    "customerAddress2": "Suite 100",
    "customerCity": "Nashville",
    "customerState": "TN",
    "customerCountry": "USA",
    "customerZipCode": "37076",
    "addressType": "BILLING"
  }
}