Cancel / Update contracts for Order
PUT https://{HOST_NAME}/partner/api/v1/order
Use this endpoint to change an order you have already sent: lower or raise the quantity on a covered line, cancel the plans on a line, or cancel every plan on the order. You send the order again, and SureBright compares each line's quantity with the active contracts it holds for that line, then cancels or creates the difference.
This is also how you cancel ordinary contracts. There is no separate cancel call for them. Send the order the first time with Create Contracts for Order, and cancel a whole-system contract with Cancel Contracts for Whole System Warranty instead.
Headers#
Request body#
The body is the same as on Create Contracts for Order and passes the same validation, so every required field has to be present even when you only change one quantity. The full field tables are on Create Contracts for Order. The fields that drive an update are:
What each change does#
To cancel every plan on an order, send every covered line with quantity 0, or send them without planDetails.
Customer postal code#
customerDetails must carry the postal code as either zipCode or pinCode; the two names are aliases and SureBright stores whichever one you send. If both are missing, the request fails validation with Customer details missing required fields: ... zipCode.
Example request#
The order was created with two covered units on line-1. This request reduces it to one, which cancels one contract.
curl -X PUT 'https://{HOST_NAME}/partner/api/v1/order' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \
-d '{
"storeId": "{storeId}",
"orderId": "83737121380",
"orderPurchaseDate": "2026-01-07T10:15:30Z",
"orderLineItemList": [
{
"lineItemId": "line-1",
"quantity": 1,
"productTitle": "Example Wood Chipper",
"productId": "6673746231399",
"productSKU": "ALH05",
"salePrice": 899.99,
"planDetails": {
"policyPurchaseDate": "2026-01-07T10:15:30Z",
"quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537",
"quoteItemId": "a7defcbd-aa07-4e01-9076-c1935af20a98"
}
}
],
"customerDetails": {
"firstName": "Dana",
"lastName": "Reyes",
"customerEmail": "dana@example.com",
"addressLine1": "123 Example Street",
"city": "New York",
"state": "NY",
"country": "US",
"zipCode": "10005"
}
}'Example response#
200:
{
"storeId": "{storeId}",
"orderId": "83737121380",
"contractList": [
{ "lineItemId": "line-1", "contractId": "abc12345-6789-4abc-bcde-ef1234567890", "isCancelled": true },
{ "lineItemId": "line-1", "contractId": "def67890-1234-4def-8abc-0123456789ab", "isCancelled": false }
]
}If a line you send has no active contracts and no plan to create, it adds nothing to contractList. A request that changes nothing returns 200 with the existing contracts, or an empty contractList.
Errors#
Status codes, errorList shapes and validation messages are the same as on Create Contracts for Order. The ones you are most likely to meet on an update:
Behaviour notes#
What this endpoint can change. The number of active contracts on each line you send: it cancels contracts or creates new ones.
What it cannot change. Contracts that already exist are not edited. If you resend a line with the same
quantitybut differentcustomerDetails,salePriceorplanDetails, the existing contracts stay as they were.Changing the plan on a line. Cancel the line's contracts first (
quantity0), then send the line again with the newplanDetails. The new contracts have new IDs.A cancelled contract stays cancelled. It is not reactivated. Sending the line again with a plan creates new contracts.
You do not choose which contract is cancelled. When you reduce a quantity, read
contractListto see which contract IDs now haveisCancelled: true.Keep the product identifiers stable. Lines are matched to their contracts by
optionIdwhen you send it, otherwise byproductId. If these differ from the create request, SureBright sees a new product and creates contracts instead of updating.A
PUTfor an unknown order creates it.POSTandPUTbehave the same, so an update for an order SureBright has not seen creates contracts for its covered lines.The customer is told. SureBright normally emails the customer one cancellation confirmation per line item, not one per contract.
One request at a time. Do not send two requests for the same order at the same moment.
Related#
Full request fields, validation messages and error shapes.
Read back the active contracts on an order.
Cancel a whole-system contract by its ID.
Credentials, methods and the postal code alias.
https://api.surebright.com/partner/api/v1/orderThis endpoint is used to create, update, or cancel warranty contracts for a specific order.
🔄 Updating Line Item Quantities
If the quantity of a product in the original order is changed (e.g., reduced), the corresponding warranty contract quantity is automatically adjusted to match the updated product quantity.
To reduce or cancel warranty coverage for a line item, update the quantity field inside the relevant lineItem object in the orderLineItemList.
❌ Cancelling Line Items
To cancel warranty coverage for a specific line item, set its quantity to 0 in the orderLineItemList.
Once cancelled, a warranty contract cannot be reactivated.
This applies to both partial cancellations (some items in the order) and full order cancellations.
🧾 Handling Full Order Cancellation
For full order cancellations, merchants have two options:
- Remove the planDetails object entirely from the request payload.
- Set the quantity of each relevant lineItem in orderLineItemList to 0.
⚙️ Automatic Price and Tenure Updates
Any changes to warranty price or tenure (e.g., due to product updates or plan revisions) are handled automatically by the system.
Authorizations
X-SureBright-Access-TokenstringrequiredMerchant API key (sb_live_...) created on the Merchant Portal Developers page, or the integration-kit access token
Body
{
"storeId": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09",
"orderId": "83737121380",
"orderPurchaseDate": "2024-01-07T10:15:30Z",
"orderLineItemList": [
{
"lineItemId": "374dc3c3-94a3-4b85-a876-8651e461446d",
"planDetails": {
"policyPurchaseDate": "2024-01-07T10:15:30Z",
"quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537",
"quoteItemId": "a7defcbd-aa07-4e01-9076-c1935af20a98",
"policySKU": "SBW-1U-SHAB-2900",
"policyPrice": 29,
"categoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f",
"tenure": 2
},
"totalPrice": 3300,
"quantity": 3,
"productTitle": "GreatCircleUSA 3-in-1 Wood Chipper - 7HP Engine, 3 Max Branch Capacity",
"productId": "6673746231399",
"optionId": "8577825144935",
"productSKU": "ALH05",
"salePrice": 1100,
"listPrice": 1299,
"discountAmount": 199,
"productURL": "https://example.com/products/wood-chipper-alh05"
}
],
"customerDetails": {
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Hathway Street",
"addressLine2": "Apt 4B",
"city": "New York City",
"state": "NY",
"country": "US",
"zipCode": "10005",
"pinCode": "10005",
"customerEmail": "johndoe@gmail.com",
"mobileNumber": "7872323781"
},
"discount": {
"discountAmount": 10
},
"totalOrderValue": 1000,
"isTestOrder": false,
"taxAmount": 100
}