---
title: "API quickstart"
description: "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](/api-reference/integration-tutorial) afterwards.

## Before you start

| You need | Where to get it |
|---|---|
| Your `storeId` and `storeParentId` | Your 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](/api-reference/authentication) |
| `curl` and `base64` | Any 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'
```

<Warning>
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.
</Warning>

## 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](/api-reference/openapi.json)):

```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](/api-reference/openapi.json)):

```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](/api-reference/openapi.json)):

```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](/api-reference/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

- [Integrate with the API](/api-reference/integration-tutorial): every step in detail, including fulfilment, updates and cancellations.
- [Endpoint map](/api-reference/introduction#endpoint-map): every endpoint and whether it needs a key.
- [Use these docs with AI assistants](/api-reference/ai-assistants): point a coding agent at `llms.txt` and the OpenAPI spec to write this integration for you.
