API quickstart

Four copy-paste curl requests: list your store's categories, quote plans for a product, record a test order with a plan, and look its contracts up.

This page gets you from nothing to a recorded test order with a protection plan in four requests. Run them in a terminal in order: each one uses a value from the one before. For what each field means and the update and cancel calls, follow Integrate with the API afterwards.

Before you start#

You needWhere to get it
Your storeId and storeParentIdYour SureBright Integration Kit, or ask your SureBright contact
An API key, prefixed sb_live_Merchant Portal Developers page. Only steps 3 and 4 need it. See Authentication
curl and base64Any macOS or Linux terminal

Set them once:

bash
export SB_HOST='https://api.surebright.com'
export SB_STORE_ID='{storeId}'
export SB_STORE_PARENT_ID='{storeParentId}'
export SB_API_KEY='sb_live_YOUR_API_KEY'

There is no sandbox. The order in step 3 is real, so keep "isTestOrder": true in it: SureBright records it as a test order with a Test badge on Sales. Make Order calls from your server in production, never from the browser.

1. List your store's categories#

No key needed.

bash
curl "$SB_HOST/quote/api/storeCategory/listStoreCategories?storeId=$SB_STORE_ID"

A successful response looks like this (example values from the OpenAPI spec):

json
[
  {
    "storeCategoryId": "07b1dcb3-fbe5-46c6-b42f-66d82e89f2a7",
    "storeParentId": "13612f29-8ec5-49ad-bab1-5ab09b51367e",
    "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f",
    "sbCategoryName": "Small Home Appliance",
    "labelList": [
      "Ovens",
      "Microwaves",
      "Refrigerators"
    ]
  }
]

Pick an entry from the array and copy its sbCategoryId:

bash
export SB_CATEGORY_ID='{sbCategoryId}'

2. Quote plans for a product#

No key needed. The inputs go in one JSON object, Base64-encoded as the payload parameter. quoteSyncMode=SYNC saves the quote before the response returns, so you can use it in step 3 straight away.

bash
PAYLOAD=$(printf '{"storeParentId":"%s","country":"US","visitId":"quickstart-1","platform":"OFFLINE_PORTAL","storeCategoryList":[{"sbCategoryId":"%s","productPrice":199.99}]}' \
  "$SB_STORE_PARENT_ID" "$SB_CATEGORY_ID" | base64 | tr -d '\n')

curl -G "$SB_HOST/quote/api/quote/category/listQuotes" \
  --data-urlencode 'quoteSyncMode=SYNC' \
  --data-urlencode "payload=$PAYLOAD"

A successful response looks like this (example values from the OpenAPI spec):

json
{
  "quoteList": [
    {
      "storeCategoryId": "ecca4210-09a4-446c-ad87-5e65bd50df12",
      "sbCategoryId": "4c3103e4-38dc-4171-96e5-b4b77ab0e96f",
      "country": "US",
      "platform": "SHOPIFY",
      "sbProductId": "643bc477-0eec-4da1-946a-38ff7d1292c9",
      "storeParentId": "ecca4210-09a4-446c-ad87-5e65bd50df12",
      "allowDynamicPolicyPricing": true,
      "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537",
      "quoteItemList": [
        {
          "quoteId": "33f21a29-95ca-4150-b5df-afe36f5ef537",
          "quoteItemId": "33f21a29-95ca-4150-b5df-afe36f5ef537",
          "lowerPrice": 749.99,
          "upperPrice": 999.99,
          "coverageYears": "1",
          "policyPrice": "79",
          "storeProductVariantPrice": "899.99",
          "country": "US",
          "isActive": true
        }
      ],
      "coverageType": "AD",
      "coverageList": [
        {
          "coverageItemType": "COVERAGE_OPTION",
          "coverageItemTitle": "Your warranty plan provides",
          "coverageItemList": [
            "Protection against everyday spills (food, beverages, human or pet biological stains, cosmetics, etc)."
          ]
        }
      ],
      "policyId": "1234567890",
      "createdAt": "2021-01-01T00:00:00Z",
      "updatedAt": "2021-01-01T00:00:00Z"
    }
  ]
}

From the first entry of quoteList, copy quoteId, and from its quoteItemList copy one quoteItemId. Each quoteItemList entry is one plan with its coverageYears and policyPrice. An empty quoteList means no plan matches that category and price: try another category or price.

bash
export SB_QUOTE_ID='{quoteId}'
export SB_QUOTE_ITEM_ID='{quoteItemId}'

3. Record a test order with the plan#

Needs your API key.

bash
NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -X POST "$SB_HOST/partner/api/v1/order" \
  -H "X-SureBright-Access-Token: $SB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "storeId": "'"$SB_STORE_ID"'",
    "orderId": "QUICKSTART-1",
    "orderPurchaseDate": "'"$NOW"'",
    "orderLineItemList": [{
      "lineItemId": "LINE-1",
      "productId": "PROD-1",
      "productSKU": "SKU-1",
      "productTitle": "Quickstart test product",
      "quantity": 1,
      "salePrice": 199.99,
      "totalPrice": 199.99,
      "planDetails": {
        "policyPurchaseDate": "'"$NOW"'",
        "quoteId": "'"$SB_QUOTE_ID"'",
        "quoteItemId": "'"$SB_QUOTE_ITEM_ID"'"
      }
    }],
    "customerDetails": {
      "firstName": "Test", "lastName": "Customer",
      "customerEmail": "test.customer@example.com",
      "addressLine1": "123 Main St", "city": "Austin", "state": "TX",
      "country": "US", "zipCode": "78701"
    },
    "isTestOrder": true
  }'

A successful response looks like this (example values from the OpenAPI spec):

json
{
  "storeId": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09",
  "orderId": "83737121380",
  "contractList": [
    {
      "lineItemId": "374dc3c3-94a3-4b85-a876-8651e461446d",
      "contractId": "abc12345-6789-4abc-bcde-ef1234567890",
      "isCancelled": false
    }
  ]
}

A 200 with one entry in contractList means the contract was created. A 400 or an errorList in the response says which field to fix; see HTTP status codes. If the request timed out, send it again with the same orderId: SureBright does not create the contract twice.

4. Look the contracts up#

Needs your API key.

bash
curl -G "$SB_HOST/partner/api/v1/order" \
  --data-urlencode "storeId=$SB_STORE_ID" \
  --data-urlencode 'partnerOrderId=QUICKSTART-1' \
  -H "X-SureBright-Access-Token: $SB_API_KEY"

A successful response looks like this. The spec describes data.order and each contract in data.contracts without listing their fields, so they are shown abridged here:

text
{
  "isError": false,
  "storeId": "f4c059b2-5b74-4e4c-a3c5-85bc80cf8a09",
  "partnerOrderId": "QUICKSTART-1",
  "data": {
    "order": { ...the order as SureBright stored it... },
    "contracts": [ { ...one active contract... } ],
    "processedAt": "2026-11-05T10:15:30.000Z"
  }
}

data.contracts lists the contract from step 3. The order also appears on Sales in the Merchant Portal with a Test badge.

Next steps#