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

Begin connecting a store

Creates a connector in pairing state for the store and returns a one-time pairing code for the plugin. Store-scoped like every other per-store resource: a merchant may have several stores, so the store cannot be inferred from the bearer. The store must belong to the caller’s merchant (404 otherwise).

POST/stores/{store_id}/connectors/pairing
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.

Path parameters
store_idstringrequired

A store the caller's merchant owns. Authorized server-side against the principal; not a free-form tenant selector.

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
Responses
201

Connector created in pairing state.

connector_idstring
store_idstring

The store this connector belongs to (merchant → store → connector).

platformplatform

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

Allowed:woocommercemagento
connector_typeconnector_type

What a connector record is for. commerce is the store's commerce backend and the only kind the checkout path calls. Absent on records written before the discriminator existed, which read as commerce.

Allowed:commerce
statusstring
Allowed:pairinghealthydegradeddown
sync_modelstring
Allowed:realtimepoll
last_signal_atstring<date-time> | null
last_full_sync_atstring<date-time> | null
last_heartbeat_atstring<date-time> | null
freshness_warningboolean
plugin_versionstring | null
profile_servingobject

Health of the plugin's Role 2 — serving /.well-known/ucp at the merchant origin. (The plugin serves only the profile; it does not proxy the UCP API.)

Show properties
profile_route_okboolean

Profile is being served with a 200 at the merchant domain.

last_profile_served_atstring<date-time> | null
serving_from_cacheboolean

Plugin is serving last-known-good because Sarvex was unreachable.

advertised_endpointstring | null

The services.endpoint the profile advertises — points at Sarvex (e.g. https://api.sarvex.example.com/ucp/v1/{store}).

pairing_codestring

One-time code the merchant pastes into the plugin. Shown once.

404

Resource not found within the caller's tenant.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
422

Request body failed validation.

errorobjectrequired
Show properties
codestringrequired
messagestringrequired
detailsobject | null
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST "https://api.sarvex.example.com/v1/stores/string/connectors/pairing" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "woocommerce"
}'
Response
{
  "connector_id": "string",
  "store_id": "string",
  "platform": "woocommerce",
  "connector_type": "commerce",
  "status": "pairing",
  "sync_model": "realtime",
  "last_signal_at": "2019-08-24T14:15:22Z",
  "last_full_sync_at": "2019-08-24T14:15:22Z",
  "last_heartbeat_at": "2019-08-24T14:15:22Z",
  "freshness_warning": true,
  "plugin_version": "string",
  "profile_serving": {
    "profile_route_ok": true,
    "last_profile_served_at": "2019-08-24T14:15:22Z",
    "serving_from_cache": true,
    "advertised_endpoint": "string"
  },
  "pairing_code": "string"
}