List stores

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

{
  "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": [{
                  "monday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "sunday": { "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": []
    }
  ]
}

GET

stores

List stores

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

{
  "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": [{
                  "monday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "sunday": { "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": []
    }
  ]
}

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 Authorize to obtain a token.

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.

Request

curl "https://firespark.vercel.app/api/integrations/v1/stores" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-brand-id: 0001"

Response

The response wraps an array of store objects in data. Each store includes the full operational configuration: contact, location, channels (with fulfillment per channel), payments, CMS template metadata, and scheduled overrides.

{
  "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": [{
                  "monday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "sunday": { "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": []
    }
  ]
}

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.

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

Error responses

Status	Description
`401`	Missing or invalid access token.
`403`	Token does not include the `stores:read` scope.

Update product Upsert stores

⌘I

​Headers

​Request

​Response

​Store object

​Mapping stores to your POS

​Error responses

Headers

Request

Response

Store object

Mapping stores to your POS

Error responses