> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get preferences

> Resolve every merchant preference domain against the current storefront scope in one request.

Loads cached merchant preferences once, then resolves availability, analytics, prep time, order rules, and the channel release gate against the optional menu scope before returning. Clients should prefetch this payload at startup and reuse it for the unavailable screen, the minimum-version screen, and analytics session timeout.

> [!NOTE]
>
> Requires a Fire spark access token obtained through [token
> exchange](https://firespark.cloud/docs/storefront-api/oauth/exchange/post.md). This endpoint does not block
> other Storefront API calls.

Raw rules live on `merchants.preferences`. This endpoint never returns the rule trees — only the matched effect for the current scope.

* **availability** — Any matching enabled rule makes the storefront `UNAVAILABLE`. Empty conditions match every scope. Scheduled rules use `start_date` (inclusive) and `end_date` (exclusive).
* **analytics** — Session inactivity timeout as stored plus `session_ms`.
* **prep\_time** — First matching prep-time rule for the scope, or the fallback effect.
* **order\_rules** — First matching order and redeem limit effects for the scope, or the fallback effects.
* **release** — Channel minimum version and store URLs for the current `env` + `channel_id`. `min_version` is `null` when no gate is configured.

`availability.next_change_at` is the soonest future `start_date` or `end_date` among enabled scheduled availability rules. Use it to refetch when a window opens or closes.

Kiosk clients subscribe to `availability.changed` on the workspace realtime topic after [issuing a token](https://firespark.cloud/docs/storefront-api/realtime/token/post.md). The payload is `{ merchant_id }`. This event also fires when `preferences.releases` changes. App clients refetch this endpoint on foreground instead of opening a realtime connection. Web clients ignore `release`.

## Query parameters

| Parameter | Required | Description |
| - | - | - |
| `fulfillment_id` | No | External fulfillment identifier. Same format as [Get menus](https://firespark.cloud/docs/storefront-api/menus/get.md). |
| `store_id` | No | External store identifier. |
| `channel_id` | No | External channel identifier. |
| `brand_id` | No | External brand identifier. |

## Request

```bash theme={null}
curl "https://firespark.cloud/api/storefront/v1/preferences?channel_id=kiosk&store_id=downtown" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

## Response

| Field | Description |
| - | - |
| `availability.status` | `AVAILABLE` or `UNAVAILABLE`. |
| `availability.next_change_at` | ISO datetime of the next scheduled window change, or `null`. |
| `availability.rule` | Present when `UNAVAILABLE`. Includes `id`, `title`, `description`, `schedule`. |
| `analytics.session` | Stored timeout `{ value, unit }` (`s`, `min`, or `h`). |
| `analytics.session_ms` | Same timeout in milliseconds. |
| `prep_time` | Matched prep-time effect (`strategy`, `value`, `unit`). |
| `order_rules.order` | Matched item and total limits. |
| `order_rules.redeems` | Matched redeem limits. |
| `release.min_version` | Required app version, or `null` when the gate is off. |
| `release.title` | Blocking-screen heading. |
| `release.description` | Blocking-screen body. |
| `release.ios_store_url` | App Store URL, or empty. |
| `release.android_store_url` | Play Store URL, or empty. |
| `country` | Merchant ISO 3166-1 alpha-2 country (e.g. `EC`). Restricts map address search. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.