Cancel Contracts for Whole System Warranty
POST https://{HOST_NAME}/partner/api/v1/order/whole-system/cancel?contractId={contractId}
Use this endpoint to cancel a whole-system contract, the one created by Create / Update Contracts for Whole System Warranty. You identify it by the contractId that call returned.
Contracts created through POST /partner/api/v1/order are not cancelled here. Cancel those by lowering the line's quantity with Cancel / Update contracts for Order.
Headers#
Overview#
This endpoint cancels the warranty contract for a whole system order. It takes the contract ID and, optionally, a reason.
You send the same request for every contract. Which rule applies depends on how the contract was created:
For the second case see Creating for a connected installer.
Request#
No other body is needed. The contract ID goes in the query string, not in the body. A platform does not send sbAccountId or sbStoreId here: the contract already records which installer and location it belongs to.
Example request#
curl -X POST 'https://{HOST_NAME}/partner/api/v1/order/whole-system/cancel?contractId={contractId}' \
-H 'Accept: application/json' \
-H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY'Example response#
200:
{
"isError": false,
"cancelledContractId": "5233a92bfcc04a77920abfa1fe52194a"
}Errors#
Contracts created with your own key#
Errors raised before the cancellation is attempted have this shape, with errorType equal to the HTTP status:
{ "isError": true, "errorType": 505, "errorCode": "CANCELLATION_WINDOW_EXPIRED", "message": "Contract can be cancelled only within 30 days from order creation date" }503, 504 and 505 are application codes on this endpoint, not gateway errors. Read the errorCode in the body before you retry: only 502 and 500 are worth retrying unchanged.
Contracts created for a connected installer#
These bodies carry isError: true, a message and, where shown, a code. The 505 window error does not apply to these contracts.
A successful cancellation of a connected installer's contract returns the same 200 body as above, with isError: false and cancelledContractId.
Behaviour notes#
One contract covers the whole system. A whole-system sale is a single contract that covers every line item on the proposal. There are no separate per-product contracts to cancel, so cancelling the contract ends cover for all of its line items at once.
No partial cancellation. You cannot cancel one covered product here. To change which products are covered, update the contract through Create / Update Contracts for Whole System Warranty, within the limits described on that page.
The 30-day window applies to contracts created with your own key. It is counted from the date and time the contract's order was created, which for a whole-system contract is when you first created it. After that the request returns
505. Contracts created for a connected installer have no 30-day window.Cancelling twice is harmless. The second call returns
200withisError: trueandContract already cancelled, or400withContract has already been cancelledfor a connected installer's contract.The customer is told. SureBright normally emails the customer a cancellation confirmation.
Related#
The whole flow for platforms and installers.
Create the contract, or change its covered products.
Price a whole-system plan for a proposal.
Cancel ordinary order contracts.
Credentials and rules shared by the Order endpoints.
https://api.surebright.com/partner/api/v1/order/whole-system/cancelThis endpoint cancels an existing warranty contract for a whole system order. Provide the contract ID obtained from the Create Contracts for Whole System Warranty endpoint. The API returns the cancellation status of the warranty contract.
Authorizations
X-SureBright-Access-TokenstringrequiredAccess token for authentication
Query parameters
contractIdstringrequiredThe unique identifier for the warranty contract to be cancelled
5233a92bfcc04a77920abfa1fe52194a