Alexa.InventoryUsageSensor Interface 3
Implement the Alexa.InventoryUsageSensor
capability interface so that you can report the amount of a consumable product that your device has used. For example, if your device is a coffee maker that uses coffee pods, you can report the number of pods that your device used to date. You can implement multiple instances of Alexa.InventoryUsageSensor
for multiple consumable products, such as a coffee maker with coffee pods and milk or creamer pods.
If you report the quantity of a consumable product remaining in your device, implement the Alexa.InventoryLevelSensor
interface instead. If your device contains a consumable product that has an unknown lifespan, implement the Alexa.InventoryLevelUsageSensor
interface instead.
For the list of languages that the Alexa.InventoryUsageSensor
interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Dash replenishment IDs
You can add the Amazon Dash Replenishment Service to your smart home device to enable Alexa to monitor and reorder supplies or replacement parts for your device. When you report inventory with Alexa.InventoryUsageSensor
, your customers can track supply levels within the Alexa app and receive notifications from Alexa when supplies run low or parts need replacement. Also, customers can set up automatic reordering of these supplies. For example, a printer can report ink usage to Alexa so that the customer doesn't run out of ink.
For details, see About Dash Replenishment.
When you register your device for Dash replenishment, Amazon supplies a replenishment ID for each consumable product in your device. The replenishment ID identifies the products that the customer can order to replace the consumed product. You can provide these IDs to Alexa in the following ways:
- If you already have your replenishment IDs at the time of device discovery, provide them in your discovery response.
- You can provide your replenishment IDs later in an
AddOrUpdateReport
message.
Reportable properties
The Alexa.InventoryUsageSensor
interface doesn't define any reportable properties.
Discovery
You describe endpoints that support Alexa.InventoryUsageSensor
by using the standard discovery mechanism described in Alexa.Discovery
.
For the full list of display categories, see display categories.
Capabilities array
In addition to the usual discovery response fields, for each Alexa.InventoryUsageSensor
entry in the capabilities array, include the following fields.
Field | Description | Type |
---|---|---|
instance |
Name of the sensor: Examples: CoffeePod or DetergentPod . |
String |
measurement |
Way you measure the consumable product. One of count, volume, or weight. For volume and weight, include the unit of measure. |
Object |
replenishment |
The Dash replenishment ID for the consumable product. | Object |
capabilityResources |
Friendly names that customers can use to interact with the sensor. | CapabilityResources object |
Discover response example
The following example shows a Discover.Response
message for a coffee maker that supports the Alexa.InventoryUsageSensor
interface.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [
{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Coffee Maker Plus",
"description": "Smart Coffee Maker by Coffee Maker Plus",
"friendlyName": "Coffee maker",
"displayCategories": [
"OTHER"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryUsageSensor",
"instance": "Sensor.CoffeePod",
"version": "3",
"configuration": {
"measurement": {
"@type": "Count"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "replenishment ID for refill options"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Coffee pods",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Capsules de café",
"locale": "fr-FR"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"retrievable": true,
"proactivelyReported": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
AddOrUpdateReport
You must proactively send an Alexa.Discovery.AddOrUpdateReport
message if the feature support of your endpoint changes. For example, if you don't have the replenishment IDs for your consumable products at the time of initial device discovery, you can provide the replenishment IDs to Alexa later by sending an AddOrUpdateReport
message. For details, see AddOrUpdateReport
event.
AddOrUpdateReport event example
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [
{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Coffee Maker Plus",
"description": "Smart Coffee Maker by Coffee Maker Plus",
"friendlyName": "Coffee maker",
"displayCategories": [
"OTHER"
],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryUsageSensor",
"instance": "Sensor.CoffeePod",
"version": "3",
"configuration": {
"measurement": {
"@type": "Count"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "replenishment ID for refill options"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Coffee pods",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "Capsules de café",
"locale": "fr-FR"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Inventory update events
The Alexa.InventoryUsageSensor
interface defines the following events that you use to update the inventory.
ChangeReport
When you implement the Alexa.InventoryUsageSensor
interface, you send InventoryConsumed
events instead of the typical ChangeReport
event. For details about change reports, see Understand State and Change Reporting.
ChangeReport
events for other interfaces that you support, such as Alexa.PowerController
. For details, see the documentation for each interface that you support.InventoryConsumed event
To report inventory proactively to Alexa, send an InventoryConsumed
event and include the amount of the consumable products that your device has already consumed. You send the event to the Alexa event gateway.
messageId
in the header of your events must be unique, as described in Header
object.InventoryConsumed event example
In the following example you notify Alexa after the user has consumed a coffee pod.
{
"event": {
"header": {
"namespace": "Alexa.InventoryUsageSensor",
"name": "InventoryConsumed",
"instance": "Sensor.CoffeePod",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"usage": {
"@type": "Count",
"value": 1
},
"timeOfSample": "2020-09-23T16:20:50Z"
}
}
}
InventoryConsumed event payload
Field | Description | Type | Required |
---|---|---|---|
usage |
Amount of the consumable product that has been used, expressed as a count, volume, or weight. For volume and weight, include the unit of measure. | Object | Yes |
timeOfSample |
Time the inventory was consumed, specified in UTC. Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ . |
String | Yes |
Related topics
Last updated: Oct 19, 2022