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#

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

See Authentication for how to get a key, and Request conventions for the rules shared by every Order endpoint.

Request body#

Order#

NameTypeRequiredDescription
storeIdstringYesYour SureBright store ID, from your Integration Kit.
orderIdstringYesYour own identifier for the order. You pass the same value as partnerOrderId to Get Contracts for Order.
orderPurchaseDatestringYesWhen the customer placed the order. ISO 8601 date and time with Z or a UTC offset, for example 2025-06-16T11:24:00.000Z or 2025-06-11T06:09:17-08:00. A date without a time is rejected.
orderLineItemListobject[]YesThe order's line items. Must not be empty.
customerDetailsobjectYesThe customer and their address.
manufacturerWarrantyDurationintegerNoManufacturer warranty in months, applied to the line items of this order.
totalOrderValuenumberNoOrder total. Must not be negative.
taxAmountnumberNoTax on the order. Must not be negative.
discount.discountAmountnumberNoOrder-level discount. Must not be negative.
isTestOrderbooleanNotrue marks the contracts as test contracts. Accepts a boolean or the strings "true" and "false". Defaults to false.

Line item (orderLineItemList[])#

NameTypeRequiredDescription
lineItemIdstringYesYour identifier for the line. It is returned on every contract and error for that line.
quantitynumberYesUnits of the product bought. Must not be negative. A covered line gets one contract per unit.
productTitlestringYesName of the product.
productIdstringYesYour product identifier.
productSKUstringYesYour SKU for the product.
salePricenumberYesPrice paid per unit. Must not be negative.
optionIdstringNoYour variant identifier. When you send it, SureBright matches the line to its contracts by optionId; otherwise by productId. Send the same value on every later request for the order.
listPricenumberNoList price per unit. Must not be negative.
productURLstringNoLink to the product page.
planDetailsobjectNoThe plan bought for this line. Leave it out for a line sold without a plan.

Plan (planDetails)#

policyPurchaseDate is always required. Then identify the plan in one of two ways.

NameTypeRequiredDescription
policyPurchaseDatestringYesWhen the customer bought the plan. Same format as orderPurchaseDate.
quoteIdstringWith quoteItemIdThe quoteId of the plan the customer chose, from By Category.
quoteItemIdstringWith quoteIdThe quoteItemId of that plan.
policySKUstringWith policyPriceA plan SKU that SureBright shared for your store. The line's salePrice has to fall inside the price band that SKU is set up for.
policyPricenumberWith policySKUPrice the customer paid for the plan. Must be greater than zero and less than salePrice.

If a line carries both pairs, quoteId and quoteItemId are used and the SKU is ignored.

Customer (customerDetails)#

NameTypeRequiredDescription
firstName, lastNamestringYesCustomer name.
customerEmailstringYesMust look like an email address (name@domain.tld).
addressLine1stringYesFirst line of the address.
addressLine2stringNoSecond line of the address.
citystringYesCity.
statestringYesState or province code, for example NY.
countrystringYesTwo-letter country code, for example US.
zipCode or pinCodestringYes, one of themPostal code. See below.
mobileNumberstringNoCustomer phone number.

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#

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

json
{
  "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 }
  ]
}
FieldTypeMeaning
storeId, orderIdstringEchoed from the request.
contractListobject[]One entry per contract, so a line with quantity 2 appears twice.
contractList[].lineItemIdstringThe line the contract belongs to.
contractList[].contractIdstringThe contract's identifier. Store it against the order line.
contractList[].isCancelledbooleanfalse for an active contract. true appears on updates that cancel contracts.
errorListobject[]Present only when something failed. See Errors.

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.

StatusMeaning
200Every covered line was processed. No errorList.
207Some contracts were created and some lines failed. Read both contractList and errorList.
400Nothing was created. errorList says why.
401The key is missing or not valid. See Authentication.
500SureBright could not complete the request.

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:

ShapeWhen
{"errorMessage": "..."}The request as a whole failed validation.
{"lineItemId": "...", "error": "..."}A line item failed validation.
{"field": "...", "error": "..."}The customer details or an optional field failed validation.
{"error": "..."}The store, the order or a plan SKU could not be resolved.
{"lineItemId": "...", "errorType": 504, "errorMessage": "..."}The quote for a line could not be found.
StatusMessageCause and what to do
400X-SureBright-Access-Token header is requiredThe X-SureBright-Access-Token header is missing. Send your key in that header.
400Missing required fields: ...One of storeId, orderId, orderPurchaseDate, orderLineItemList, customerDetails is absent or empty.
400orderPurchaseDate must be a valid ISO date, e.g., 2025-06-11T06:09:17-08:00Wrong date format. Include the time and Z or an offset.
400orderLineItemList must be a non-empty arraySend at least one line item.
400Line item at index N missing required fields: ...A line lacks lineItemId, quantity, productTitle, productId, productSKU or salePrice.
400quantity must be a positive number, salePrice must be a non-negative number, listPrice must be a non-negative numberSend these as JSON numbers, not strings, and not negative.
400planDetails.policyPurchaseDate is required or ... must be a valid ISO date ...Add the plan purchase date in the same format as orderPurchaseDate.
400planDetails must contain one of the following: ...Send quoteId with quoteItemId, or policySKU with policyPrice.
400planDetails.policyPrice must be less than salePriceCheck that you did not swap the two prices.
400Customer details missing required fields: ...Fill in the listed customer fields.
400Invalid email format in customerDetailsFix customerEmail.
400discountAmount must be a non-negative number (also totalOrderValue, taxAmount)Send a number that is not negative, or leave the field out.
400Invalid storeParentId: Store Parent not foundstoreId is not a store SureBright knows. Use the ID from your Integration Kit.
400Order ... does not exist for store ... on platform ...The store is connected to an e-commerce platform and SureBright has not received this order from it. Check orderId.
400 or 207No Quote Found (errorType: 504)The quoteId is unknown. Request the quote with quoteSyncMode=SYNC so that it is saved before you create the contract.
400 or 207The specified Quote Item ID is not found within the provided quote. (errorType: 504)quoteItemId does not belong to quoteId. Send both from the same quote.
400 or 207Invalid policy SKU: ... for line item NThe SKU is not set up for your store, or salePrice is outside its price band.
500Failed to process order with internal serviceThe request did not complete in time or failed part-way. See the retry note below.
500Internal server error occurred while processing the requestUnexpected failure. See the retry note below.

Behaviour notes#

  • One contract per unit. A covered line with quantity 3 creates three contracts that share the lineItemId.

  • 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 contractId values. You get 200, not an error, and no duplicates.

  • One line per product. Contracts are matched to a line by optionId when you send it, otherwise by productId, and counted across the order. Do not split the same product over two lines; send one line with the total quantity.

  • POST and PUT behave the same. Both compare what you send with the active contracts on the order. A POST for 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.

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

This 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-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",
  "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
}