Alexa.InventoryLevelUsageSensor Interface 3

Implement the Alexa.InventoryLevelUsageSensor interface in your Alexa add-on so that you can report the approximate usage of a consumable product 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 Alexa.InventoryLevelUsageSensor for multiple consumable products, such as a vacuum with a dust filter and a brush. If you report the quantity of a consumable product remaining in your device, implement the Alexa.InventoryLevelSensor interface instead. If you report when your device uses a consumable product, implement the Alexa.InventoryUsageSensor interface instead. For the list of languages that the Alexa.InventoryLevelUsageSensor 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.InventoryLevelUsageSensor, 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.

Utterances

The Alexa.InventoryLevelUsageSensor interface doesn’t define any user utterances.

Properties and objects

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

Reportable properties

The Alexa.InventoryLevelUsageSensor 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 value: `Duration`.	String
`value`	Approximate amount of the consumable product already used, expressed as a Duration. Include when you report the usage.	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.InventoryLevelUsageSensor by using the standard discovery mechanism described in Alexa.Discovery. An endpoint can support multiple sensors. To distinguish sensors, you must include an Alexa.InventoryLevelUsageSensor 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.InventoryLevelUsageSensor entry in the capabilities array, include the following fields.

Property	Description	Type
`instance`	Name of the sensor. Examples: `Sensor.DustFilter` or `Sensor.Brush`.	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 vacuum that supports the Alexa.InventoryLevelUsageSensor interface.

{
    "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": "Vacuum Plus",
                "description": "Smart Vacuum by Vacuum Maker Plus",
                "friendlyName": "Downstairs vacuum",
                "displayCategories": [
                    "VACUUM_CLEANER"
                ],
                "additionalAttributes": {
                    "manufacturer": "Vacuum Plus",
                    "model": "VPM1",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional 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": "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": "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.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

{
  "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": "Vacuum Plus",
          "description": "Smart Vacuum by Vacuum Maker Plus",
          "friendlyName": "Downstairs vacuum",
          "displayCategories": [
            "VACUUM_CLEANER"
          ],
          "additionalAttributes":  {
            "manufacturer": "Vacuum Plus",
            "model" : "VPM1",
            "serialNumber": "Serial number of the device",
            "firmwareVersion" : "Firmware version of the device",
            "softwareVersion": "Software version of the device",
            "customIdentifier": "Optional 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": "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": "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"
            }
          ]
        }
      ]
    }
  }
}

Inventory update events

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

ChangeReport

When you implement the Alexa.InventoryLevelUsageSensor interface, you send InventoryConsumed and InventoryReplaced events instead of the ChangeReport event.

InventoryConsumed event

To report inventory proactively to Alexa, send an InventoryConsumed event and include the approximate usage of a consumable product installed in your device. Report this event about one time a day. You send the event to the Alexa event gateway.

InventoryConsumed event example

In the following example, you notify Alexa after the device consumes 30 minutes of the dust filter lifespan.

{
  "event": {
    "header": {
      "namespace": "Alexa.InventoryLevelUsageSensor",
      "name": "InventoryConsumed",
      "instance": "Sensor.DustFilter",
      "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": "Duration",
        "value": "PT30M"
        },
        "timeOfSample": "2020-07-02T16:20:00.00Z"
    }
  }
}

InventoryConsumed event payload

Property	Description	Type	Required
`usage`	Amount of the consumable product already used, expressed as a duration. The duration value must not be negative.	`Measurement` object	Yes
`timeOfSample`	Time the sensor detected the usage level. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`	String	Yes

InventoryReplaced event

After the user replaces a consumable product, send an InventoryReplaced event proactively to Alexa. You send the event to the Alexa event gateway.

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": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "replacedDate": "2020-01-15T14:30Z"
    }
  }
}  

InventoryReplaced event payload

Property	Description	Type	Required
`replacedDate`	Date the user replaced the consumable product. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`	String	Yes

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.InventoryLevelUsageSensor Interface 3

Dash replenishment IDs

Utterances

Properties and objects

Reportable properties

Measurement object

Replenishment object

Discovery

Capabilities array

Discover response example

AddOrUpdateReport

AddOrUpdateReport event example

Inventory update events

ChangeReport

InventoryConsumed event

InventoryConsumed event example

InventoryConsumed event payload

InventoryReplaced event

InventoryReplaced event example

InventoryReplaced event payload

​Dash replenishment IDs

​Utterances

​Properties and objects

​Reportable properties

​Measurement object

​Replenishment object

​Discovery

​Capabilities array

​Discover response example

​AddOrUpdateReport

​AddOrUpdateReport event example

​Inventory update events

​ChangeReport

​InventoryConsumed event

​InventoryConsumed event example

​InventoryConsumed event payload

​InventoryReplaced event

​InventoryReplaced event example

​InventoryReplaced event payload

​Related topics

Dash replenishment IDs

Utterances

Properties and objects

Reportable properties

Measurement object

Replenishment object

Discovery

Capabilities array

Discover response example

AddOrUpdateReport

AddOrUpdateReport event example

Inventory update events

ChangeReport

InventoryConsumed event

InventoryConsumed event example

InventoryConsumed event payload

InventoryReplaced event

InventoryReplaced event example

InventoryReplaced event payload

Related topics