Alexa.InventoryLevelUsageSensor Interface
Implement the Alexa.InventoryLevelUsageSensor interface in your Alexa skill so that you can report the approximate usage of a consumable installed in your device. For example, if your device is a vacuum cleaner, you can report the approximate health of the dust filter. You can implement multiple instances of InventoryLevelUsageSensor for multiple consumables, such as a vacuum with a dust filter and a brush.
If you report the quantity of a consumable remaining in your device, implement the InventoryLevelSensor interface instead. If you report when your device uses a consumable, implement the InventoryUsageSensor interface instead.
For the list of languages that the InventoryLevelUsageSensor 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 the remaining estimated lifespan falls below a specified threshold. For details, see What is Dash Replenishment? and Dash Replenishment Account Setup.
When you sign your device up for Dash Replenishment, you define a replenishment ID for each consumable in your device. The replenishment ID identifies what 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.InventoryLevelUsageSensor 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 InventoryLevelUsageSensor entry in the capabilities array, include the following fields.
| Field | Description | Type |
|---|---|---|
instance |
The name of the sensor, for example Sensor.DustFilter or Sensor.Brush. |
String |
configuration.measurement |
The way you measure the consumable. Valid value: Duration |
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 vacuum that supports the Alexa.InventoryLevelUsageSensor 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": "Vacuum Plus",
"description": "Smart Vacuum by Vacuum Maker Plus",
"friendlyName": "Downstairs vacuum",
"displayCategories": [
"VACUUM_CLEANER"
],
"additionalAttributes": {
"manufacturer": "Vacuum Plus",
"model" : "VPM1",
"serialNumber": "the serial number of the device",
"firmwareVersion" : "the firmware version of the device",
"softwareVersion": "the software version of the device",
"customIdentifier": "your custom identifier for the device"
},
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryLevelUsageSensor",
"instance": "Sensor.DustFilter",
"version": "3",
"configuration": {
"measurement": {
"@type": "Duration"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "<the replenishment ID for refill options>"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Dust filter",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "filtre à poussière",
"locale": "fr-FR"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryLevelUsageSensor",
"instance": "Sensor.Brush",
"version": "3",
"configuration": {
"measurement": {
"@type": "Duration"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "<the replenishment ID for refill options>"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Brush",
"locale": "en-US"
}
}
]
}
},
{
"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": "Vacuum Plus",
"description": "Smart Vacuum by Vacuum Maker Plus",
"friendlyName": "Downstairs vacuum",
"displayCategories": [
"VACUUM_CLEANER"
],
"additionalAttributes": {
"manufacturer": "Vacuum Plus",
"model" : "VPM1",
"serialNumber": "the serial number of the device",
"firmwareVersion" : "the firmware version of the device",
"softwareVersion": "the software version of the device",
"customIdentifier": "your custom identifier for the device"
},
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryLevelUsageSensor",
"instance": "Sensor.DustFilter",
"version": "3",
"configuration": {
"measurement": {
"@type": "Duration"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "<the replenishment ID for refill options>"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Dust filter",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "filtre à poussière",
"locale": "fr-FR"
}
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.InventoryLevelUsageSensor",
"instance": "Sensor.Brush",
"version": "3",
"configuration": {
"measurement": {
"@type": "Duration"
},
"replenishment": {
"@type": "DashReplenishmentId",
"value": "<the replenishment ID for refill options>"
}
},
"capabilityResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "Brush",
"locale": "en-US"
}
}
]
}
},
{
"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.InventoryLevelUsageSensor interface, you send InventoryConsumed and InventoryReplaced events instead of the ChangeReport event.
ChangeReport events for other interfaces that you support, such as Alexa.PowerController. For details, see the documentation for each interface that you support. For details about change reports, see Understand State and Change Reporting.InventoryConsumed event
Send an InventoryConsumed event to proactively report to Alexa the approximate usage of a consumable installed in your device. Report this event about one time a day.
InventoryConsumed payload details
| Field | Description | Type | Required |
|---|---|---|---|
usage |
The amount of the consumable already used, expressed as a Duration. The duration value must not be negative. | Object | Yes |
timeOfSample |
Time the sensor detected the usage level. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. |
Yes |
InventoryConsumed event example
In the following example, you notify Alexa after the device consumes 30 hours of the dust filter lifespan.
{
"event": {
"header": {
"namespace": "Alexa.InventoryLevelUsageSensor",
"name": "InventoryConsumed",
"instance": "Sensor.DustFilter",
"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": "Duration",
"value": "PT30H"
},
"timeOfSample": "2020-07-02T16:20:50.52Z"
}
}
}
InventoryReplaced event
Send an InventoryReplaced event to proactively report to Alexa after the user replaces a consumable.
InventoryReplaced payload details
| Field | Description | Type | Required |
|---|---|---|---|
replacedDate |
When the user replaced the consumable. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. |
Yes |
InventoryReplaced event example
In the following example you notify Alexa after the user has replaced the dust filter.
{
"event": {
"header": {
"namespace": "Alexa.InventoryLevelUsageSensor",
"name": "InventoryReplaced",
"instance": "Sensor.DustFilter",
"messageId": "<a unique identifier, preferably a version 4 UUID>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "endpoint ID"
},
"payload": {
"replacedDate": "2020-01-15T14:30Z"
}
}
}