Update store configuration

Updates the current community store configuration aggregate for the API-key's community and persists widget settings as part of the same operation.

Use this when a partner integration needs to save storefront display settings, currency labels, store copy, cover images, and widget configuration in one full update.

Authentication:

Bearer API key in Authorization header

API key must have the store permission

Community is resolved from the API key token — do not pass communityID

Returns 401 if the key is missing, invalid, or expired

Returns 403 if the key does not include the store permission

Side effects:

Publishes update:store-config to the store service

The store service updates _store_configs

The store service auto-creates or updates the community's _widgets document for the store widget

Internal widgetID linkage remains service-only and is not exposed in the partner response

Rate limits:

Standard API rate limits apply

Constraints:

The request body is a full replacement-style store configuration update

title is required when isEnabled is true and is limited to 32 characters

Cover and currency image values must be HTTPS URLs or empty strings

Widget size width and height must be zero or greater

Widget identifiers such as widgetID and widget._id must not be sent by clients

Upstream store-service failures return 502

Example — update:

{
  "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": []
  }
}

Related endpoints:

GET /stores

curl --location --request PUT 'https://sgtr-integration.returning.ai/apis/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 } }

Request

Responses