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

# Upsert kiosk devices

> Create or update up to 100 kiosk devices by external identifier in one request.

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.

> [!NOTE]
>
> Requires an access token with the `kiosk:write` scope. See
> [Token](https://firespark.cloud/docs/integrations-api/oauth/token/post.md) 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

```bash theme={null}
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](https://firespark.cloud/docs/integrations-api/kiosk/devices/\[id]/get). Only when `status` is `200`. |
| `error` | Error message. Only when `status` is not `200`. |
| `details` | Error details for item-level failures. |

```json Success theme={null}
{
  "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
    }
  ]
}
```

```json Invalid fields theme={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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.