Update one connection’s Storefront Bot settings

Only fields present in the body are changed. Supports Idempotency-Key header for safe retries.

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

salesChannelIdstring

The sales channel to configure: its ID, its public vc_* connection ID, or its exact name.

enabled?boolean

Master on/off switch for the public widget on this sales channel.

displayName?string

Bot name shown in the widget header. Up to 40 characters.

Lengthlength <= 40

avatarUrl?string

Avatar image URL shown in the widget. Up to 2048 characters.

Lengthlength <= 2048

personaJson?PersonaConfigDto

Persona and behavior settings. Every key is optional, so a single setting can be sent.

escalationJson?object

How the bot hands a shopper to the store team. Only the known keys are kept: enabled (boolean, default true; off hides the contact form), defaultSubject (up to 120 characters), notifyEmails (up to 5 valid addresses besides the store owner) and handoverMessage (up to 300 characters). An invalid email is rejected.

retentionJson?object

{ days }: how long conversations on this sales channel are kept, a whole number from 7 to 3650. An empty object or a days of 0 keeps them forever. A daily job deletes a conversation and its messages when its last activity is older than this; contact inquiries a chat created and anonymous analytics counters stay. Deleted data cannot be recovered.

localeJson?object

Bot language settings (enabled languages, answer language mode, translations). Stored as sent and not validated.

dailySpendCeilingUsd?number

Daily AI spend ceiling in USD for the whole store. Omitted or 0 means no ceiling. The day total across every sales channel of the store is compared with it.

Range0 <= value

curl -X PUT "https://api.brainerce.com/api/v1/storefront-bot/settings" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "salesChannelId": "vc_9f3a2b1c8d7e6f5a"
  }'

curl -X PUT "https://api.brainerce.com/api/v1/storefront-bot/settings" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "salesChannelId": "vc_9f3a2b1c8d7e6f5a"  }'

{
  "salesChannelId": "clx1a2b3c4d5e6f7g8h9",
  "connectionId": "clx1a2b3c4d5e6f7g8h9",
  "name": "Maya",
  "enabled": true,
  "displayName": "Assistant",
  "avatarUrl": "https://cdn.example.com/bot/maya.png",
  "personaJson": {
    "greeting": "string",
    "tone": "friendly",
    "accentColor": "string",
    "responseLength": "concise",
    "emoji": true,
    "bubbleShape": "rounded",
    "displayMode": "floating",
    "position": "start",
    "allowExpand": true,
    "customInstructions": "string",
    "faqs": [
      {
        "q": "string",
        "a": "string"
      }
    ],
    "capabilities": {
      "productQa": true,
      "recommendations": true,
      "orderTracking": true,
      "returns": true,
      "bundleNudges": true
    },
    "languages": [
      "en"
    ],
    "starterQuestions": [
      "string"
    ],
    "avoidTopics": "string",
    "maxDiscountPct": 0,
    "minRecommend": 0,
    "restrictLanguages": true,
    "storeFacts": true,
    "knowledgePageIds": [
      "string"
    ],
    "rules": [
      {
        "kind": "always",
        "text": "string"
      }
    ],
    "memory": {
      "enabled": true,
      "kinds": [
        "size"
      ],
      "days": 0,
      "consentMode": "ask"
    }
  },
  "escalationJson": {},
  "retentionJson": {
    "days": 0
  },
  "localeJson": {},
  "dailySpendCeilingUsd": 5
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/storefront-bot/settings"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/storefront-bot/settings"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/storefront-bot/settings"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/storefront-bot/settings"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/store"
}

Update one connection’s Storefront Bot settings

Authorization

Header Parameters

Request Body

Example default

Example default

Example default

Example default

Example default