---
title: "Limits, idempotency and versioning"
description: "What is and is not fixed about the SureBright API: request limits, what happens when you send the same order twice, pagination, path versions and where to download the OpenAPI document."
---

This page collects the operational facts an integrator asks about before going live: how fast you may call, whether a retry can create duplicates, how results are paged and how the API is versioned. Where SureBright has not published a figure or a policy, the page says so instead of guessing.

## Rate limits

| Endpoints | Limit | Over the limit |
|---|---|---|
| Category, quote and Order endpoints | No fixed public limit is published | Not applicable |
| [Invoice upload and line-item update](/api-reference/endpoint/quote/invoice-upload) | 50 requests per minute, shared across all callers | `429` with a `Retry-After` header in seconds |

"No published limit" is not an invitation to send traffic without bound. Keep to the rate your shoppers and orders naturally produce. Before a bulk load, such as a backfill of past orders or quoting a whole catalogue, tell your SureBright contact what you plan to send and when.

## Idempotency

The Order endpoints do not take an idempotency key. An order is identified by its `storeId` and `orderId`, and that pair is what makes a repeat safe.

| You send | What happens |
|---|---|
| The same `POST` or `PUT /partner/api/v1/order` body again | Each plan line is compared with the active contracts already on the order, matched by `productId` and `optionId`. Units that already have a contract get no second one. The existing `contractId` values come back in `contractList` |
| The same order with a higher `quantity` on a plan line | Contracts are created for the extra units only |
| The same order with a lower `quantity`, `quantity` `0`, or no `planDetails` on a line | The difference is cancelled. A cancelled contract cannot be reactivated |
| The same [fulfilment dates](/api-reference/endpoint/order/fulfillment) request again | Contracts that are already dated are reported with `skipped: true` and left alone |

Two things follow from this:

- A retry is only harmless when the body is unchanged. Because a later request with fewer units cancels contracts, always send the order as it stands now, not an older copy.
- Use one stable `orderId` per order and keep each line's `productId` and `optionId` the same on every call. Changing them makes SureBright treat the line as a different product.

`POST` and `PUT` on `/partner/api/v1/order` are handled the same way: either creates the order when it is new and updates it when it exists. Customer emails are sent at most once per order or per plan, so a replayed order does not email the customer twice; see [Emails your customers receive](/customer-emails/overview).

The field-level rules are on [Create Contracts for Order](/api-reference/endpoint/order/create-contract) and [Cancel / Update contracts for Order](/api-reference/endpoint/order/update-contract). For the rules on headers and methods shared by every Order endpoint, see [Request conventions](/api-reference/endpoint/order/request-conventions).

## Pagination and sizes

No endpoint in the API reference takes `page`, `limit` or cursor parameters.

| Endpoint | How results are bounded |
|---|---|
| [List Category](/api-reference/endpoint/store-category/list-category) | One array with every active category. Stores on the category tree get one level per call, or every priced leaf with `view=leaves` |
| [Quotes by Category](/api-reference/endpoint/quote/list-warranty-quotes-by-category) | One quote per `storeCategoryList` entry you send |
| [Get Contracts for Order](/api-reference/endpoint/order/get-contracts) | One order per call, with its active contracts. There is no endpoint that lists contracts across orders |

The OpenAPI document gives `orderId` and `lineItemId` a maximum length of 48 characters. Stay within it. To read contracts for a whole period, use **Download** on [Sales](/merchant-portal/sales).

## Versioning

Versions are part of the path, and not every family has one:

| Path family | Version segment |
|---|---|
| Order: `/partner/api/v1/order`, `/partner/api/v1/order/whole-system` | `v1` |
| Fulfilment dates: `/order/api/v1/contract/fulfillment` | `v1` |
| Partner sign-in: `/site-platform/api/v1/sso` | `v1` |
| Quotes and categories: `/quote/api/quote/...`, `/quote/api/storeCategory/...`, `/quote/api/whole-system/...` | None |

That is a description of the paths in use today. SureBright has not published a compatibility or deprecation policy for the API, and there is no public changelog, so these docs make no promise about either. Write your client to ignore response fields it does not recognise, and ask your SureBright contact how changes that affect your integration will reach you.

## The OpenAPI document

The machine-readable description of the API is served from this docs site at `/api-reference/openapi.json`, in OpenAPI 3.0 format. Download it and import it into Postman or a similar tool to get a ready-made collection.

- It covers the ten operations whose reference pages are generated from it: categories, quotes by category, by product and by URL, the Order create, update and lookup calls, and the whole system warranty calls.
- Pages written by hand, such as [Get a quote](/api-reference/endpoint/quote/get-quote) and [Set or revert fulfillment dates](/api-reference/endpoint/order/fulfillment), are not in it.
- Its server is the placeholder `https://{HOST_NAME}`. Set the host after you import; see [Authentication](/api-reference/authentication#required-credentials).
- Three operations carry their query string inside the path. Check those requests after importing, because some tools read the query string as part of the path.

## Timeouts and retries

<Note>
The points below are general client advice, not SureBright commitments. SureBright does not publish response-time figures.
</Note>

- Set an explicit timeout on every call so a slow response cannot hold a checkout page or a worker open.
- A quote that fails or times out should hide the offer, not block the product page or the checkout.
- Retry `429`, `502`, `503` and network errors with a growing delay between attempts, and honour `Retry-After` when it is present. Do not retry `400` or `401` unchanged; fix the request or the key first.
- Send one request per order at a time. Wait for the response, or for your timeout, before you send that order again.
- After a create that timed out, read the order back with [Get Contracts for Order](/api-reference/endpoint/order/get-contracts) or resend the same body; both are safe for the reasons under [Idempotency](#idempotency).

## Related

- [Integrate with the API](/api-reference/integration-tutorial)
- [Authentication](/api-reference/authentication)
- [Request conventions](/api-reference/endpoint/order/request-conventions)
- [HTTP status codes](/api-reference/http-status-codes)
- [Notifications and webhooks](/api-reference/notifications-and-webhooks)
