Upsert kiosk devices

Send an array of kiosk devices. Each item creates a device or updates the one that already uses its external id. Send only the fields you want to change. Omitted fields stay as they are.

Requires an access token with the kiosk:write scope. See Token to obtain a token.

Each item id is yours. Fire spark does not derive it from the store and alias. Creating a device requires channel_id, store_id, alias, and device_code. The channel must be a kiosk channel. The store must already exist. Fire spark generates a pairing_code, sets status to LINKED, and copies the channel default app tracks. A soft-deleted id can be created again as a new device. An existing device accepts any subset of those fields plus settings_overrides. Changing store_id or alias notifies the tablet so it reloads its configuration. Status, health, software, enrollment, and secrets are reported by the tablet and are not writable here. device_code is stored uppercase and must be at least 8 characters. alias must be unique within the store. settings_overrides.disabled_payment_ids replaces the whole list. An empty array enables every payment the channel allows. Omit settings_overrides to leave the current list unchanged.

Request

curl -X PUT "https://firespark.cloud/api/integrations/v1/kiosk/devices" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "counter-1",
      "channel_id": "kioscos",
      "store_id": "downtown",
      "alias": "Counter 1",
      "device_code": "tablet01",
      "settings_overrides": {
        "disabled_payment_ids": ["cash-desk"]
      }
    },
    {
      "id": "counter-2",
      "alias": "Counter 2"
    }
  ]'

Body

An array of 1 to 100 items. Each item takes these fields:

Field	Required on create	Description
`id`	yes, always	External device identifier. Alphanumeric characters, `_`, and `-` only. 1–64 characters.
`channel_id`	yes	External id of a kiosk channel.
`store_id`	yes	External store identifier.
`alias`	yes	Name shown in the dashboard. Unique per store.
`device_code`	yes	Code shown on the tablet. Minimum 8 characters. Stored uppercase.
`settings_overrides.disabled_payment_ids`	no	Payment configuration ids disabled on this device.

Response

Zod validates the entire body before saving. If any field is invalid, HTTP 400 is returned and no items are saved. When the body is valid, items are saved one after another. HTTP 200 only when every item is saved. If a later item hits a business error, HTTP is that item’s status (422 or 500).

Field	Description
`id`	The item `id`. `null` when it was missing or invalid.
`status`	`200` when saved. `422` when a create is missing channel, store, alias, or device code, when the channel or store does not exist, or when the device code, alias, or id is already in use. `500` for an unexpected failure.
`data`	The saved device, same shape as Get kiosk device. Only when `status` is `200`.
`error`	Error message. Only when `status` is not `200`.
`details`	Error details for item-level failures.

{
  "data": [
    {
      "id": "counter-1",
      "status": 200,
      "data": {
        "id": "counter-1",
        "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "channel_id": "kioscos",
        "store_id": "downtown",
        "alias": "Counter 1",
        "pairing_code": "K7M2QX",
        "device_code": "TABLET01",
        "settings_overrides": { "disabled_payment_ids": ["cash-desk"] },
        "status": "LINKED",
        "app_update_status": "UNKNOWN",
        "can_operate": false,
        "is_online": false,
        "app_presence": "UNKNOWN"
      }
    },
    {
      "id": "counter-2",
      "status": 422,
      "error": "Channel, store, alias, and device code are required",
      "details": null
    }
  ]
}

{
  "error": "Invalid fields",
  "details": {
    "0.alias": "Required"
  }
}

Error responses

Status	Description
`400`	The body is not an array of 1 to 100 items, or any item has invalid fields. No items are saved.
`401`	Missing or invalid access token.
`403`	Token does not include the `kiosk:write` scope.

API Documentation

Endpoints

Guides

Resources

Upsert kiosk devices

Request

Body

Response

Error responses

​Request

​Body

​Response

​Error responses

Request

Body

Response

Error responses