Limits, idempotency and versioning
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#
"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.
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
orderIdper order and keep each line'sproductIdandoptionIdthe 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.
The field-level rules are on Create Contracts for Order and Cancel / Update contracts for Order. For the rules on headers and methods shared by every Order endpoint, see Request conventions.
Pagination and sizes#
No endpoint in the API reference takes page, limit or cursor parameters.
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.
Versioning#
Versions are part of the path, and not every family has one:
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 and Set or revert fulfillment dates, are not in it.
Its server is the placeholder
https://{HOST_NAME}. Set the host after you import; see Authentication.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#
The points below are general client advice, not SureBright commitments. SureBright does not publish response-time figures.
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,503and network errors with a growing delay between attempts, and honourRetry-Afterwhen it is present. Do not retry400or401unchanged; 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 or resend the same body; both are safe for the reasons under Idempotency.