Update Store configuration API

When to use this

Rename the Store or change its description.
Switch the Store on or off, or show a custom coin name and icon.
Allow your website's domain to embed the Store widget, or move the widget from testing to live.

Authentication#

Header: Authorization: Bearer <API_KEY>
Permission: storeShown in the dashboard as “Store”

Send a Community API key with the store permission. The key decides the community, so you can only change your own Store and never send a community ID. Keep the key on your server.

Behaviour#

This is a full replace. isEnabled, title, description, cover, currency and widget are all required, with every field inside them, so a request that sends only a new title is rejected. Read the settings with Get Store configuration, change the fields you need, and send the rest back unchanged.

A new title or description clears the automatically generated translations of that text, because they no longer match; translations your team entered by hand are kept. Translations, the widget ID and the widget's access key can't be changed here.

Request#

Headers#

Authorization#stringREQUIRED

Community API key with store.

RuleBearer <API_KEY>

Content-Type#stringREQUIRED

Request body format.

Ruleapplication/json

Body#

Send booleans as JSON true or false; "true" is rejected. Image and link URLs must use HTTPS, or be an empty string. widgetID is rejected if you send it back from a read; other fields this endpoint doesn't take, such as i18n, _id and the timestamps, are ignored.

isEnabled#booleanREQUIRED

true switches the Store on. When true, title can't be empty.

RuleJSON boolean

Egtrue

title#stringREQUIRED

Store title shown to traders.

RuleUp to 32 chars; required when isEnabled is true

Eg"Trading Rewards Store"

description#stringREQUIRED

Store description as HTML. Send an empty string for none.

Eg"<p>Redeem your coins for trading credits and gifts.</p>"

cover#objectREQUIRED

Banner images at the top of the Store.

Eg{"isEnabled": false, "light": "", "dark": ""}

isEnabled#booleanREQUIRED

true shows the banner. Needs at least one image.

RuleJSON boolean

Egfalse

light#stringREQUIRED

Banner image URL for light mode. Send an empty string for none.

RuleHTTPS URL or empty string

dark#stringREQUIRED

Banner image URL for dark mode. Send an empty string for none.

RuleHTTPS URL or empty string

currency#objectREQUIRED

A custom name and icon for coins in the Store.

Eg{ ... }

isEnabled#booleanREQUIRED

true shows the custom coin name and icons. Needs name.

RuleJSON boolean

Egtrue

name#stringREQUIRED

The custom coin name, such as Coins. Send an empty string for none.

RuleUp to 32 chars; required when isEnabled is true

Eg"Coins"

light#stringREQUIRED

Coin icon URL for light mode. Send an empty string for none.

RuleHTTPS URL or empty string

Eg"https://cdn.example.com/store/coin-light.png"

dark#stringREQUIRED

Coin icon URL for dark mode. Send an empty string for none.

RuleHTTPS URL or empty string

Eg"https://cdn.example.com/store/coin-dark.png"

curl --request PUT \
  --url https://api.returning.ai/v1/stores \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "isEnabled": true,
    "title": "Trading Rewards Store",
    "description": "<p>Redeem your coins for trading credits and gifts.</p>",
    "cover": {
      "isEnabled": false,
      "light": "",
      "dark": ""
    },
    "currency": {
      "isEnabled": true,
      "name": "Coins",
      "light": "https://cdn.example.com/store/coin-light.png",
      "dark": "https://cdn.example.com/store/coin-dark.png"
    },
    "widget": {
      "isEnabled": true,
      "allowedDomains": ["example.com"],
      "accessMode": "live",
      "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": []
    }
  }'

Response#

A 200 returns the Store settings after the change in data, in the same shape as Get Store configuration. Branch on the HTTP status and meta.code, never on message.

meta#objectALWAYS

Status details.

Eg{ ... }

status#stringALWAYS

Result of the request.

Rulesuccess

statusCode#integerALWAYS

The HTTP status, repeated.

Eg200

code#stringALWAYS

Machine-readable result code.

RuleSTORE_CONFIGURATION_UPDATED

message#stringALWAYS

Human-readable summary. Do not branch on it.

Eg"Update store config success."

data#objectALWAYS

Your Store settings after the change, in the same shape as Get Store configuration.

Eg{ ... }

_id#string

ID of the Store settings record.

Eg"66f000000000000000000901"

communityID#string

Your community ID.

Eg"66f000000000000000000010"

isEnabled#boolean

true when the Store is switched on.

Egtrue

title#string

The stored title.

Eg"Trading Rewards Store"

description#string

The stored description.

Eg"<p>Redeem your coins for trading credits and gifts.</p>"

cover#object

Cover/banner image configuration returned for the store.

Eg{"isEnabled": false, "light": "", "dark": ""}

isEnabled#boolean

Whether banner display is enabled for the store.

Egfalse

light#string

Light-mode cover image URL. Defaults to empty string until configured.

dark#string

Dark-mode cover image URL. Defaults to empty string until configured.

currency#object

Custom currency display configuration returned for the store.

Eg{ ... }

isEnabled#boolean

Whether custom currency display is enabled.

Egtrue

name#string

Custom currency display name. Defaults to empty string until configured.

Eg"Coins"

light#string

Light-mode custom currency icon URL. Defaults to empty string until configured.

Eg"https://cdn.example.com/store/coin-light.png"

dark#string

Dark-mode custom currency icon URL. Defaults to empty string until configured.

Eg"https://cdn.example.com/store/coin-dark.png"

widgetID#string

ID of the Store's embeddable widget. Read-only.

i18n#object

Translations of the title and description. This endpoint doesn't change them, except as described under Behaviour.

Eg{ ... }

isTranslationEnabled#boolean

Whether store translations are enabled.

Egfalse

titleTranslations#object[]

Title translations. Defaults to an empty array.

Eg[]

locale#string

Translation locale code.

Eg"th"

content#string

Translated content value.

Eg"ร้านค้ารางวัล"

label#string

Language display label.

Eg"Thai"

isAiGenerated#boolean

Whether this value was generated by AI.

Egtrue

translationConfigHash#string

Translation config hash used for AI-generated content.

Eg"3f786850e387550fdab836ed7e6dc881de23001b"

descriptionTranslations#object[]

Description translations. Defaults to an empty array.

Eg[]

locale#string

Translation locale code.

Eg"th"

content#string

Translated content value.

Eg"ร้านค้ารางวัล"

label#string

Language display label.

Eg"Thai"

isAiGenerated#boolean

Whether this value was generated by AI.

Egtrue

translationConfigHash#string

Translation config hash used for AI-generated content.

Eg"3f786850e387550fdab836ed7e6dc881de23001b"

translationPrompt#string

Store-specific AI translation prompt.

Eg"Use a concise rewards-store tone."

translationIgnoreList#string[]

Terms AI translation should preserve exactly.

Eg["ReturningAI", "VIP"]

createdAt#string

Store config creation timestamp. May be omitted when using fields projection.

RuleDate-time

Eg"2026-09-01T08:30:00.000Z"

updatedAt#string

Store config last update timestamp. May be omitted when using fields projection.

RuleDate-time

Eg"2026-09-27T10:15:00.000Z"

__v#integer

Mongoose version key when selected. May be omitted when using fields projection.

Eg0

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "STORE_CONFIGURATION_UPDATED"
  },
  "message": "Update store config success.",
  "data": {
    "_id": "66f000000000000000000901",
    "communityID": "66f000000000000000000010",
    "isEnabled": true,
    "title": "Trading Rewards Store",
    "description": "<p>Redeem your coins for trading credits and gifts.</p>",
    "cover": {
      "isEnabled": false,
      "light": "",
      "dark": ""
    },
    "currency": {
      "isEnabled": true,
      "name": "Coins",
      "light": "https://cdn.example.com/store/coin-light.png",
      "dark": "https://cdn.example.com/store/coin-dark.png"
    },
    "widgetID": "66f000000000000000000902",
    "i18n": {
      "isTranslationEnabled": false,
      "titleTranslations": [],
      "descriptionTranslations": []
    },
    "widget": {
      "isEnabled": true,
      "allowedDomains": ["example.com"],
      "accessMode": "live",
      "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": [],
      "createdAt": "2026-09-01T08:30:00.000Z",
      "updatedAt": "2026-09-27T10:15:00.000Z",
      "__v": 0
    },
    "createdAt": "2026-09-01T08:30:00.000Z",
    "updatedAt": "2026-09-27T10:15:00.000Z",
    "__v": 0
  }
}

Errors#

Every error carries its code in meta.code, with the reason in detail keyed by setting name. The message on a 400 varies, so don't read it.

Fix the request04

400VALIDATION_FAILEDFix the request

A setting is missing or breaks a rule, and nothing was changed. detail names each one, for example widget must be an object, title must be shorter than or equal to 32 characters, Image URL must be an HTTPS URL or an empty string., Domain must be a valid hostname such as example.com. or widgetID is response-only and cannot be updated.

401AUTH_API_KEY_REQUIREDFix the request

No key was sent. Send Authorization: Bearer <API_KEY>.

401AUTH_API_KEY_INVALIDFix the request

The key is unknown, expired or malformed. Use a current Community API key.

403AUTH_PERMISSION_REQUIREDFix the request

The key lacks store. Add the permission in Settings > Integration > API Keys.

Retry with backoff03

502STORE_DEPENDENCY_UNAVAILABLERetry with backoff

The outcome is unknown. Read the settings with Get Store configuration, then send the update again if it didn't apply.

500INTERNAL_ERRORRetry with backoff

The outcome is unknown. Read the settings with Get Store configuration, then send the update again if it didn't apply.

401AUTH_API_KEY_VALIDATION_FAILEDRetry with backoff

The key could not be checked just now, and nothing was changed. Retry with backoff.

{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED"
  },
  "message": "Validation failed",
  "detail": {
    "title": "Store title is required when store is enabled."
  },
  "solution": "Please check the request and try again"
}

Next step#

Get Store configurationGET/v1/storesRead the settings back to confirm the change.

Organise the Store with List Store categories

Update Store configuration

When to use this

01Authentication#

02Behaviour#

03Request#

Headers#

Body#

04Response#

05Errors#

06Next step#

Authentication#

Behaviour#

Request#

Response#

Errors#

Next step#