StylorDocs

Update widget settings

patch/v1/widget/settings

enabled: false hides every widget (the chat and complete the look) on every store from the next page view; an open chat hides itself on its next message. It is not cached anywhere. The chat API called without a widget session is unaffected.

holdoutPercent sets the share of visits that never see the chat widget, a whole number from 0 to 50. Any change of share ends the running test and starts a new one with a new id (visits split at one share cannot be pooled with another); the ended test moves to pastHoldouts, newest first, and its results stay readable. 0 ends the test. The same share again changes nothing.

Private keyapi.v1.widget.settings.updateNo demo

Request body

application/jsonrequired
enabledboolean

Show the widgets (true) or hide them everywhere (false).

holdoutPercentinteger

The share of visits kept from the chat widget, in percent. 0 ends the test.

min: 0max: 50

Response

200The settings after the change.
enabledbooleanrequired

false when every widget is switched off.

WidgetHoldout | nullnullablerequired

The running holdout test, or null.

Option 1: WidgetHoldout

idstringrequired

The test.

percentintegerrequired

The share of visits kept from the chat widget.

startedAtstring (date-time)required

When the test started.

endedAtstring (date-time)

When it ended. Only on pastHoldouts.

Option 2: null

array<WidgetHoldout>required

Tests that ended, newest first (the last 20).

idstringrequired

The test.

percentintegerrequired

The share of visits kept from the chat widget.

startedAtstring (date-time)required

When the test started.

endedAtstring (date-time)

When it ended. Only on pastHoldouts.

Errors

22

Every error is JSON with a single error string unless noted. Match on the status code; the message is for humans.

400
Request body must be valid JSON.

The body is not parseable JSON.

409
The holdout changed while this was being saved. Load the settings again and retry.

Another change to the holdout was saved at the same moment.

422
Validation failed.

Neither field was sent, enabled is not a boolean, or holdoutPercent is not a whole number from 0 to 50. details names each.

curl -X PATCH "https://stylor.ai/api/v1/widget/settings" \
  -H "Authorization: Bearer $STYLOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'
Response · 200
{
  "enabled": true,
  "holdout": {
    "id": "hold_3f9a1c2b7d4e5f60",
    "percent": 10,
    "startedAt": "2026-11-04T12:00:00.000Z"
  },
  "pastHoldouts": []
}