CMS Managed Devices
#
This document describes how CMS platforms can programmatically manage devices within an organisation using the upsertCMSDevice GraphQL mutation.
1. Overview
#
CMS platforms can manage devices by:
- Creating new devices - Register a device with a platform-provided ID
- Updating existing devices - Modify device settings by referencing the same platform-provided ID
- Assigning locations and cloudshelves - Link devices to specific locations and cloudshelf configurations
The platformProvidedId field acts as the unique identifier for upsert operations. If a device with the given ID exists, it will be updated; otherwise, a new device is created.
2. Prerequisites
#
Authentication:
Your API key must have the DEVICE MODIFY permission to use this mutation.
Note: This mutation is only available via API key authentication. It cannot be used with user session authentication.
3. Create or Update a Device
#
The upsertCMSDevice mutation handles two scenarios:
Input Fields:
platformProvidedId name locationId null to unassign) cloudshelfId null to unassign) deviceMode INTERACTIVE , DISPLAY_ONLY , or HYBRID attributes 4. Smart Defaults for New Devices
#
When creating a new device, the following defaults are applied automatically:
deviceMode INTERACTIVE if not specified locationId cloudshelfId Note: These defaults only apply when creating new devices. Updating an existing device will not change these fields unless explicitly provided.
5. Example Mutations
#
Create a new device with minimal fields:
Create a device with all fields specified:
Update an existing device:
Unassign a device from its location:
6. Success Response
#
7. Device Modes
#
INTERACTIVE DISPLAY_ONLY HYBRID 8. Error Handling
#
The mutation returns a userErrors array containing any errors that occurred.
Common Error Codes:
ACTION_DISALLOWED ENTITY_NOT_FOUND ENTITY_INVALID_FIELD LIVE_LOCATIONS_LIMIT_REACHED DEVICES_PER_LOCATION_LIMIT_REACHED Example Error Response:
Example - Location Not Found:
Example - Live Locations Limit Reached:
Example - Devices Per Location Limit Reached:
9. Subscription Limits
#
New device creation is subject to your organisation's subscription limits. If the limit is reached, the mutation will return an ACTION_DISALLOWED error.
To check if you can register a new device before attempting, use the canRegisterDevice query:
This returns true if the organisation can register additional devices, or false if the limit has been reached.
10. Device Location Constraints
#
Before assigning a device to a location, you can query the available capacity using the deviceLocationConstraints query. This provides detailed information about subscription limits and per-location availability.
Query:
When moving an existing device, pass the device ID to get accurate availability (the device's current location won't count against the limit):
Response Fields:
maxLiveLocations maxDevicesPerLocation currentLiveLocations discoveryAllocationUsed discoveryLocationId locations Per-Location Fields:
locationId locationName retailerDeviceCount canAssignRetailerDevice true if a device can be assigned here isDiscoveryLocation true if this location uses the discovery allocation disabledReason canAssignRetailerDevice is false Example Response:
Discovery Allocation:
Each organisation is allowed one "discovery" allocation - a single location can exceed the per-location device limit by one device. This allows for testing or temporary expansion at one location. The allocation is reflected in the following fields:
discoveryAllocationUsed:truewhen one location has an extra device beyond the normal limitdiscoveryLocationId: The GlobalID of the location using this extra allocationisDiscoveryLocation: Per-location flag indicating which location has the allocation
Once the discovery allocation is in use at one location, other locations cannot exceed their per-location device limit.
Managed Users
About Plugins