Create / Update Contracts for Whole System Warranty

Headers#

Header	Description	Required
X-SureBright-Access-Token	Access token for authentication	Yes
Content-Type	application/json	Yes

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.

Flow#

Call the List Quotes for Whole System Warranty endpoint to get available warranty plans for your proposal.
Select the desired plan from the returned warrantyQuoteItemList.
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#

sbProposalId - The SureBright proposal ID returned by the List Quotes API. The proposal must belong to the supplied storeId.
warrantyQuoteId - The quote ID returned by the List Quotes API.
warrantyQuoteItemId - The ID of the selected plan within that quote.

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.

Updating Existing Contracts

If a contract already exists for the provided proposal, calling this endpoint updates that contract:

Covered line items can be updated within 90 days from the original sale date. Updating the contract does not restart this window.
Customer details and other non-line item fields 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.

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.

Validations#

The endpoint checks the proposal, store, selected plan, and contract update window. Failed checks return the following errors:

Check	Error
`sbProposalId` is provided and valid (see the backward-compatibility note for existing integrations)	`512` Validation Failed for Input Parameters
The proposal exists and belongs to the supplied `storeId`	`515` Sales Lead Not Found
`warrantyQuoteId` matches the quote associated with the proposal	`518` Quote ID Mismatch
The selected quote exists	`513` No Quote Found
The supplied `storeId` identifies an existing store	`514` Store Not Found
`warrantyQuoteItemId` identifies a plan within the selected quote	`519` Quote Item Not Found
`warrantyCoverageYears` matches the selected plan's `coverageYears`	`520` Warranty Coverage Years Mismatch
The existing contract associated with the proposal can be found when updating it	`516` Contract Not Found
Covered line-item changes are within 90 days from the original sale date	`517` Line Items Update Not Allowed

Response#

On success, you will receive:

contractId - The unique identifier for the warranty contract created or updated.

POSThttps://{HOST_NAME}/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

Access token for authentication

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"
  }
}

PreviousCancel Contracts for Whole System Warranty Next HTTP Status Codes