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

Provision a new merchant (tenant)

Creates the account/tenant root. Operator-only — this is the bootstrap step that cannot use X-Operate-As because the merchant does not yet exist. Audit-logged with operator identity. Also provisions the merchant’s entry-level (self_serve) Stripe subscription with a 30-day, no-payment-method trial — a merchant account never exists without one — so this call fails as a whole if billing provisioning fails.

POST/operator/merchants
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
Header parameters
Idempotency-Keystring

Client-generated key; replays return the original result.

Request body
requiredapplication/json
namestringrequired
owner_emailstring<email>required

Used to invite the account owner and to pre-fill the entry-level trial's Stripe customer.

business_factsobject

Optional initial business facts: legal entity, support contact, etc.

Responses
201

Merchant created.

merchant_idstring
namestring
timezonestring
country_codestring

ISO 3166-1 alpha-2 country code

business_factsbusiness_facts

Facts Google requires downstream; collected at onboarding.

Show properties
legal_entity_namestring
support_emailstring<email>
support_phonestring
fulfillment_regionsstring[]
created_atstring<date-time>
locale_optionslocale_options

Reference data for the console's timezone/country selection — countries and their selectable IANA timezones. The client relies entirely on this list rather than validating country/timezone pairs itself.

Show properties
countriescountry_locale[]
Show properties
Array of country_locale
codestring

ISO 3166-1 alpha-2 country code

namestring
time_zonesstring[]
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" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "owner_email": "user@example.com",
  "business_facts": {}
}'
Response
{
  "merchant_id": "string",
  "name": "string",
  "timezone": "Australia/Sydney",
  "country_code": "AU",
  "business_facts": {
    "legal_entity_name": "string",
    "support_email": "user@example.com",
    "support_phone": "string",
    "fulfillment_regions": [
      "AU"
    ]
  },
  "created_at": "2019-08-24T14:15:22Z",
  "locale_options": {
    "countries": [
      {
        "code": "AU",
        "name": "Australia",
        "time_zones": [
          "Australia/Sydney"
        ]
      }
    ]
  }
}