> ## 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
> Read store configuration for POS and RMS location mapping.
Returns all stores configured for the authenticated merchant. Use this endpoint to map Fire spark stores to locations in your POS or RMS before syncing menus and injecting orders.
Requires an access token with the `stores:read` scope. See
[Token](/docs/integrations-api/oauth/token/post) to obtain a token.
## Request
```bash theme={null}
curl "https://firespark.cloud/api/integrations/v1/stores?brand_id=0001&limit=20" \
-H "Authorization: Bearer ACCESS_TOKEN"
```
## Query parameters
| Parameter | Type | Default | Description |
| ---------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `brand_id` | string | — | 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. |
## Response
The response wraps a page of store objects in `data` and pagination metadata in `pagination`. Each store includes the full operational configuration: contact, location, channels (with fulfillment per channel), payments, CMS template metadata, and scheduled overrides.
```json Success theme={null}
{
"data": [
{
"id": "pos-location-01",
"uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"organization_id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
"merchant_id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
"brand_id": "0001",
"name": "Main Street",
"status": "ACTIVE",
"timezone": "America/Guayaquil",
"contact": {
"email": "main@merchant.com",
"phone": "+593991234567",
"name": "Main Street"
},
"location": {
"latitude": -2.1894,
"longitude": -79.8891,
"address_line_1": "Calle Principal 456",
"city": "Guayaquil",
"country": "Ecuador",
"postal_code": "090101",
"business_name": "Main Street Restaurant"
},
"channels": {
"UBER_EATS": {
"id": "uber-eats-main",
"uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "Uber Eats",
"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": 8,
"maximum_order_value": 300,
"tax_rate": 0.15,
"fees": []
},
"coverage_zones": [
{
"name": "City center",
"type": "RADIUS",
"radius_info": {
"latitude": -2.1894,
"longitude": -79.8891,
"radius": 8000
}
}
],
"availability": {
"status": "OPEN",
"schedules": [
{ "day_of_week": "monday", "periods": [{ "start_time": "08:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "tuesday", "periods": [{ "start_time": "08:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "wednesday", "periods": [{ "start_time": "08:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "thursday", "periods": [{ "start_time": "08:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "friday", "periods": [{ "start_time": "08:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "saturday", "periods": [{ "start_time": "08:00:00", "end_time": "23:00:00" }] },
{ "day_of_week": "sunday", "periods": [{ "start_time": "08: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": "Datafast",
"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 Main Street"
}
]
},
"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 POS or RMS. Alphanumeric, `_`, and `-` only. 1–64 characters. Unique per merchant. |
| `uid` | string (UUID) | Fire spark internal identifier. |
| `organization_id` | string (UUID) | Organization that owns the merchant. |
| `merchant_id` | string (UUID) | Merchant the store belongs to. |
| `brand_id` | string | External brand identifier. Alphanumeric characters, `_`, and `-` only. 1–64 characters. Optional — `null` when the merchant operates under a single brand. |
| `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 | Per-channel fulfillment configuration keyed by channel code. Each channel contains a `fulfillment` map. |
| `payments` | object | 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 | Store configuration to apply. Includes `contact`, `location`, `timezone`, `channels`, `payments`, and `cms_template_id`. |
## Mapping stores to your POS
Match the `id` field to the location identifier in your POS or RMS. Fire spark uses this external ID to route menu sync and order injection to the correct site.
Store `uid` values are stable Fire spark identifiers. Use `id` for
cross-system mapping and `uid` when referencing stores in other Fire spark API
calls. For pagination, pass `pagination.next_cursor` as the `cursor` query
parameter until `next_cursor` is `null`.
## Error responses
| Status | Description |
| ------ | ----------------------------------------------- |
| `401` | Missing or invalid access token. |
| `403` | Token does not include the `stores:read` scope. |
## OpenAPI
````yaml integrations-api/openapi.json GET /stores
openapi: 3.0.1
info:
title: Fire spark Integrations API
description: POS and RMS integration endpoints for Fire spark.
version: 1.0.0
servers:
- url: https://firespark.cloud/api/integrations/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: >-
External brand identifier. Alphanumeric characters, _, and - only.
1–64 characters.
- in: query
name: cursor
required: false
schema:
type: string
format: uuid
description: >-
Opaque cursor from a previous response. Pass
`pagination.next_cursor` to fetch the next page.
- in: query
name: limit
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Maximum number of stores to return. Defaults to 20.
responses:
'200':
description: Ok
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/StoreUpsert'
pagination:
type: object
properties:
next_cursor:
type: string
format: uuid
nullable: true
prev_cursor:
type: string
format: uuid
nullable: true
components:
schemas:
StoreUpsert:
type: object
required:
- id
- name
- status
- timezone
- contact
- location
properties:
id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
brand_id:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-zA-Z0-9_-]+$
name:
type: string
status:
type: string
enum:
- ACTIVE
- INACTIVE
timezone:
type: string
contact:
type: object
location:
type: object
channels:
type: object
additionalProperties: true
payments:
type: object
cms_template_id:
type: string
format: uuid
nullable: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````