Alexa.InventoryUsageSensor Interface
Implement the Alexa.InventoryUsageSensor capability interface so that you can report the amount of a consumable that your device has consumed. For example, if your device is a coffee maker that uses coffee pods, you can report the number of pods that have already been used. You can implement multiple instances of InventoryUsageSensor for multiple consumables, such as a coffee maker with coffee pods and milk or creamer pods.
If you report the quantity of a consumable remaining in your device, implement the InventoryLevelSensor interface instead.
For the list of languages that the InventoryUsageSensor interface supports, see List of Alexa Interfaces and Supported Languages.
Dash Replenishment IDs
By using Dash Replenishment through Alexa, the user of your device can sign up to order more of the consumable when they're running low. For details, see What is Dash Replenishment? and Dash Replenishment Account Setup.
When you sign your device up for Dash Replenishment, you set up a replenishment id for each consumable in your device. The replenishment id identifies what (one or more) products the user can order to replace the consumable. When the user sets up replenishment in their account, they choose the specific product that they want to order. Users can't set up replenishment until you provide your replenishment ids to Alexa. You can provide the replenishment ids for your device to Alexa in the following ways:
- If you already have your replenishment IDs at the time of device discovery, provide them in your discover response.
- You can provide your replenishment IDs later in an AddOrUpdateReport message.
Discovery
You describe endpoints that support Alexa.InventoryUsageSensor using the standard discovery mechanism described in Alexa.Discovery.
For the full list of display categories, see display categories.
In addition to the usual discovery response fields, for each InventoryUsageSensor entry in the capabilities array, include the following fields.
| Field | Description | Type |
|---|---|---|
instance |
The name of the sensor, for example CoffeePod or DetergentPod. |
String |
configuration.measurement |
The way you measure the consumable. One of count, volume, or weight. For volume and weight, include the unit of measure. | Object |
configuration.replenishment |
The Dash Replenishment ID for the consumable. | Object |
capabilityResources |
Friendly names that customers can use to interact with the sensor. | A CapabilityResources object. |
Discover response example
The following example shows a Discover.Response message for a coffee maker that supports the Alexa.InventoryUsageSensor interface.
messageId in the header of your events must be unique, as described in Header object.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<a 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": "<the 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 consumables 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": "<a 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": "<the 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"
}
]
}
]
}
}
}
Change reporting
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
Send an InventoryConsumed event to proactively report to Alexa the amount of a consumable that your device has already consumed.
InventoryConsumed payload details
| Field | Description | Type | Required |
|---|---|---|---|
usage |
The amount of the consumable that has been used, expressed as a count, volume, or weight. For volume and weight, include the unit of measure. | Object | Yes |
timeOfSample |
When the inventory was consumed, specified in UTC. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. |
Yes |
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": "<a unique identifier, preferably a version 4 UUID>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {
"usage": {
"@type": "Count",
"value": 1
},
"timeOfSample": "2020-09-23T16:20:50Z"
}
}
}