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/json and a JSON body (except GET).

  • Responses are JSON. Partial success on a multi-line order is 207 with an errorList; 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.

CredentialWhere to send itNotes
Self-serve developer key, sb_live_...X-SureBright-Access-Token: sb_live_...Created on the merchant portal Developers page. Send it in this header only; an API key is not accepted in Authorization.
Integration Kit access tokenX-SureBright-Access-Token onlyIssued by SureBright during onboarding. Not accepted in Authorization.
Partner's own key (SureBright Connect)As for the key type aboveAn integration partner authenticates with its own key (self-serve or Integration Kit) and identifies the merchant in the body. See below.

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#

PathMethodsNotes
/v1/orderPOST create, PUT update or cancel line items, GET look upSee Create, Update and Get contracts.
/v1/order/whole-systemAnyThe route accepts every HTTP method and treats them alike. Use POST.
/v1/order/whole-system/cancelPOSTcontractId goes in the query string.

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.

string

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.

string

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.

string

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.

stringrequired

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.

bash
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#

  1. Your key authenticates you as the partner.

  2. sbAccountId is looked up. If it matches a merchant connection, the connection must be ACTIVE, the merchant must have granted the sales.write scope, and sbStoreId must be one of the locations the merchant authorised.

  3. If sbAccountId does 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.

Errors specific to Connect requests#

StatusBodyCause
400{"isError": true, "message": "Use sbAccountId instead of merchantStoreId"}merchantStoreId is not accepted on these endpoints
400{"isError": true, "message": "sbAccountId must be a non-empty identifier"}Empty, non-string or over 200 characters
401code: invalid_api_key, Partner authentication failedThe connection does not belong to the partner whose key was used
403code: insufficient_scopeThe merchant did not grant sales.write
403code: access_denied, The selected location is not authorizedsbStoreId is not one of the authorised locations
403{"isError": true, "message": "Store integration is inactive"}Cancel on a contract whose merchant connection has been revoked
409code: invalid_request, partnerId and storeId must identify the same partnerpartnerId and storeId resolve to different partners
503{"isError": true, "code": "PARTNER_LOOKUP_UNAVAILABLE", ...} or Merchant authorization is unavailableSureBright could not reach its partner registry; retry