Alexa.InventoryLevelSensor Interface 3

Implement the Alexa.InventoryLevelSensor interface in your Alexa skill so that you can report the amount of a consumable product that your device has remaining. For example, if your device is a printer, you can report the amount of ink or toner that the printer has remaining. You can implement multiple instances of Alexa.InventoryLevelSensor for multiple consumable products, such as a printer with separate storage for cyan, yellow, magenta, and black ink or toner.

If you report when your device uses a consumable product, implement the Alexa.InventoryUsageSensor interface instead. If the consumable product that you track has an unknown lifespan, implement the Alexa.InventoryLevelUsageSensor interface instead.

For the list of languages that the Alexa.InventoryLevelSensor 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.InventoryLevelSensor, 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.InventoryLevelSensor interface uses the level property to represent the current amount of a consumable product that a device has remaining.

You can express level as one of the following types: count, percentage, volume, or weight. For volume and weight, you include the unit of measure.

An endpoint can support multiple sensors, so you must always include the instance attribute for a level property. You identify your instance names in your discovery response.

Level property example

Copied to clipboard.

{
  "namespace": "Alexa.InventoryLevelSensor",
  "instance": "InkSensor.Cyan",
  "name": "level",
  "value": {
    "@type": "Volume",
    "value": 5,
    "unit": "MILLILITER"
  }
}

Discovery

You describe endpoints that support Alexa.InventoryLevelSensor by using the standard discovery mechanism described in Alexa.Discovery.

Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report.

For the full list of display categories, see display categories.

Capabilities array

In addition to the usual discovery response fields, for each Alexa.InventoryLevelSensor entry in the capabilities array, include the following fields.

Field Description Type
instance Name of the sensor.
Examples: Ink.Cyan or Ink.Yellow.		 String
markdown="span">`measurement` Way you measure the consumable product.
One of count, percentage, volume, or weight. For volume and weight, include the unit of measure.		 Object
replenishment 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 printer that supports the Alexa.InventoryLevelSensor interface.

Copied to clipboard.

{
  "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": "Printer Plus",
          "description": "Smart Printer by Printer Maker Plus",
          "friendlyName": "Printer",
          "displayCategories": [
            "OTHER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.InventoryLevelSensor",
              "instance": "InkSensor.Cyan",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "level"
                  }
                ],
                "retrievable": false,
                "proactivelyReported": true
              },
              "configuration": {
                "measurement": {
                  "@type": "Volume",
                  "unit": "MILLILITER"
                },
                "replenishment": {
                  "@type": "DashReplenishmentId",
                  "value": "replenishment ID for refill options"
                }
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Cyan ink",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Encre cyan",
                      "locale": "fr-FR"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.InventoryLevelSensor",
              "instance": "PaperSensor.FrontTray",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "level"
                  }
                ],
                "retrievable": false,
                "proactivelyReported": true
              },
              "configuration": {
                "measurement": {
                  "@type": "Count"
                },
                "replenishment": {
                  "@type": "DashReplenishmentId",
                  "value": "replenishment ID for refill options"
                }
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Front tray",
                      "locale": "en-US"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": 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

Copied to clipboard.

{
  "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": "Printer Plus",
          "description": "Smart Printer by Printer Maker Plus",
          "friendlyName": "Printer",
          "displayCategories": [
            "OTHER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.InventoryLevelSensor",
              "instance": "InkSensor.Cyan",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "level"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "configuration": {
                "measurement": {
                  "@type": "Volume",
                  "unit": "MILLILITER"
                },
                "replenishment": {
                  "@type": "DashReplenishmentId",
                  "value": "replenishment ID for refill options"
                }
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Cyan ink",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Encre cyan",
                      "locale": "fr-FR"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.InventoryLevelSensor",
              "instance": "PaperSensor.FrontTray",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "level"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "configuration": {
                "measurement": {
                  "@type": "Count"
                },
                "replenishment": {
                  "@type": "DashReplenishmentId",
                  "value": "replenishment ID for refill options"
                }
              },
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Front tray",
                      "locale": "en-US"
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Change reporting

To report inventory proactively to Alexa, you send a ChangeReport event and include the remaining levels of each consumable product. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

ChangeReport event example

In the following example, you notify Alexa about the remaining levels of each consumable product after a daily check of all sensors.

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.InventoryLevelSensor",
            "instance": "InkSensor.Cyan",
            "name": "level",
            "value": {
              "@type": "Volume",
              "value": 5,
              "unit": "MILLILITER"
            },
            "timeOfSample": "2019-10-31T17:00:00Z",
            "uncertaintyInMilliseconds": 0
          },
          {
            "namespace": "Alexa.InventoryLevelSensor",
            "instance": "PaperSensor.FrontTray",
            "name": "level",
            "value": {
              "@type": "Count",
              "value": 200
            },
            "timeOfSample": "2019-10-31T17:00:00Z",
            "uncertaintyInMilliseconds": 0
          },
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2019-10-31T17:00:00Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "namespace": "Alexa.EndpointHealth",
    "name": "connectivity",
    "value": {
      "value": "OK"
    },
    "timeOfSample": "2019-10-31T17:00:00Z",
    "uncertaintyInMilliseconds": 0
  }
}