Managing inventory

The Inventory API registers and updates your physical inventory — locations (stores, with zones) and the devices (screens) deployed in them.

Concepts

Location — a physical store, optionally divided into zones.
Device — a screen deployed at a location (and zone).
Upsert — every write is an idempotent create-or-update keyed on identity, so sending the same payload again simply reconciles state rather than creating duplicates.

How references resolve

References between resources resolve by metadata.id by default. Prefix a value with externalid: (e.g. "id": "externalid:3886") to resolve by your own external id instead. A device’s location / zone references must point to locations and zones you created previously.

Two ways to write

Combined upsert — location + device in one call

POST /v1alpha/inventory/mgmt:upsert upserts a location and a device together. If the location upsert fails, the device is not attempted and its outcome reports FAILED_PRECONDITION.

POST /v1alpha/inventory/mgmt:upsert HTTP/1.1
Host: api.dev.retailmedia.verve.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...
X-Verve-Namespace: project:01ABCDEFGHIJKLMNOPQRSTUVWX
Content-Type: application/json

{
  "location": { "metadata": { "name": "Store 123", "id": "externalid:store-123" } },
  "device":   { "metadata": { "name": "Screen A",  "id": "externalid:screen-a" } }
}

The response reports a per-resource outcome — an independent status plus the upserted resource — for the location and the device.

Dedicated endpoints

When you only need one resource type, locations and devices each have their own endpoints:

Resource	Upsert	List
Locations	`POST /v1alpha/inventory/locations:upsert`	`POST /v1alpha/inventory/locations`
Devices	`POST /v1alpha/inventory/devices:upsert`	`POST /v1alpha/inventory/devices`

Both also support Get (GET …/{id}), Create (PUT), Update (PATCH), and more.

For full request and response schemas, see the Inventory API reference.