List stores

curl --request GET \
  --url https://api.example.com/stores

{
  "data": [
    {
      "id": "downtown-kitchen",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "brand_id": "0001",
      "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": [{
                  "monday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "sunday": { "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": []
    }
  ]
}

GET

stores

List stores

curl --request GET \
  --url https://api.example.com/stores

{
  "data": [
    {
      "id": "downtown-kitchen",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "brand_id": "0001",
      "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": [{
                  "monday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "sunday": { "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": []
    }
  ]
}

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.

Requires a Fire spark access token obtained through token exchange. The token scopes requests to the authenticated customer and merchant.

Headers

Header	Required	Description
`x-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.

Query parameters

Parameter	Required	Description
`from`	Yes	Start index (0-based).
`to`	Yes	End index (inclusive). Must be greater than or equal to `from`.
`limit`	Yes	Maximum number of records per request. 1–100. The range `to - from` cannot exceed `limit`.

Request the first page with from=0, to=24, and limit=25. For the next page, set from=25, to=49, and keep the same limit.

Request

curl "https://firespark.vercel.app/api/storefront/v1/stores?from=0&to=24&limit=25" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-brand-id: 0001"

Response

The response wraps an array of store objects in data. Each store includes location, channels (with fulfillment per channel), payments, and availability so your channel can decide where the customer can order.

{
  "data": [
    {
      "id": "downtown-kitchen",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "brand_id": "0001",
      "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": [{
                  "monday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "sunday": { "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": []
    }
  ]
}

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

contact

Field	Type	Required	Description
`email`	string	Yes	Valid email address.
`phone`	string	Yes	E.164 format (for example `+593991234567`).
`name`	string	No	Contact name.

location

| Field | Type | Required | Description | | ----- | ---- | -------- | ----------- | | latitude | number | Yes | Between -90 and 90. | | longitude | number | Yes | Between -180 and 180. | | address_line_1 | string | Yes | 3–255 characters. | | address_line_2 | string | No | 3–255 characters. | | city | string | Yes | 1–100 characters. | | country | string | Yes | 1–100 characters. | | postal_code | string | Yes | Numeric only. 4–10 digits. | | business_name | string | Yes | Legal or trade name. 1–100 characters. | | unit_number | string | No | Numeric only. 1–10 digits. |

channels

A map of channel codes to channel configuration. Each entry contains:

Field	Type	Description
`id`	string	External channel identifier.
`uid`	string (UUID)	Fire spark channel identifier.
`name`	string	Display name.
`fulfillment`	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.

pricing

Field	Type	Description
`is_tax_inclusive`	boolean	Whether listed prices include tax.
`minimum_order_value`	number	Minimum order amount. ≥ 0.
`maximum_order_value`	number	Maximum order amount. 0–1,000,000.
`tax_rate`	number	Tax rate as a decimal (for example `0.15` for 15%). 0–1.
`fees`	array	Additional fees applied to orders.

Each fee object:

Field	Type	Description
`id`	string	External fee identifier.
`type`	string	`FIXED` or `PERCENTAGE`.
`tax_inclusive`	boolean	Whether the fee includes tax.
`name`	object	Localized label keyed by locale (for example `en_us`).
`description`	object	Optional localized description.
`amount`	number	Fixed amount when `type` is `FIXED`. ≥ 0.
`percentage`	number	Rate when `type` is `PERCENTAGE`. 0–1.

availability

Field	Type	Description
`status`	string	`OPEN`, `CLOSED`, or `TEMPORARILY_CLOSED`.
`schedules`	array \| null	Weekly hour maps keyed by day name (`monday` through `sunday`). `null` when there is no schedule restriction.
`temporary_closed_reason`	object	Localized reason when temporarily closed.
`temporary_closed_until`	string	ISO 8601 datetime when the temporary closure ends.

Each schedule map is keyed by day name (monday through sunday). Include only the days the store operates. Each day:

Field	Type	Description
`start_time`	string	ISO time (for example `09:00:00`).
`end_time`	string	ISO time (for example `22:00:00`).

fulfillment

Field	Type	Description
`uid`	string (UUID)	Fire spark fulfillment identifier.
`id`	string	External fulfillment identifier.
`type`	string	Fulfillment type code (for example `DELIVERY`, `PICKUP`).
`name`	string	Display name.
`instructions`	object	Optional localized customer instructions.
`pricing`	object	Pricing rules for this fulfillment type.
`coverage_zones`	array	Delivery or service areas.
`availability`	object	Operating hours and status.

Coverage zone:

Field	Type	Description
`name`	string	Zone label.
`type`	string	`RADIUS` or `POLYGON`.
`radius_info`	object	Required when `type` is `RADIUS`. Contains `latitude`, `longitude`, and `radius` (meters, 0–100,000).
`polygon_info`	object	Required when `type` is `POLYGON`. Contains `polygon`, an array of `{ latitude, longitude }` points.

payments

Field	Type	Description
`orderable`	boolean	Whether the store accepts orders.
`methods`	array	Accepted payment methods.

Each payment method:

Field	Type	Description
`method`	string	`CREDIT`, `DEBIT`, `CASH`, `BANK_TRANSFER`, or `OTHER`.
`minimum_order_value`	number	Minimum order for this method. ≥ 0.
`maximum_order_value`	number	Maximum order for this method. 0–1,000,000.
`providers`	array	Payment providers for this method.

Each provider:

Field	Type	Description
`id`	string (UUID)	Provider identifier.
`name`	string	Provider display name.
`status`	string	`ACTIVE` or `INACTIVE`.

cms

Present only when cms_template_id is not null. Contains the resolved CMS template assigned to the store.

Field	Type	Description
`id`	string (UUID)	Template identifier. Matches `cms_template_id`.
`name`	string	Template name. 1–100 characters.
`entity`	string	Always `STORES` for store responses.
`status`	string	`ACTIVE` or `INACTIVE`.
`fields`	array	Template fields with their current stored values.

Each field in fields:

Field	Type	Description
`name`	string	Field key.
`type`	string	`TEXT`, `SELECT`, `IMAGE`, or `LIST`.
`label`	object	Optional localized label keyed by locale.
`required`	boolean	Whether the field is required.
`placeholder`	string	Optional placeholder text.
`options`	array	For `SELECT` fields — objects with `label` and `value`.
`altText`	string	For `IMAGE` fields — alternative text.
`src`	string	For `IMAGE` fields — image URL.
`href`	string	For `IMAGE` fields — optional link URL.
`value`	varies	Current stored value for this store. Omitted when empty.

overrides

Scheduled changes that take effect at a future date. Each override contains:

Field	Type	Description
`start_date`	string	ISO 8601 datetime when the override becomes active.
`changes`	object	Partial store configuration to apply. Includes `contact`, `location`, `timezone`, `channels`, `payments`, and `cms_template_id`.

Error responses

Status	Description
`400`	Invalid pagination parameters. `from` must be ≤ `to`, and `to - from` must not exceed `limit`.
`401`	Missing or invalid access token.
`403`	Token does not have access to this merchant’s stores.

Get channel List nearby stores

⌘I

​Headers

​Query parameters

​Request

​Response

​Store object

​Error responses

Headers

Query parameters

Request

Response

Store object

Error responses