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#

HeaderDescriptionRequired
X-SureBright-Access-TokenMerchant API key (sb_live_...) or integration-kit access tokenYes
Content-Typeapplication/jsonYes

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:

NameTypeRequiredDescription
storeIdstringYesThe store ID you used when you created the order.
orderIdstringYesThe order ID you used when you created the order.
orderPurchaseDatestringYesISO 8601 date and time with Z or a UTC offset, for example 2025-06-11T06:09:17-08:00.
customerDetailsobjectYesThe customer and address, with the same required fields as on create.
orderLineItemListobject[]YesThe lines you want SureBright to reconcile. Lines you leave out are not touched.
orderLineItemList[].lineItemId, productTitle, productId, productSKU, salePriceYesRequired on every line you send, as on create.
orderLineItemList[].optionIdstringNoSend it if you sent it on create. It is how the line is matched to its contracts.
orderLineItemList[].quantitynumberYesHow many units of the line should be covered after this request. 0 cancels the line's plans.
orderLineItemList[].planDetailsobjectNoThe plan for the line. Needed when the request creates contracts. If you leave it out or send it empty, the line is treated as having no plan and its active contracts are cancelled. When present it must carry policyPurchaseDate.

What each change does#

You send, for a lineResult
quantity lower than the number of active contractsThe difference is cancelled.
quantity of 0Every active contract on the line is cancelled.
No planDetails, or an empty oneEvery active contract on the line is cancelled, whatever the quantity.
quantity higher than the number of active contracts, with planDetailsThe difference is created as new contracts.
quantity equal to the number of active contractsNothing changes. The existing contracts are returned.
The line is not in orderLineItemListNothing changes for that line.

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.

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

json
{
  "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 }
  ]
}
FieldTypeMeaning
storeId, orderIdstringEchoed from the request.
contractListobject[]The contracts this request touched or kept on the lines you sent.
contractList[].lineItemIdstringThe line the contract belongs to.
contractList[].contractIdstringThe contract's identifier.
contractList[].isCancelledbooleantrue for a contract this request cancelled. false for one that is still active.
errorListobject[]Present only when something failed.

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:

StatusMessageCause and what to do
400Missing required fields: ... or Customer details missing required fields: ...You sent only the changed fields. Send the full order body.
400Line item at index N missing required fields: ...A line lacks productTitle, productSKU, salePrice or another required field, even though you only meant to change its quantity.
400quantity must be a positive numberquantity is negative or not a JSON number. 0 is accepted.
400planDetails.policyPurchaseDate is requiredA non-empty planDetails needs the purchase date. To cancel, leave planDetails out altogether or set quantity to 0.
400 or 207No Quote Found (errorType: 504)The request raises a quantity and the quoteId is unknown. Quote again with quoteSyncMode=SYNC and send the new IDs.
401See AuthenticationThe key is missing or not valid.
500Failed to process order with internal serviceThe request did not complete. Check the order with Get Contracts for Order before you send it again.

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 quantity but different customerDetails, salePrice or planDetails, the existing contracts stay as they were.

  • Changing the plan on a line. Cancel the line's contracts first (quantity 0), then send the line again with the new planDetails. 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 contractList to see which contract IDs now have isCancelled: true.

  • Keep the product identifiers stable. Lines are matched to their contracts by optionId when you send it, otherwise by productId. If these differ from the create request, SureBright sees a new product and creates contracts instead of updating.

  • A PUT for an unknown order creates it. POST and PUT behave 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.

PUThttps://api.surebright.com/partner/api/v1/order

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

Merchant API key (sb_live_...) created on the Merchant Portal Developers page, or the integration-kit access token

Body

application/json
json
{
  "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
}