---
title: "Request conventions"
description: "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](/api-reference/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](/api-reference/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.

| Credential | Where to send it | Notes |
|---|---|---|
| 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 token | `X-SureBright-Access-Token` only | Issued by SureBright during onboarding. Not accepted in `Authorization`. |
| Partner's own key (SureBright Connect) | As for the key type above | An 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

| Path | Methods | Notes |
|---|---|---|
| `/v1/order` | `POST` create, `PUT` update or cancel line items, `GET` look up | See [Create](/api-reference/endpoint/order/create-contract), [Update](/api-reference/endpoint/order/update-contract) and [Get contracts](/api-reference/endpoint/order/get-contracts). |
| `/v1/order/whole-system` | Any | The route accepts every HTTP method and treats them alike. Use `POST`. |
| `/v1/order/whole-system/cancel` | `POST` | `contractId` 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)](/api-reference/endpoint/partner/sso), 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.

<ParamField body="sbAccountId" type="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.
</ParamField>

<ParamField body="sbStoreId" type="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`.
</ParamField>

<ParamField body="partnerId" type="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`.
</ParamField>

<ParamField body="storeId" type="string" required>
  Your own SureBright store ID (the partner's store, not the merchant's).
</ParamField>

Everything else in the body is the normal whole-system payload described on [Create / Update Contracts for Whole System Warranty](/api-reference/endpoint/order/create-contract-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](/api-reference/endpoint/partner/sso).

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

| Status | Body | Cause |
|--------|------|-------|
| `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 |
| `401` | `code: invalid_api_key`, `Partner authentication failed` | The connection does not belong to the partner whose key was used |
| `403` | `code: insufficient_scope` | The merchant did not grant `sales.write` |
| `403` | `code: access_denied`, `The selected location is not authorized` | `sbStoreId` 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 |
| `409` | `code: invalid_request`, `partnerId and storeId must identify the same partner` | `partnerId` and `storeId` resolve to different partners |
| `503` | `{"isError": true, "code": "PARTNER_LOOKUP_UNAVAILABLE", ...}` or `Merchant authorization is unavailable` | SureBright could not reach its partner registry; retry |
