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#

HeaderDescriptionRequired
X-SureBright-Access-TokenAccess token for authenticationYes

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:

The contract was createdWhen you can cancel itWho can cancel it
With your own key, under your own accountWithin 30 days of the date its order was created. After that the request returns 505The account that owns the contract. Another account's key gets 503
By a platform for a connected installer, with sbAccountIdWhile the contract is active. There is no 30-day limit. The request is refused while the contract has an active claim, or when no refund is due on itThe platform that created it, while the installer's connection is active and still grants sales.write for that location

For the second case see Creating for a connected installer.

Request#

NameInTypeRequiredDescription
contractIdquerystringYesThe contract to cancel, as returned by Create / Update Contracts for Whole System Warranty.
cancellationReasonbodystringNoFree-text reason. Recorded for contracts created for a connected installer. Ignored for contracts created with your own key.

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#

bash
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:

json
{
  "isError": false,
  "cancelledContractId": "5233a92bfcc04a77920abfa1fe52194a"
}
FieldTypeMeaning
isErrorbooleanfalse when the contract was cancelled. Check it on every 200, because some failures are also returned with 200.
cancelledContractIdstringThe contract that was cancelled. Same value as the contractId you sent.
messagestringPresent when isError is true. See Errors.

Errors#

Contracts created with your own key#

Errors raised before the cancellation is attempted have this shape, with errorType equal to the HTTP status:

json
{ "isError": true, "errorType": 505, "errorCode": "CANCELLATION_WINDOW_EXPIRED", "message": "Contract can be cancelled only within 30 days from order creation date" }
StatuserrorCodemessageCause and what to do
400CONTRACT_ID_REQUIREDcontractId is requiredAdd contractId to the query string.
401X-SureBright-Access-Token header is requiredThe key is missing. A key that is not valid returns the bodies listed on Authentication.
504CONTRACT_NOT_FOUNDcontract not foundNo contract has that ID. Check that you are sending the contractId from the create response.
503CONTRACT_ACCESS_DENIEDcontract access deniedThe contract does not belong to your account. Use the key of the account that created it.
505CANCELLATION_WINDOW_EXPIREDContract can be cancelled only within 30 days from order creation dateThe 30-day window has passed. Ask your SureBright contact.
505CANCELLATION_WINDOW_EXPIREDSomething went wrongThe contract has no readable order creation date, so the window cannot be checked. Ask your SureBright contact.
200Contract already cancelledisError is true. The contract was cancelled earlier; treat it as done.
200Contract cancellation failed to persistisError is true. The contract is still active. Send the request again.
502Something went wrongSureBright could not complete the request. Send it again.
500Internal Server ErrorUnexpected failure. Send it again.

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.

StatuscodemessageCause and what to do
403Store integration is inactiveThe installer has disconnected your platform. Ask the installer to connect again, or to cancel the plan in their portal.
401invalid_api_keyPartner authentication failedThe key does not belong to the platform that created the contract. Use that platform's key.
403insufficient_scopeThe sales.write scope is requiredThe installer no longer grants sales.write. Ask the installer to approve again.
403access_deniedThe selected location is not authorized or The selected location is not activeThe contract's location is no longer approved for your platform, or is no longer active.
403access_deniedThe merchant authorization is no longer activeThe person who approved the connection is no longer an active owner or administrator. Ask a current owner or administrator to connect again.
403PARTNER_CONTRACT_ACCESS_DENIEDContract is not available to this connectionThe contract does not belong to this connection and location.
400Contract has already been cancelledTreat it as done.
400Refund not available. An active claim exists for this contract.The contract has an active claim. It cannot be cancelled until the claim is closed.
400Sorry, you are not eligible for a refundNo refund is due on the contract, for example because it has reached its end date. It is not cancelled.
400 or 500Something went wrong. Please try again laterThe contract could not be cancelled. Check the contractId, then send the request again.
502Unable to reach the target serviceSend the request again.
503Merchant authorization is unavailableSureBright could not check the connection. Send the request again.

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 200 with isError: true and Contract already cancelled, or 400 with Contract has already been cancelled for a connected installer's contract.

  • The customer is told. SureBright normally emails the customer a cancellation confirmation.

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

This 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-Tokenstringrequired

Access token for authentication

Query parameters

contractIdstringrequired

The unique identifier for the warranty contract to be cancelled

Example: 5233a92bfcc04a77920abfa1fe52194a