Create Contracts for Order
POST https://{HOST_NAME}/partner/api/v1/order
Use this endpoint to record an order on which you sold protection plans through your own checkout or sales tool. You send the order, its line items and, for each covered line, the plan the customer bought. SureBright creates one contract per covered unit and returns the contract IDs.
Send an order here the first time. To change quantities or cancel plans later, use Cancel / Update contracts for Order. To read back what exists, use Get Contracts for Order. Whole-system sales have their own endpoint, Create / Update Contracts for Whole System Warranty.
Headers#
See Authentication for how to get a key, and Request conventions for the rules shared by every Order endpoint.
Request body#
Order#
Line item (orderLineItemList[])#
Plan (planDetails)#
policyPurchaseDate is always required. Then identify the plan in one of two ways.
If a line carries both pairs, quoteId and quoteItemId are used and the SKU is ignored.
Customer (customerDetails)#
Required customer fields have to be non-empty strings.
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#
curl -X POST '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": 2,
"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 when every covered line was processed:
{
"storeId": "{storeId}",
"orderId": "83737121380",
"contractList": [
{ "lineItemId": "line-1", "contractId": "abc12345-6789-4abc-bcde-ef1234567890", "isCancelled": false },
{ "lineItemId": "line-1", "contractId": "def67890-1234-4def-8abc-0123456789ab", "isCancelled": false }
]
}To confirm what was created, call Get Contracts for Order (GET /partner/api/v1/order?storeId=...&partnerOrderId=...) with the same key.
Errors#
The status code tells you how much of the order went through.
Request validation runs before anything is created. If any line item, the customer details or an optional field fails validation, the whole request is rejected with 400.
Entries in errorList do not all have the same shape, so read whichever message key is present:
Behaviour notes#
One contract per unit. A covered line with
quantity3 creates three contracts that share thelineItemId.Lines without a plan create nothing. A line with no
planDetails, or an empty one, is accepted and ignored.Repeating a create is safe. If you send the same order again, SureBright finds the active contracts it already holds for each line and returns them with the same
contractIdvalues. You get200, not an error, and no duplicates.One line per product. Contracts are matched to a line by
optionIdwhen you send it, otherwise byproductId, and counted across the order. Do not split the same product over two lines; send one line with the total quantity.POSTandPUTbehave the same. Both compare what you send with the active contracts on the order. APOSTfor an order that already has contracts can therefore create more or cancel some, exactly as described on Cancel / Update contracts for Order.Retry one request at a time. After a
500, the order may still have been processed. Look it up with Get Contracts for Order before you send it again, and send one request per order at a time.
Related#
Change quantities or cancel plans on an order.
Read back the active contracts on an order.
Get the quote IDs to send in planDetails.
Credentials, methods and the postal code alias.
https://api.surebright.com/partner/api/v1/orderThis endpoint is used to create warranty contracts for a specific order.
🛠️ Contract Creation Logic
Warranty contracts are created in a 1:1 ratio with the quantity of the associated product purchased.
The warranty quantity is automatically inferred from the product quantity.
Contracts are only created for the exact number of products purchased—warranty coverage cannot exceed or fall short of the product quantity.
🏷️ Using policySKU
The policySKU is a required field that determines the parameters of each warranty contract, including:
- Coverage Type (e.g., accidental damage, mechanical breakdown)
- Tenure (duration of coverage)
- Country (to apply relevant terms and conditions)
- Category (product type classification)
Merchants must ensure that the appropriate policySKU is used for each product to ensure accurate coverage assignment.
🔁 Handling Updates
If this endpoint is called for an order where contracts already exist:
- Existing contracts will be updated if the quantity or details have changed.
- Warranty price, tenure, and coverage type are handled automatically based on the provided policySKU.
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",
"manufacturerWarrantyDuration": 24,
"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
}