Returning.AIDevelopers
v1

API reference / Store

.md

Get Store configuration

Read the Store settings for the community that owns your API key, including its title, banner, coin display and embeddable widget.

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/stores
Permission
store
Retries
Read-only; exact retries are safe

When to use this

  • Check whether the Store is switched on and what title traders see.
  • Fetch the current settings before you update them, because an update replaces every setting.
  • Read the widget's allowed domains and appearance before you embed the Store on your own site.

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 always get your own Store and never send a community ID. Keep the key on your server.

Request#

Query parameters#

fields#stringOPTIONAL
Comma-separated settings to return, such as title,widget. _id is always returned, and asking for widget also returns widgetID. Without it, every setting is returned.

RuleStore setting names

EgisEnabled,title,widget

lang#stringOPTIONAL
Language code for the translated title and description, such as th.

RuleLanguage code

Egen

Headers#

Authorization#stringREQUIRED
Community API key with store.

RuleBearer <API_KEY>

curl --request GET \
  --url https://api.returning.ai/v1/stores \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns every Store setting in data. Save it before an update: Update Store configuration replaces all of these settings at once, so you send back what you read with your change applied. The widget's own access key is never returned. 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_RETRIEVED

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Read store config success."

data#objectALWAYS
Your Store settings.

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
Store title shown to traders.

Eg"Trading Rewards Store"

description#string
Store description as HTML.

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

cover#object
Banner images at the top of the Store.

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

isEnabled#boolean
true when the banner is shown.

Egfalse

light#string
Banner image URL for light mode, or an empty string.
dark#string
Banner image URL for dark mode, or an empty string.
currency#object
A custom name and icon for coins in the Store.

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

isEnabled#boolean
true when the custom name and icon are shown.

Egfalse

name#string
The custom coin name, such as Coins, or an empty string.
light#string
Coin icon URL for light mode, or an empty string.
dark#string
Coin icon URL for dark mode, or an empty string.
widgetID#string
ID of the Store's embeddable widget. Read-only; an update can't change it.
widget#object
Settings for embedding the Store on your own website.

RuleNullable

Eg{ ... }

isEnabled#boolean
true when the widget is switched on.

Egfalse

allowedDomains#string[]
Hostnames allowed to embed the widget, such as example.com.

Eg[]

accessMode#string
live for every trader, development for the test users and roles only.

Rulelive or development

Eg"live"

testUsers#string[]
IDs of the traders who can use the widget in development mode.

Eg[]

testRoles#string[]
IDs of the roles that can use the widget in development mode.

Eg[]

size#object
Widget size.

Eg{"mode": "dynamic", "width": 400, "height": 400}

mode#string
dynamic fills the space available; fixed uses width and height.

Ruledynamic or fixed

Eg"dynamic"

width#number
Width in pixels.

Eg400

height#number
Height in pixels.

Eg400

appearance#object
Widget colours.

Eg{ ... }

light#object
Light-mode theme.

Eg{"name": "white-smoke", "palette": {}}

name#string
Theme name, such as white-smoke.

Eg"white-smoke"

palette#object
Colour overrides, keyed by colour name. Empty when there are none.

Eg{}

dark#object
Dark-mode theme.

Eg{"name": "black-beauty", "palette": {}}

name#string
Theme name, such as black-beauty.

Eg"black-beauty"

palette#object
Colour overrides, keyed by colour name. Empty when there are none.

Eg{}

useCommunityTheme#boolean
true when the widget uses your community's theme instead of these.

Egfalse

callToAction#object
A button shown in the widget.

Eg{"isEnabled": false, "text": "", "link": ""}

isEnabled#boolean
true when the button is shown.

Egfalse

text#string
Button label.
userIdentifierFields#object[]
Fields the widget uses to identify the signed-in trader.

Eg[]

id#string
Field ID.

Eg"email"

field#string
The source field key, such as email.

Eg"email"

label#string
Label shown to traders.

Eg"Email"

type#string
Where the field comes from.

Ruledefault or custom

Eg"default"

dataAttribute#string
The HTML data attribute your page sets for this field, such as data-email.

Eg"data-email"

createdAt#string
When the widget was created, ISO 8601 UTC.

RuleDate-time

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

updatedAt#string
When the widget last changed, ISO 8601 UTC.

RuleDate-time

Eg"2026-09-26T09:15:00.000Z"

__v#integer
Internal version number. You can ignore it.

Eg0

i18n#object
Translations of the title and description.

Eg{ ... }

isTranslationEnabled#boolean
true when translations are shown.

Egfalse

titleTranslations#object[]
Translated titles, one per language.

Eg[]

locale#string
Language code.

Eg"th"

content#string
Translated title.

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

label#string
Language name.

Eg"Thai"

isAiGenerated#boolean
true when the translation was generated automatically.

Egtrue

translationConfigHash#string
Fingerprint of the settings an automatic translation used. You can ignore it.

Eg"3f786850e387550fdab836ed7e6dc881de23001b"

descriptionTranslations#object[]
Translated descriptions, one per language.

Eg[]

locale#string
Language code.

Eg"th"

content#string
Translated description.

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

label#string
Language name.

Eg"Thai"

isAiGenerated#boolean
true when the translation was generated automatically.

Egtrue

translationConfigHash#string
Fingerprint of the settings an automatic translation used. You can ignore it.

Eg"3f786850e387550fdab836ed7e6dc881de23001b"

translationPrompt#stringWHEN SET
Extra guidance for automatic translations, when set.

Eg"Use a concise rewards-store tone."

translationIgnoreList#string[]WHEN SET
Terms automatic translations keep unchanged, when set.

Eg["ReturningAI", "VIP"]

createdAt#string
When the Store settings were created, ISO 8601 UTC.

RuleDate-time

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

updatedAt#string
When the Store settings last changed, ISO 8601 UTC.

RuleDate-time

Eg"2026-09-26T09:15:00.000Z"

__v#integer
Internal version number. You can ignore it.

Eg0

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "STORE_CONFIGURATION_RETRIEVED"
  },
  "message": "Read 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": false,
      "name": "",
      "light": "",
      "dark": ""
    },
    "widgetID": "66f000000000000000000902",
    "i18n": {
      "isTranslationEnabled": false,
      "titleTranslations": [],
      "descriptionTranslations": []
    },
    "widget": {
      "isEnabled": false,
      "allowedDomains": [],
      "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-26T09:15:00.000Z",
      "__v": 0
    },
    "createdAt": "2026-09-01T08:30:00.000Z",
    "updatedAt": "2026-09-26T09:15:00.000Z",
    "__v": 0
  }
}

Errors#

Every error carries its code in meta.code, with the reason in detail.

Fix the request04

400VALIDATION_FAILEDFix the request
fields names a setting that doesn't exist; detail lists the valid names. A 400 with message: Read store config failed. means the settings couldn't be read; retry that one with backoff.
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 Store is briefly unavailable. Retry the same request with exponential backoff.
500INTERNAL_ERRORRetry with backoff
Retry the same request with exponential backoff. If it keeps failing, contact Returning.AI with the time of the request.
401AUTH_API_KEY_VALIDATION_FAILEDRetry with backoff
The key could not be checked just now. Retry with backoff; the key itself may be fine.
{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED"
  },
  "message": "Validation failed",
  "detail": {
    "fields": "Invalid field(s): colour. Valid fields: _id, communityID, isEnabled, redemptionMethodsCutover, redemptionMethodIDs, title, description, cover, currency, i18n, spendingCap, widgetID, widget, createdAt, updatedAt, __v"
  },
  "solution": "Please check the request and try again"
}

Next step#

Update Store configurationPUT/v1/storesChange a setting, sending back everything you just read with your change applied.