Update Store configuration

What this endpoint does

Replace the community's Store and widget settings, then confirm that every submitted value was saved.

INFO

Workflow

Update settings → read Store settings

Quick start

Use the environment selected by Try it. The example values are synthetic.

Authentication and permission

Send	Permission	Community scope
`Authorization: Bearer <apiKey>`	`store`	Community scope is derived from the key; do not send a community identifier.

Complete examples

{
  "isEnabled": true,
  "title": "Agent Test Store",
  "description": "<p>Synthetic Store documentation example.</p>",
  "cover": {
    "isEnabled": false,
    "light": "",
    "dark": ""
  },
  "currency": {
    "isEnabled": false,
    "name": "Coins",
    "light": "",
    "dark": ""
  },
  "widget": {
    "isEnabled": true,
    "allowedDomains": [
      "store-agent.example.invalid"
    ],
    "accessMode": "development",
    "testUsers": [],
    "testRoles": [],
    "size": {
      "mode": "dynamic",
      "width": 400,
      "height": 400
    },
    "appearance": {
      "light": {
        "name": "agent-light",
        "palette": {
          "accent": "#167A5A"
        }
      },
      "dark": {
        "name": "agent-dark",
        "palette": {
          "accent": "#62D2A2"
        }
      },
      "useCommunityTheme": false
    },
    "callToAction": {
      "isEnabled": false,
      "text": "",
      "link": ""
    },
    "userIdentifierFields": [
      {
        "id": "email",
        "field": "email",
        "label": "Email",
        "type": "default",
        "dataAttribute": "data-email"
      }
    ]
  }
}

Success and readback

Branch on: meta.code = STORE_CONFIGURATION_UPDATED

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "STORE_CONFIGURATION_UPDATED"
  },
  "message": "Update Store configuration successfully",
  "data": {
    "isEnabled": true,
    "title": "Agent Test Store",
    "description": "<p>Synthetic Store documentation example.</p>",
    "cover": {
      "isEnabled": false,
      "light": "",
      "dark": ""
    },
    "currency": {
      "isEnabled": false,
      "name": "Coins",
      "light": "",
      "dark": ""
    },
    "widget": {
      "isEnabled": true,
      "allowedDomains": [
        "store-agent.example.invalid"
      ],
      "accessMode": "development",
      "testUsers": [],
      "testRoles": [],
      "size": {
        "mode": "dynamic",
        "width": 400,
        "height": 400
      },
      "appearance": {
        "light": {
          "name": "agent-light",
          "palette": {
            "accent": "#167A5A"
          }
        },
        "dark": {
          "name": "agent-dark",
          "palette": {
            "accent": "#62D2A2"
          }
        },
        "useCommunityTheme": false
      },
      "callToAction": {
        "isEnabled": false,
        "text": "",
        "link": ""
      },
      "userIdentifierFields": [
        {
          "id": "email",
          "field": "email",
          "label": "Email",
          "type": "default",
          "dataAttribute": "data-email"
        }
      ]
    }
  }
}

CHECK

Readback

Read back with GET /stores and verify every submitted setting persisted.

Errors and recovery

Branch on meta.code, never message text.

HTTP	Machine code	What the caller should do	Retry?
400	`VALIDATION_FAILED`	Repair the field-keyed `detail` map; no settings persist.	No, fix first
401	`AUTH_API_KEY_REQUIRED`	Add the Authorization header.	No, fix first
401	`AUTH_API_KEY_INVALID`	Replace or rotate the key.	No, fix first
401	`AUTH_API_KEY_VALIDATION_FAILED`	Authentication could not be completed.	Yes, with backoff
403	`AUTH_PERMISSION_REQUIRED`	Request the store permission; no resource data is returned.	No, fix first
409	`STORE_RESOURCE_CONFLICT`	Re-read current settings before retrying.	After reconciliation
502	`STORE_DEPENDENCY_UNAVAILABLE`	Retry after a short backoff; the Store dependency is unavailable.	Yes, with backoff
500	`INTERNAL_ERROR`	Retry with exponential backoff and the same request context, then escalate.	Yes, with backoff

Retry safety

WARNING

Exact retry

The same complete body is idempotent. Re-read before retrying a conflict.

Gotchas

Avoid this mistake

Next steps

Read Store configuration

Continue with the next operation in the connected Store lifecycle.

curl --location --request PUT 'https://sgtr-api.returning.ai/v1/stores' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "isEnabled": true, "title": "Agent Test Store", "description": "<p>Synthetic Store documentation example.</p>", "cover": { "isEnabled": false, "light": "", "dark": "" }, "currency": { "isEnabled": false, "name": "Coins", "light": "", "dark": "" }, "widget": { "isEnabled": true, "allowedDomains": [ "store-agent.example.invalid" ], "accessMode": "development", "testUsers": [], "testRoles": [], "size": { "mode": "dynamic", "width": 400, "height": 400 }, "appearance": { "light": { "name": "agent-light", "palette": { "accent": "#167A5A" } }, "dark": { "name": "agent-dark", "palette": { "accent": "#62D2A2" } }, "useCommunityTheme": false }, "callToAction": { "isEnabled": false, "text": "", "link": "" }, "userIdentifierFields": [ { "id": "email", "field": "email", "label": "Email", "type": "default", "dataAttribute": "data-email" } ] } }'

{ "meta": { "status": "success", "statusCode": 200, "code": "STORE_CONFIGURATION_UPDATED" }, "message": "Update Store configuration successfully", "data": { "isEnabled": true, "title": "Agent Test Store", "description": "<p>Synthetic Store documentation example.</p>", "cover": { "isEnabled": false, "light": "", "dark": "" }, "currency": { "isEnabled": false, "name": "Coins", "light": "", "dark": "" }, "widget": { "isEnabled": true, "allowedDomains": [ "store-agent.example.invalid" ], "accessMode": "development", "testUsers": [], "testRoles": [], "size": { "mode": "dynamic", "width": 400, "height": 400 }, "appearance": { "light": { "name": "agent-light", "palette": { "accent": "#167A5A" } }, "dark": { "name": "agent-dark", "palette": { "accent": "#62D2A2" } }, "useCommunityTheme": false }, "callToAction": { "isEnabled": false, "text": "", "link": "" }, "userIdentifierFields": [ { "id": "email", "field": "email", "label": "Email", "type": "default", "dataAttribute": "data-email" } ] }, "widgetID": "650906d314a3e564c56f3450" } }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps