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 are running low. For more information, 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. Currently, count is supported. | 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.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"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 more information, see AddOrUpdateReport event.
AddOrUpdateReport event example
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"payloadVersion": "3",
"messageId": "<message id>"
},
"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 more information about change reports, see Understand State Reporting.
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. | 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": "<message id>",
"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"
}
}
}
