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 /v1/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 errors[]; 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
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://api.returning.ai/v1/stores' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "isEnabled": true, "title": "Rewards Store", "description": "<p>Redeem community rewards.</p>", "cover": { "isEnabled": false, "light": "", "dark": "" }, "currency": { "isEnabled": false, "name": "Coins", "light": "", "dark": "" }, "widget": { "isEnabled": true, "allowedDomains": [ "example.com" ], "accessMode": "development", "testUsers": [], "testRoles": [], "size": { "mode": "dynamic", "width": 400, "height": 400 }, "appearance": { "light": { "name": "white-smoke", "palette": {} }, "dark": { "name": "black-beauty", "palette": {} }, "useCommunityTheme": false }, "callToAction": { "isEnabled": false, "text": "", "link": "" }, "userIdentifierFields": [] } }'

{ "meta": { "status": "success", "statusCode": 200 }, "message": "Update store config success.", "data": { "_id": "650a619360e8475d8ce4b2d4", "communityID": "6502c9e514a3e564c5c09c0a", "isEnabled": true, "title": "The Concept Trading update", "description": "<p>Redeem community rewards.</p>", "cover": { "isEnabled": false, "light": "", "dark": "" }, "currency": { "isEnabled": false, "name": "Coins", "light": "", "dark": "" }, "i18n": { "isTranslationEnabled": false, "titleTranslations": [], "descriptionTranslations": [], "translationPrompt": "", "translationIgnoreList": [] }, "widget": { "isEnabled": true, "allowedDomains": [], "accessMode": "live", "testUsers": [], "testRoles": [], "size": { "mode": "dynamic", "width": 400, "height": 400 }, "appearance": { "light": { "name": "violet-dream", "palette": {} }, "dark": { "name": "black-beauty", "palette": { "accent": "rgb(3, 169, 244)", "text": "rgb(0, 150, 218)", "background": "rgb(3, 23, 38)", "divider": "rgb(19, 71, 95)", "shadow": "rgba(26, 38, 43, .5)" } }, "useCommunityTheme": false }, "callToAction": { "isEnabled": false, "text": "", "link": "" }, "userIdentifierFields": [], "apiKey": "9d644e64ce43b0cfd4b428b03fb0f962f0f093078b2b618fbf1aaf7d8b668b06", "createdAt": "2026-04-15T12:41:45.223Z", "updatedAt": "2026-04-15T12:42:22.024Z", "__v": 0 }, "createdAt": "2026-04-15T12:41:45.223Z", "updatedAt": "2026-04-15T12:42:22.024Z", "__v": 0 } }

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