Skip to content
SarvexDocs
Esc
↑↓navigate↵open⌘Jpreview

Create a store under a merchant

Operator equivalent of POST /stores, usable during provisioning. Creates the store (no connector yet); its journey starts at the beginning. Pairing follows via POST /connectors.

POST/operator/merchants/{merchant_id}/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.

Scopes:operator
Path parameters
merchant_idstringrequired
Header parameters
Idempotency-Keystring

Client-generated key; replays return the original result.

Request body
requiredapplication/json
platformplatformrequired

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

Allowed:woocommercemagento
namestringrequired
Responses
201

Store created.

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.

403

Authenticated but not permitted (e.g. non-operator on an operator route).

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST "https://api.sarvex.example.com/v1/operator/merchants/string/stores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "woocommerce",
  "name": "string"
}'
Response
{
  "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
}