# Get Store configuration

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

- Endpoint: `GET https://api.returning.ai/v1/stores`
- Section: Store and rewards / General
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `store` (Shown in the dashboard as "Store")
- Retries: Read-only; exact retries are safe
- Guide: hand-written
- Verified: live, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/store/get-store-configuration

## 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.

**Instead:** Use [List Store categories](https://docs.returning.ai/api-reference/store-categories/list-store-categories.md) instead to read the Store's shelves, or [List products](https://docs.returning.ai/api-reference/store-products/list-products.md) for its rewards.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | `string` | No | 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. (Store setting names) |
| `lang` | `string` | No | Language code for the translated title and description, such as `th`. |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `store`. (`Bearer <API_KEY>`) |

### Example request

```bash
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`.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `meta` | `object` | always | Status details. |
| `meta.status` | `string` | always | Result of the request. (`success`) |
| `meta.statusCode` | `integer` | always | The HTTP status, repeated. |
| `meta.code` | `string` | always | Machine-readable result code. (`STORE_CONFIGURATION_RETRIEVED`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | Your Store settings. |
| `data._id` | `string` | - | ID of the Store settings record. |
| `data.communityID` | `string` | - | Your community ID. |
| `data.isEnabled` | `boolean` | - | `true` when the Store is switched on. |
| `data.title` | `string` | - | Store title shown to traders. |
| `data.description` | `string` | - | Store description as HTML. |
| `data.cover` | `object` | - | Banner images at the top of the Store. |
| `data.cover.isEnabled` | `boolean` | - | `true` when the banner is shown. |
| `data.cover.light` | `string` | - | Banner image URL for light mode, or an empty string. |
| `data.cover.dark` | `string` | - | Banner image URL for dark mode, or an empty string. |
| `data.currency` | `object` | - | A custom name and icon for coins in the Store. |
| `data.currency.isEnabled` | `boolean` | - | `true` when the custom name and icon are shown. |
| `data.currency.name` | `string` | - | The custom coin name, such as `Coins`, or an empty string. |
| `data.currency.light` | `string` | - | Coin icon URL for light mode, or an empty string. |
| `data.currency.dark` | `string` | - | Coin icon URL for dark mode, or an empty string. |
| `data.widgetID` | `string` | - | ID of the Store's embeddable widget. Read-only; an update can't change it. |
| `data.widget` | `object` | - | Settings for embedding the Store on your own website. (Nullable) |
| `data.widget.isEnabled` | `boolean` | - | `true` when the widget is switched on. |
| `data.widget.allowedDomains` | `string[]` | - | Hostnames allowed to embed the widget, such as `example.com`. |
| `data.widget.accessMode` | `string` | - | `live` for every trader, `development` for the test users and roles only. (`live` or `development`) |
| `data.widget.testUsers` | `string[]` | - | IDs of the traders who can use the widget in `development` mode. |
| `data.widget.testRoles` | `string[]` | - | IDs of the roles that can use the widget in `development` mode. |
| `data.widget.size` | `object` | - | Widget size. |
| `data.widget.size.mode` | `string` | - | `dynamic` fills the space available; `fixed` uses `width` and `height`. (`dynamic` or `fixed`) |
| `data.widget.size.width` | `number` | - | Width in pixels. |
| `data.widget.size.height` | `number` | - | Height in pixels. |
| `data.widget.appearance` | `object` | - | Widget colours. |
| `data.widget.appearance.light` | `object` | - | Light-mode theme. |
| `data.widget.appearance.light.name` | `string` | - | Theme name, such as `white-smoke`. |
| `data.widget.appearance.light.palette` | `object` | - | Colour overrides, keyed by colour name. Empty when there are none. |
| `data.widget.appearance.dark` | `object` | - | Dark-mode theme. |
| `data.widget.appearance.dark.name` | `string` | - | Theme name, such as `black-beauty`. |
| `data.widget.appearance.dark.palette` | `object` | - | Colour overrides, keyed by colour name. Empty when there are none. |
| `data.widget.appearance.useCommunityTheme` | `boolean` | - | `true` when the widget uses your community's theme instead of these. |
| `data.widget.callToAction` | `object` | - | A button shown in the widget. |
| `data.widget.callToAction.isEnabled` | `boolean` | - | `true` when the button is shown. |
| `data.widget.callToAction.text` | `string` | - | Button label. |
| `data.widget.callToAction.link` | `string` | - | Button link, an HTTPS URL, or an empty string. |
| `data.widget.userIdentifierFields` | `object[]` | - | Fields the widget uses to identify the signed-in trader. |
| `data.widget.userIdentifierFields.id` | `string` | - | Field ID. |
| `data.widget.userIdentifierFields.field` | `string` | - | The source field key, such as `email`. |
| `data.widget.userIdentifierFields.label` | `string` | - | Label shown to traders. |
| `data.widget.userIdentifierFields.type` | `string` | - | Where the field comes from. (`default` or `custom`) |
| `data.widget.userIdentifierFields.dataAttribute` | `string` | - | The HTML data attribute your page sets for this field, such as `data-email`. |
| `data.widget.createdAt` | `string` | - | When the widget was created, ISO 8601 UTC. (Date-time) |
| `data.widget.updatedAt` | `string` | - | When the widget last changed, ISO 8601 UTC. (Date-time) |
| `data.widget.__v` | `integer` | - | Internal version number. You can ignore it. |
| `data.i18n` | `object` | - | Translations of the title and description. |
| `data.i18n.isTranslationEnabled` | `boolean` | - | `true` when translations are shown. |
| `data.i18n.titleTranslations` | `object[]` | - | Translated titles, one per language. |
| `data.i18n.titleTranslations.locale` | `string` | - | Language code. |
| `data.i18n.titleTranslations.content` | `string` | - | Translated title. |
| `data.i18n.titleTranslations.label` | `string` | - | Language name. |
| `data.i18n.titleTranslations.isAiGenerated` | `boolean` | - | `true` when the translation was generated automatically. |
| `data.i18n.titleTranslations.translationConfigHash` | `string` | - | Fingerprint of the settings an automatic translation used. You can ignore it. |
| `data.i18n.descriptionTranslations` | `object[]` | - | Translated descriptions, one per language. |
| `data.i18n.descriptionTranslations.locale` | `string` | - | Language code. |
| `data.i18n.descriptionTranslations.content` | `string` | - | Translated description. |
| `data.i18n.descriptionTranslations.label` | `string` | - | Language name. |
| `data.i18n.descriptionTranslations.isAiGenerated` | `boolean` | - | `true` when the translation was generated automatically. |
| `data.i18n.descriptionTranslations.translationConfigHash` | `string` | - | Fingerprint of the settings an automatic translation used. You can ignore it. |
| `data.i18n.translationPrompt` | `string` | when set | Extra guidance for automatic translations, when set. |
| `data.i18n.translationIgnoreList` | `string[]` | when set | Terms automatic translations keep unchanged, when set. |
| `data.createdAt` | `string` | - | When the Store settings were created, ISO 8601 UTC. (Date-time) |
| `data.updatedAt` | `string` | - | When the Store settings last changed, ISO 8601 UTC. (Date-time) |
| `data.__v` | `integer` | - | Internal version number. You can ignore it. |

### Example response (200)

```json
{
  "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 request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | `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. |
| 401 | `AUTH_API_KEY_REQUIRED` | No key was sent. Send `Authorization: Bearer <API_KEY>`. |
| 401 | `AUTH_API_KEY_INVALID` | The key is unknown, expired or malformed. Use a current Community API key. |
| 403 | `AUTH_PERMISSION_REQUIRED` | The key lacks `store`. Add the permission in Settings > Integration > API Keys. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 502 | `STORE_DEPENDENCY_UNAVAILABLE` | The Store is briefly unavailable. Retry the same request with exponential backoff. |
| 500 | `INTERNAL_ERROR` | Retry the same request with exponential backoff. If it keeps failing, contact Returning.AI with the time of the request. |
| 401 | `AUTH_API_KEY_VALIDATION_FAILED` | The key could not be checked just now. Retry with backoff; the key itself may be fine. |

**Retries:** This endpoint is read-only, so retrying the exact same request is safe after a network error, a `500` or a `502`. Use bounded exponential backoff. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Update Store configuration](https://docs.returning.ai/api-reference/store/update-store-configuration.md): `PUT /v1/stores`. Change a setting, sending back everything you just read with your change applied.
- [See the Store's shelves with List Store categories](https://docs.returning.ai/api-reference/store-categories/list-store-categories.md): `GET /v1/categories`.