Alexa.InventoryUsageSensor Interface 3

Implement the Alexa.InventoryUsageSensor capability interface so that you can report the amount of a consumable product 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 since the last report. You can implement multiple instances of Alexa.InventoryUsageSensor for multiple consumable products, such as a coffee maker with coffee pods and milk or creamer pods.

If you report the quantity of a consumable product remaining in your device, implement the Alexa.InventoryLevelSensor interface instead. If your device contains a consumable product that has an unknown lifespan, implement the Alexa.InventoryLevelUsageSensor interface instead.

For the list of languages that the Alexa.InventoryUsageSensor 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.InventoryUsageSensor, 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.
  • If you don't have the replenishment IDs at the time of device discovery, provide your replenishment IDs later in an AddOrUpdateReport event.

Properties and objects

The Alexa.InventoryUsageSensor interface includes the following properties and objects.

Reportable properties

The Alexa.InventoryUsageSensor interface doesn't define any reportable properties.

Measurement object

The Measurement object defines the way that you measure a consumable product.

Property Description Type

@type

Measurement type.
Valid values: count, volume, weight.

String

value

Amount of the consumable product used since the last report. Include when you report the usage.

String

unit

Standard of measurement for the type. Include for volume and weight only. For valid values, see volume units and weight units.

String

Replenishment object

The Replenishment object identifies the consumable product.

Property Description Type

@type

Identifies the ID type.
Valid values: DashReplenishmentId.

String

value

Dash replenishment ID for the consumable product.
You request replenishment IDs in the Dash console.

String

Discovery

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

An endpoint can support multiple sensors. To distinguish sensors, you must include the an Alexa.InventoryUsageSensor with the instance property for each sensor that you support.

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

To let Alexa know the health of your device, also implement the Alexa.EndpointHealth interface.

Capabilities array

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

Property Description Type

instance

Name of the sensor.
Examples: CoffeePod or DetergentPod.

String

configuration.measurement

Way you measure the consumable product.

Measurement object

configuration.replenishment

Dash replenishment ID for the consumable product.

Replenishment object

capabilityResources

Friendly names for the consumable product that customers can use to interact with the sensor.

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": "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": "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.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 event 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 event. You can't change the replenishment IDs after you report them the first time.

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

Inventory update events

The Alexa.InventoryUsageSensor interface defines the following events that you use to update the inventory.

ChangeReport

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

To report inventory proactively to Alexa, send an InventoryConsumed event and include the amount of the consumable products that your device has consumed since the last event. You send the event to the Alexa event gateway.

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": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "usage": {
        "@type": "Count",
        "value": 1
      },
      "timeOfSample": "2020-09-23T16:20:50Z"
    }
  }
}

InventoryConsumed event payload

Property Description Type Required

usage

Amount of the consumable product used since the last InventoryConsumed event, expressed as a count, volume, or weight.

Measurement object

Yes

timeOfSample

Time the sensor detected the usage level.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ

String

Yes

Was this page helpful?

Last updated: Nov 22, 2023