---
title: "Integrate with the API"
description: "The end-to-end path for a custom storefront or back office: list categories, get quotes, show the offer, create contracts when the order is paid, report fulfilment, update or cancel, and look contracts up."
---

This page walks one order through the SureBright API, from the first quote to a cancelled plan. It is for teams selling from their own storefront, app or back office rather than through one of SureBright's platform integrations.

Each step names the endpoint, shows a minimal request and lists the response fields the next step needs. The linked reference pages carry the full field lists.

## Before you start

You need the API host (`HOST_NAME`), your `storeId` and an API key. [Authentication](/api-reference/authentication) says where each comes from. The category and quote calls in steps 1 to 3 take no key. Make the Order calls from your server, never from the browser, so the key stays private.

<Tip>
While you build, keep `"isTestOrder": true` in the order body in step 4. The order is recorded as a test order with a **Test** badge on **Sales**. See [Live keys and testing](/api-reference/authentication#live-keys-and-testing).
</Tip>

## The integration, step by step

<Steps>
  <Step title="Get your store's categories">
    [List Category](/api-reference/endpoint/store-category/list-category): `GET /quote/api/storeCategory/listStoreCategories`

    ```bash
    curl 'https://{HOST_NAME}/quote/api/storeCategory/listStoreCategories?storeId={storeId}'
    ```

    The response is an array. From each entry keep:

    | Field | Use |
    |---|---|
    | `sbCategoryId` | The category to quote against in step 2 |
    | `sbCategoryName`, `labelList` | Names for mapping your product types to a category |
    | `storeParentId` | Sent with `sbCategoryId` in step 2 |

    If your store uses the category tree, the same endpoint returns one level per call, or every priced leaf with `view=leaves`. The reference page explains both.
  </Step>
  <Step title="Get quotes for a product">
    [By Category](/api-reference/endpoint/quote/list-warranty-quotes-by-category): `GET /quote/api/quote/category/listQuotes`

    All inputs go in one JSON object, sent Base64-encoded as the `payload` query parameter. Send `quoteSyncMode=SYNC` so the quote is saved before the response returns and can be used in step 4 straight away.

    ```bash
    PAYLOAD=$(printf '%s' '{
      "storeParentId": "{storeParentId}",
      "country": "US",
      "visitId": "3d99a4ae-5cf0-4d87-8436-46c0cdc03676",
      "platform": "OFFLINE_PORTAL",
      "storeCategoryList": [
        { "sbCategoryId": "{sbCategoryId}", "productPrice": 199.99 }
      ]
    }' | base64 | tr -d '\n')

    curl -G 'https://{HOST_NAME}/quote/api/quote/category/listQuotes' \
      --data-urlencode 'quoteSyncMode=SYNC' \
      --data-urlencode "payload=${PAYLOAD}"
    ```

    `country`, `visitId`, `platform` and a non-empty `storeCategoryList` are required, and `storeParentId` must be present when you quote by `sbCategoryId`. `visitId` is any identifier you generate for the shopper's session. Add `province` when you know the shopper's state or province. Each `storeCategoryList` entry quotes one product.

    From `quoteList[]` keep:

    | Field | Use |
    |---|---|
    | `quoteId` | The quote. Sent in step 4 |
    | `quoteItemList[].quoteItemId` | One plan option. Sent in step 4 |
    | `quoteItemList[].policyPrice`, `coverageYears` | The plan's price and term |
    | `coverageList` | Coverage text to show beside the plans |

    An empty `quoteList` means no plan matched that category and price. Show no offer.

    To quote by your own product and variant ids instead, see [By Product](/api-reference/endpoint/quote/list-warranty-quotes-by-product). It only works for products SureBright already knows.
  </Step>
  <Step title="Show the offer and let the shopper pick">
    There is no API call in this step. Render one option per `quoteItemList` entry with its term and price, plus a way to decline. When the shopper picks a plan, store its `quoteId`, `quoteItemId` and price on your cart line.

    To read a saved quote back later, use [Get a quote](/api-reference/endpoint/quote/get-quote). When you render the offer yourself, post shopper interactions to the [Event Collector](/frontend-widget-integration/frontend-widget-kit/event-collector) if you want them in **Sales** analytics. If you would rather not build the offer UI, see [Headless and custom storefronts](/frontend-widget-integration/frontend-widget-kit/headless-and-custom-storefronts).
  </Step>
  <Step title="Create the contracts when the order is paid">
    [Create Contracts for Order](/api-reference/endpoint/order/create-contract): `POST /partner/api/v1/order`

    Call this once payment has succeeded. Contracts are created as soon as the request is accepted. If the request times out, send it again with the same `orderId`; see [Limits, idempotency and versioning](/api-reference/limits-and-versioning#idempotency).

    ```bash
    curl -X POST 'https://{HOST_NAME}/partner/api/v1/order' \
      -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "storeId": "{storeId}",
        "orderId": "ORDER-1001",
        "orderPurchaseDate": "2026-11-12T10:15:30Z",
        "orderLineItemList": [
          {
            "lineItemId": "LINE-1",
            "productId": "PROD-1",
            "productSKU": "SKU-1",
            "productTitle": "Sample product",
            "quantity": 1,
            "salePrice": 199.99,
            "totalPrice": 199.99,
            "planDetails": {
              "policyPurchaseDate": "2026-11-12T10:15:30Z",
              "quoteId": "{quoteId}",
              "quoteItemId": "{quoteItemId}"
            }
          }
        ],
        "customerDetails": {
          "firstName": "Test",
          "lastName": "Customer",
          "customerEmail": "test.customer@example.com",
          "addressLine1": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "country": "US",
          "zipCode": "78701"
        },
        "isTestOrder": true
      }'
    ```

    What the request must carry:

    | Part | Required fields |
    |---|---|
    | Order | `storeId`, `orderId` (your own order id), `orderPurchaseDate`, a non-empty `orderLineItemList`, `customerDetails` |
    | Each line | `lineItemId`, `productId`, `productSKU`, `productTitle`, `quantity`, `salePrice` |
    | `planDetails` | `policyPurchaseDate`, plus `quoteId` and `quoteItemId` from step 2 |
    | `customerDetails` | `firstName`, `lastName`, `customerEmail`, `addressLine1`, `city`, `state`, `country`, and `zipCode` or `pinCode` |

    Dates are ISO 8601 with `Z` or a timezone offset. Put `planDetails` only on the lines that carry a plan; a line without it creates nothing. One contract is created per unit of `quantity`.

    In the response, `contractList[]` has one entry per contract (`lineItemId`, `contractId`, `isCancelled`). Store each `contractId` against your order line. `errorList[]` is present when something failed.

    `200` means no line failed. `207` means some contracts were created and some lines failed. `400` means nothing was created. SureBright emails the customer the plan confirmation; see [Emails your customers receive](/customer-emails/overview).
  </Step>
  <Step title="Report fulfilment (only if coverage starts at shipment)">
    [Set or revert fulfillment dates](/api-reference/endpoint/order/fulfillment): `POST /order/api/v1/contract/fulfillment`

    Skip this step unless your store is set up so that coverage starts when the product ships. The endpoint is enabled per store by SureBright and uses its own server-to-server token, not your API key. Ask your SureBright contact before you build it.

    ```bash
    curl -X POST 'https://{HOST_NAME}/order/api/v1/contract/fulfillment' \
      -H 'Authorization: Bearer {SERVICE_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "contractIds": ["{contractId}"],
        "action": "SET",
        "fulfillmentDate": "2026-11-14T09:00:00Z"
      }'
    ```

    Check `results[]`: each entry carries the `contractId`, its `effectiveDate` and `expirationDate`, and `skipped: true` when the contract already had dates. `"action": "REVERT"` clears the dates after a cancelled shipment.
  </Step>
  <Step title="Update or cancel">
    [Cancel / Update contracts for Order](/api-reference/endpoint/order/update-contract): `PUT /partner/api/v1/order`

    Send the whole order again with the same `orderId`, changed to how it stands now. The body has the same shape and required fields as step 4; it is not a partial update.

    | Change in your order | What to send | Result |
    |---|---|---|
    | Fewer units of a covered product | The line with the lower `quantity` | The difference is cancelled |
    | The plan is removed or refunded | The line with `quantity` set to `0`, or without `planDetails` | Every contract on that line is cancelled |
    | More units of a covered product | The line with the higher `quantity` | Contracts are created for the extra units |

    To cancel a whole order, do this for every plan line. Keep `productId` and `optionId` the same as in step 4, because a line's existing contracts are found by them. Cancelled contracts come back in `contractList` with `isCancelled: true` and cannot be reactivated. The customer receives a cancellation email.
  </Step>
  <Step title="Look contracts up">
    [Get Contracts for Order](/api-reference/endpoint/order/get-contracts): `GET /partner/api/v1/order`

    ```bash
    curl -G 'https://{HOST_NAME}/partner/api/v1/order' \
      --data-urlencode 'storeId={storeId}' \
      --data-urlencode 'partnerOrderId=ORDER-1001' \
      -H 'X-SureBright-Access-Token: sb_live_YOUR_API_KEY'
    ```

    `partnerOrderId` is the `orderId` you sent in step 4. `data.order` is the order as SureBright stored it and `data.contracts` lists its active contracts; cancelled contracts are left out. A `404` with `errorCode: ORDER_NOT_FOUND` means there is no order with that id on that store.

    The lookup is one order per call. To see all contracts for a period, use the export on [Sales](/merchant-portal/sales).
  </Step>
</Steps>

## Where claims are filed

There is no claims step to build: the API has no claim endpoints. Customers file a claim in the customer portal or by email, as described in [Filing a claim](/claims/filing-a-claim).

## Related

<CardGroup cols={2}>
  <Card title="Authentication" href="/api-reference/authentication" icon="shield">
    Keys, the header and testing.
  </Card>
  <Card title="Request conventions" href="/api-reference/endpoint/order/request-conventions" icon="book">
    Rules shared by every Order endpoint.
  </Card>
  <Card title="Notifications and webhooks" href="/api-reference/notifications-and-webhooks" icon="zap">
    How your systems learn about contract and claim changes.
  </Card>
  <Card title="HTTP status codes" href="/api-reference/http-status-codes" icon="file-text">
    The codes each endpoint family returns.
  </Card>
</CardGroup>
