List the merchant's stores

Merchant → store → connector. V1 returns one store; the model permits many.

GET/stores

Authorization

AuthorizationBearer token (JWT) · headerrequired

JWT issued by the external IdP via the OAuth 2.0 authorization-code flow (Kinde in production; a simulator in test). The client obtains it and sends it as a Bearer token on every authenticated call. Sarvex's services verify it — issuer, audience, signature (IdP JWKS), expiry — and read identity and tenant from its claims. Sarvex does not issue or revoke these tokens. merchant_id/store_id are read from the verified claims (and the merchant→store mapping), never from the URL. The operator scope is required for /operator/*. Operators acting on a specific merchant pass the X-Operate-As header, which is recorded in the audit log.

Responses

200

Stores owned by the caller's merchant.

datastore[]required

Show properties

Array of store

store_idstring

namestring

platformplatform

Connectable commerce backends: WooCommerce and Magento. The model and enum extend to further platform types without structural change.

Allowed:woocommercemagento

domainstring

The store's brand domain where /.well-known/ucp is served.

connector_idstring | null

journey_statejourney_state

Allowed:connectedsyncedreadylive

ucp_stateobject

The store's UCP activation state, projected onto the store record for convenience. GET /stores/{store_id}/activation is the full view. Distinct from journey_state, which remains the operator-facing concierge funnel.

Show properties

object

declared_capabilitiesucp_capability[]

UCP capabilities/extensions this store currently declares (negotiated subset of the catalogue).

open_task_countinteger

Open tasks owned by the merchant for this store (capped at 100). Drives the header store switcher's "N for you" badge.

blockedboolean

True if this store has an open task that blocks checkout. Takes priority over open_task_count in the store switcher badge.

pagepagerequired

Show properties

cursorstring | nullrequired

has_morebooleanrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Request

curl -X GET "https://api.sarvex.example.com/v1/stores" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.sarvex.example.com/v1/stores", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "https://api.sarvex.example.com/v1/stores",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "data": [
    {
      "store_id": "string",
      "name": "string",
      "platform": "woocommerce",
      "domain": "string",
      "connector_id": "string",
      "journey_state": "connected",
      "ucp_state": "draft",
      "declared_capabilities": [
        "catalog"
      ],
      "open_task_count": 0,
      "blocked": true
    }
  ],
  "page": {
    "cursor": "string",
    "has_more": true
  }
}