Request conventions
The rules shared by every Order endpoint: base path, accepted credentials and headers, HTTP methods, the postal code alias, and the SureBright Connect fields integration partners send on behalf of a merchant.
All Order endpoints live under https://{HOST_NAME}/partner/api/v1/order. This page collects the behaviour they share so the individual pages can stay short. Read Authentication first; this page only adds what it leaves out.
Base path and transport#
Every request is HTTPS with
Content-Type: application/jsonand a JSON body (exceptGET).Responses are JSON. Partial success on a multi-line order is
207with anerrorList; see HTTP status codes.{HOST_NAME}is the SureBright API host from your Integration Kit; staging and production use different hosts and different keys.
Credentials#
The Order endpoints accept one of three credentials. All resolve to your SureBright account (store parent); the storeId in the body then has to belong to that account.
A request that carries an sb_live_ key which is unknown, revoked or rotated fails with 401 {"message": "Unauthorized! Invalid or revoked API key."} and does not fall through to the other credentials.
Methods#
Customer postal code#
customerDetails carries the postal code as either zipCode or pinCode. The two names are aliases; SureBright stores whichever one you send and validates it against the customer's country. If both are absent the request fails validation with Customer details missing required fields: ... zipCode.
SureBright Connect fields#
An integration partner that sells plans on behalf of merchants does not hold each merchant's API key. Instead the merchant connects to the partner once through Partner sign-in (OIDC), SureBright returns an sbAccountId for that connection, and the partner then calls the whole-system endpoints with its own key plus the fields below.
These fields are read on /v1/order/whole-system and /v1/order/whole-system/cancel only. Direct merchant integrations leave all of them out.
The merchant's public SureBright account ID, as returned by the token endpoint of the partner sign-in flow. Non-empty, at most 200 characters.
Which of the merchant's connected locations the sale belongs to. Use one of the locations[].locationId values from the sign-in response. Always required when you send sbAccountId.
Your partner client ID. Partners that SureBright has registered may send it together with storeId; SureBright resolves the pair to your partner store. Optional when you send sbAccountId.
Your own SureBright store ID (the partner's store, not the merchant's).
Everything else in the body is the normal whole-system payload described on Create / Update Contracts for Whole System Warranty.
curl -X POST https://{HOST_NAME}/partner/api/v1/order/whole-system \
-H 'X-SureBright-Access-Token: sb_live_...' \
-H 'Content-Type: application/json' \
-d '{
"storeId": "{partnerStoreId}",
"sbAccountId": "sb_int_3f9d2c7b-1a4e-4c2b-9f6d-8a1e4b7c2d10",
"sbStoreId": "LOCATION_ID_FROM_SIGN_IN",
"sbProposalId": "PRP-20261105-0042",
"warrantyQuoteId": "WQ-7731",
"warrantyQuoteItemId": "WQI-7731-3Y",
"warrantyCoverageYears": 3,
"customerDetails": { "customerFirstName": "Dana", "customerLastName": "Reyes", "customerEmail": "dana@example.com", "zipCode": "94016", "country": "US" }
}'How a Connect request is authorised#
Your key authenticates you as the partner.
sbAccountIdis looked up. If it matches a merchant connection, the connection must beACTIVE, the merchant must have granted thesales.writescope, andsbStoreIdmust be one of the locations the merchant authorised.If
sbAccountIddoes not match an active connection of yours, the request is refused. Ask the installer to connect again through Partner sign-in.
On cancel, the contract itself tells SureBright which connection it was sold under; you only send contractId (query) and an optional cancellationReason.