Alexa.InventoryUsageSensor Interface

Implement the Alexa.InventoryUsageSensor capability interface so that you can report the amount of a consumable that your device has used. For example, if your device is a coffee maker that uses coffee pods, you can report the number of pods that your device used to date. 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. If your device contains a consumable that has an unknown lifespan, implement the InventoryLevelUsageSensor 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.

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

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

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.

Copied to clipboard.

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