Create / Update Contracts for Whole System Warranty
Headers#
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#
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#
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
400witherrorType: 517and 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.
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:
The connection named by
sbAccountIdwas made with your application and is active.The installer granted the
sales.writescope, which allows you to create and cancel contracts for the locations they approved.sbStoreIdis one of the locations the installer approved, and that location is still active.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
sbAccountIdandsbStoreIdwhenever you update the contract;re-quote the proposal with
sbProposalId, not withpartnerProposalIdalone;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:
{ "isError": true, "errorType": 517, "message": "Line items cannot be updated after 90 days of purchase date" }Requests for a connected installer#
These bodies carry isError: true, a message and, where shown, a code.
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.
Related#
The whole flow for platforms and installers.
Price a whole-system plan for a proposal.
Cancel the contract this endpoint created.
How an installer connects to your platform.
https://api.surebright.com/partner/api/v1/order/whole-systemThis 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-TokenstringrequiredMerchant API key (sb_live_...) created on the Merchant Portal Developers page, or the integration-kit access token
Body
{
"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"
}
}