List stores
curl --request GET \
--url https://firespark.cloud/api/storefront/v1/stores \
--header 'Authorization: Bearer <token>'import requests
url = "https://firespark.cloud/api/storefront/v1/stores"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://firespark.cloud/api/storefront/v1/stores', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://firespark.cloud/api/storefront/v1/stores",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://firespark.cloud/api/storefront/v1/stores"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://firespark.cloud/api/storefront/v1/stores")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://firespark.cloud/api/storefront/v1/stores")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"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
}
}
Stores
List stores
List merchant locations available for ordering in your channel.
GET
/
stores
List stores
curl --request GET \
--url https://firespark.cloud/api/storefront/v1/stores \
--header 'Authorization: Bearer <token>'import requests
url = "https://firespark.cloud/api/storefront/v1/stores"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://firespark.cloud/api/storefront/v1/stores', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://firespark.cloud/api/storefront/v1/stores",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://firespark.cloud/api/storefront/v1/stores"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://firespark.cloud/api/storefront/v1/stores")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://firespark.cloud/api/storefront/v1/stores")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"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
}
}
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.
Each fee object:
Each schedule entry contains
Coverage zone:
Each payment method:
Each provider:
Requires a Fire spark access token obtained through token
exchange. 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
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 indata 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.
{
"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. |
contact
contact
| Field | Required | Type | Description |
|---|---|---|---|
email | Yes | string | Valid email address. |
phone | Yes | string | E.164 format (for example +593991234567). |
name | No | string | Contact name. |
location
location
| 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. |
channels
channels
A map of channel codes to channel configuration. Each entry contains:
Each fulfillment entry requires
| 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). |
uid, id, type, name, pricing, coverage_zones, and availability. Optional instructions as a localized object.pricing
pricing
| 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. |
| 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. |
availability
availability
| 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. |
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.fulfillment
fulfillment
| 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. |
| 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. |
payments
payments
| Field | Required | Type | Description |
|---|---|---|---|
orderable | Yes | boolean | Whether the store accepts orders. |
methods | Yes | array | Accepted payment methods. |
| 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. |
| Field | Required | Type | Description |
|---|---|---|---|
id | Yes | string (UUID) | Provider identifier. |
name | Yes | string | Provider display name. |
status | Yes | string | ACTIVE or INACTIVE. |
cms
cms
Present only when
Each field in
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. |
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. |
overrides
overrides
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. |
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Filter stores by brand. When omitted, all stores for the merchant are returned.
Required string length:
1 - 64Pattern:
^[a-zA-Z0-9_-]+$Required range:
x <= 100Response
200 - application/json
Ok
Show child attributes
Show child attributes
⌘I