> ## 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.
# List stores
> List merchant locations available for ordering in your channel.
Returns a paginated list of stores a customer can order from. Use this endpoint to show location pickers or browse the full store catalog. To find stores near the customer, use [list stores by coordinates](/docs/storefront-api/stores/nearby/get).
Requires a Fire spark access token obtained through [token
exchange](/docs/storefront-api/oauth/exchange/post). The token scopes requests to the
authenticated customer and merchant.
## Query parameters
| Parameter | Type | Default | Description |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `brand_id` | No | Filter stores by brand. External brand identifier — alphanumeric characters, `_`, and `-` only. 1–64 characters. When omitted, all stores for the merchant are returned. | |
| `limit` | integer | `20` | Maximum stores per page. Minimum `1`, maximum `100`. |
| `cursor` | string | — | Cursor from `pagination.next_cursor` of a previous response. Omit on the first page. |
Request the first page with `limit=20`. Pass `pagination.next_cursor` as the
`cursor` query parameter until `next_cursor` is `null`.
## Request
```bash theme={null}
curl "https://firespark.cloud/api/storefront/v1/stores?brand_id=0001&limit=20" \
-H "Authorization: Bearer ACCESS_TOKEN"
```
## Response
The response wraps a page of store objects in `data` and pagination metadata in `pagination`. Each store includes location, channels (with fulfillment per channel), payments, and availability so your channel can decide where the customer can order.
```json Success theme={null}
{
"data": [
{
"id": "downtown-kitchen",
"uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"brand_id": "0001",
"organization_id": "11111111-1111-1111-1111-111111111111",
"merchant_id": "22222222-2222-2222-2222-222222222222",
"name": "Downtown Kitchen",
"status": "ACTIVE",
"timezone": "America/Guayaquil",
"contact": {
"email": "downtown@merchant.com",
"phone": "+593991234567",
"name": "Downtown Kitchen"
},
"location": {
"latitude": -2.1894,
"longitude": -79.8891,
"address_line_1": "Av. 9 de Octubre 123",
"city": "Guayaquil",
"country": "Ecuador",
"postal_code": "090101",
"business_name": "Downtown Kitchen S.A."
},
"channels": {
"APP": {
"id": "app-channel",
"uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Mobile app",
"fulfillment": {
"DELIVERY": {
"uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"id": "delivery",
"type": "DELIVERY",
"name": "Delivery",
"instructions": { "en_us": "Ring the bell at the side entrance." },
"pricing": {
"is_tax_inclusive": false,
"minimum_order_value": 10,
"maximum_order_value": 200,
"tax_rate": 0.15,
"fees": [
{
"id": "delivery-fee",
"type": "FIXED",
"tax_inclusive": false,
"name": { "en_us": "Delivery fee" },
"amount": 2.5,
"percentage": 0
}
]
},
"coverage_zones": [
{
"name": "Downtown",
"type": "RADIUS",
"radius_info": {
"latitude": -2.1894,
"longitude": -79.8891,
"radius": 5000
}
}
],
"availability": {
"status": "OPEN",
"schedules": [
{ "day_of_week": "monday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "tuesday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "wednesday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "thursday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "friday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "saturday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "sunday", "periods": [{ "start_time": "10:00:00", "end_time": "23:00:00" }] }
]
}
}
}
}
},
"payments": {
"orderable": true,
"methods": [
{
"method": "CREDIT",
"minimum_order_value": 0,
"maximum_order_value": 500,
"providers": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "Stripe",
"status": "ACTIVE"
}
]
}
]
},
"cms_template_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"cms": {
"id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"name": "Store landing page",
"entity": "STORES",
"status": "ACTIVE",
"fields": [
{
"name": "hero_title",
"type": "TEXT",
"label": { "en_us": "Hero title" },
"required": true,
"value": "Welcome to Downtown Kitchen"
}
]
},
"overrides": []
}
],
"pagination": {
"next_cursor": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"prev_cursor": null
}
}
```
When there are no more pages, `pagination.next_cursor` is `null`. On the first page, `pagination.prev_cursor` is `null`.
## Store object
| Field | Type | Description |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | string | External store identifier in your systems. Alphanumeric, `_`, and `-` only. 1–64 characters. |
| `uid` | string (UUID) | Fire spark internal identifier. |
| `brand_id` | string \| null | External brand identifier. `null` when the resource is not brand-scoped. |
| `organization_id` | string (UUID) | Fire spark organization identifier. |
| `merchant_id` | string (UUID) | Fire spark merchant identifier. |
| `name` | string | Display name. 1–100 characters. |
| `status` | string | `ACTIVE` or `INACTIVE`. |
| `timezone` | string | IANA timezone for schedules and overrides. |
| `contact` | object | Store contact details. |
| `location` | object | Physical address and coordinates. |
| `channels` | object | Channel-specific fulfillment configuration keyed by channel code. Each channel contains a `fulfillment` map. |
| `payments` | object | Accepted payment methods and order limits. |
| `cms_template_id` | string (UUID) | CMS template linked to this store. `null` when no template is assigned. |
| `cms` | object | Read-only. `null` when `cms_template_id` is `null`. When set, the resolved CMS template for this store, including field definitions and stored values. |
| `overrides` | array | Scheduled configuration changes. |
| Field | Required | Type | Description |
| ------- | -------- | ------ | ------------------------------------------- |
| `email` | Yes | string | Valid email address. |
| `phone` | Yes | string | E.164 format (for example `+593991234567`). |
| `name` | No | string | Contact name. |
| Field | Required | Type | Description |
| ---------------- | -------- | ------ | -------------------------------------- |
| `latitude` | Yes | number | Between -90 and 90. |
| `longitude` | Yes | number | Between -180 and 180. |
| `address_line_1` | Yes | string | 3–255 characters. |
| `address_line_2` | No | string | 3–255 characters. |
| `city` | Yes | string | 1–100 characters. |
| `country` | Yes | string | 1–100 characters. |
| `postal_code` | Yes | string | Numeric only. 4–10 digits. |
| `business_name` | Yes | string | Legal or trade name. 1–100 characters. |
| `unit_number` | No | string | Numeric only. 1–10 digits. |
A map of channel codes to channel configuration. Each entry contains:
| Field | Required | Type | Description |
| ------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `id` | Yes | string | External channel identifier. |
| `uid` | Yes | string (UUID) | Fire spark channel identifier. |
| `name` | Yes | string | Display name. |
| `fulfillment` | Yes | object | Map of fulfillment types available on this channel. Each key is a fulfillment code (for example `DELIVERY`, `PICKUP`). |
Each fulfillment entry requires `uid`, `id`, `type`, `name`, `pricing`, `coverage_zones`, and `availability`. Optional `instructions` as a localized object.
| Field | Required | Type | Description |
| --------------------- | -------- | ------- | -------------------------------------------------------- |
| `is_tax_inclusive` | Yes | boolean | Whether listed prices include tax. |
| `minimum_order_value` | No | number | Minimum order amount. ≥ 0. |
| `maximum_order_value` | No | number | Maximum order amount. 0–1,000,000. |
| `tax_rate` | Yes | number | Tax rate as a decimal (for example `0.15` for 15%). 0–1. |
| `fees` | No | array | Additional fees applied to orders. |
Each fee object:
| Field | Required | Type | Description |
| --------------- | -------- | ------- | ------------------------------------------------------ |
| `id` | Yes | string | External fee identifier. |
| `type` | Yes | string | `FIXED` or `PERCENTAGE`. |
| `tax_inclusive` | No | boolean | Whether the fee includes tax. |
| `name` | Yes | object | Localized label keyed by locale (for example `en_us`). |
| `description` | No | object | Optional localized description. |
| `amount` | No | number | Fixed amount when `type` is `FIXED`. ≥ 0. |
| `percentage` | No | number | Rate when `type` is `PERCENTAGE`. 0–1. |
| Field | Required | Type | Description |
| ------------------------- | -------- | ------------- | ------------------------------------------------------------------------------------------------ |
| `status` | Yes | string | `OPEN`, `CLOSED`, or `TEMPORARILY_CLOSED`. |
| `schedules` | No | array \| null | Schedule entries with `day_of_week` and `periods`. `null` when there is no schedule restriction. |
| `temporary_closed_reason` | No | object | Localized reason when temporarily closed. |
| `temporary_closed_until` | No | string | ISO 8601 datetime when the temporary closure ends. |
Each schedule entry contains `day_of_week` (`monday` through `sunday`) and a `periods` array. Each period has optional `closed` (default `false`), `start_time`, `end_time`, and optional `start_date` / `end_date` bounds.
| Field | Required | Type | Description |
| ---------------- | -------- | ------------- | --------------------------------------------------------- |
| `uid` | Yes | string (UUID) | Fire spark fulfillment identifier. |
| `id` | Yes | string | External fulfillment identifier. |
| `type` | Yes | string | Fulfillment type code (for example `DELIVERY`, `PICKUP`). |
| `name` | Yes | string | Display name. |
| `instructions` | No | object | Optional localized customer instructions. |
| `pricing` | Yes | object | Pricing rules for this fulfillment type. |
| `coverage_zones` | Yes | array | Delivery or service areas. |
| `availability` | Yes | object | Operating hours and status. |
Coverage zone:
| Field | Required | Type | Description |
| -------------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `name` | Yes | string | Zone label. |
| `type` | Yes | string | `RADIUS` or `POLYGON`. |
| `radius_info` | No | object | Required when `type` is `RADIUS` (otherwise omit). Contains `latitude`, `longitude`, and `radius` (meters, 0–100,000). |
| `polygon_info` | No | object | Required when `type` is `POLYGON` (otherwise omit). Contains `polygon`, an array of `{ latitude, longitude }` points. |
| Field | Required | Type | Description |
| ----------- | -------- | ------- | --------------------------------- |
| `orderable` | Yes | boolean | Whether the store accepts orders. |
| `methods` | Yes | array | Accepted payment methods. |
Each payment method:
| Field | Required | Type | Description |
| --------------------- | -------- | ------ | ------------------------------------------------------- |
| `method` | Yes | string | `CREDIT`, `DEBIT`, `CASH`, `BANK_TRANSFER`, or `OTHER`. |
| `minimum_order_value` | No | number | Minimum order for this method. ≥ 0. |
| `maximum_order_value` | No | number | Maximum order for this method. 0–1,000,000. |
| `providers` | No | array | Payment providers for this method. |
Each provider:
| Field | Required | Type | Description |
| -------- | -------- | ------------- | ----------------------- |
| `id` | Yes | string (UUID) | Provider identifier. |
| `name` | Yes | string | Provider display name. |
| `status` | Yes | string | `ACTIVE` or `INACTIVE`. |
Present only when `cms_template_id` is not `null`. Contains the resolved CMS template assigned to the store.
| Field | Required | Type | Description |
| -------- | -------- | ------------- | ------------------------------------------------- |
| `id` | Yes | string (UUID) | Template identifier. Matches `cms_template_id`. |
| `name` | Yes | string | Template name. 1–100 characters. |
| `entity` | Yes | string | Always `STORES` for store responses. |
| `status` | Yes | string | `ACTIVE` or `INACTIVE`. |
| `fields` | Yes | array | Template fields with their current stored values. |
Each field in `fields`:
| Field | Required | Type | Description |
| ------------- | -------- | ------- | -------------------------------------------------------- |
| `name` | Yes | string | Field key. |
| `type` | Yes | string | `TEXT`, `SELECT`, `IMAGE`, or `LIST`. |
| `label` | No | object | Optional localized label keyed by locale. |
| `required` | No | boolean | Whether the field is required. |
| `placeholder` | No | string | Optional placeholder text. |
| `options` | No | array | For `SELECT` fields — objects with `label` and `value`. |
| `altText` | No | string | For `IMAGE` fields — alternative text. |
| `src` | No | string | For `IMAGE` fields — image URL. |
| `href` | No | string | For `IMAGE` fields — optional link URL. |
| `value` | No | varies | Current stored value for this store. Omitted when empty. |
Scheduled changes that take effect at a future date. Each override contains:
| Field | Required | Type | Description |
| ------------ | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `start_date` | Yes | string | ISO 8601 datetime when the override becomes active. |
| `changes` | Yes | object | Partial store configuration to apply. Includes `contact`, `location`, `timezone`, `channels`, `payments`, and `cms_template_id`. |
## Error responses
| Status | Description |
| ------ | ----------------------------------------------------- |
| `400` | Invalid query parameters. |
| `401` | Missing or invalid access token. |
| `403` | Token does not have access to this merchant's stores. |
## OpenAPI
````yaml storefront-api/openapi.json GET /stores
openapi: 3.0.1
info:
title: Fire spark Storefront API
description: Customer-facing channel endpoints for Fire spark.
version: 1.0.0
servers:
- url: https://firespark.cloud/api/storefront/v1
security:
- bearerAuth: []
paths:
/stores:
get:
summary: List stores
parameters:
- in: query
name: brand_id
required: false
schema:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
description: >-
Filter stores by brand. When omitted, all stores for the merchant
are returned.
- in: query
name: limit
required: false
schema:
type: integer
maximum: 100
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Store'
components:
schemas:
Store:
type: object
properties:
id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
uid:
type: string
format: uuid
name:
type: string
status:
type: string
enum:
- ACTIVE
- INACTIVE
location:
type: object
channels:
type: object
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````