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.

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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.

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.

Copied to clipboard.

{  
  "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.

Copied to clipboard.

{  
  "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"
    }
  }
}