Integrating DRS in your server

I: Implement DRS

STEP 1:
Create an LwA Security Profile

→

STEP 2:
Set up a new device

→

STEP 3:
Configure LwA

→

STEP 4:
Connect to the Amazon APIs

→

STEP 5:
Receive Notifications

Warning: You are viewing an old version of the DRS docs. To access the new APIs, see Dash Replenishment Overview.

The Amazon Dash Replenishment Service offers RESTful APIs to retrieve, customer information, order information and auto-reordering status. Each DRS API is versioned, providing additional features to developers using the latest version. DRS also notify manufacturers of changes in the order and reordering status using SNS notifications.

The full list of APIs can be found in the API Overview documentation, while the SNS notifications are available in the SNS Notification Messages page.

This section covers best practices around managing the communication between the smart devices and the DRS cloud.

Cloud Overview
Server Architecture
Updating Inventory
Sending Consumption Data
Placing Orders
Managing the Customer's Lifecycle
Additional resources
Next Step

Cloud Overview

The cloud is tasked with handling the communication among smart devices, companion apps and the DRS infrastructure. Creating a DRS-compliant architecture from scratch or embedding DRS in an existing infrastructure requires as few as 3 components:

An SNS Listener - Responsible to process inbound SNS notifications sent by the DRS infrastructure.
A Database - Responsible to store customers' inventory and device consumption data.
A Server or a serverless application - Responsible to process requests from the companion app(s), smart devices and the SNS Listener

There are 4 things the cloud is responsible for:

Updating inventory – The cloud must be able to track the remaining inventory, and update it when a new order arrives or if the customers purchase supplies outside of DRS.
Sending consumption data – The cloud must send consumption data to the DRS cloud every time the device uses supplies.
Placing orders – The cloud must be able to place an order on behalf of customers, when the inventory is low.
Managing the customer’s lifecycle – The cloud must be able to provide the right level of information to the connected companion app(s), by updating their UI when customers register, deregister, pause the service or change their reordering preferences.

When customers interact with the Dash Replenishment preferences, including updating reordering information and changing auto-reordering status (on/off), manufacturers will receive SNS Notification Messages from the DRS cloud, that will help developers update the customers' reordering preferences and the companion app(s) UI. When the status of an automatically placed order changes, manufacturers will also receive order-specific SNS notifications that can help developers update the available inventory.

Server Architecture

Building a scalable infrastructure helps manage a large network of smart devices interacting with the cloud. Amazon DRS is built on AWS and leverage AWS components to communicate with the manufacturer's cloud.

Developers can choose to use their own cloud infrastructure but Amazon recommends to familiarize with the following sample architecture to better understand how each component interact with the rest.

Bespoke configurations can be discussed with the DRS Solutions Architecture team, who will guide developers to configure the ideal infrastructure.

Updating Inventory

Tracking inventory is important to ensure that orders are placed only when needed. An inventory update can be triggered in three instances: when customers use their smart device, when an automatically placed order is delivered and manually, by customers through the companion apps.

When customers use their smart device and one of the slots is dispensing consumables, the device must communicate with the cloud to report usage metrics. The cloud will update the database and check the inventory levels to ensure it’s still within safe levels.

Note: In this step, you must also send inventory updates to Amazon. This is covered in the Sending Consumption Data section.

Customers must be able to see the updated inventory level in the companion app(s).

When an order is placed on behalf of the customer, DRS sends an SNS notification for update concerning the order. For every order placed, the cloud will receive at least 2 notifications: when the order is placed and when the item is shipped. In addition, the cloud will be notified if the customer cancels an order. The ItemShipped SNS notification contains 3 key pieces of information: the slot ID being replenished (ex. Liquid Detergent), the quantity being replenished (ex. 5 Liters) and the estimated delivery date. The cloud must be able to capture these three values and update the available inventory when the estimated delivery date is reached.

Should customers buy additional supplies outside of DRS, they must be able to manually update the remaining inventory from the companion app(s).

Consumable Types

Tracking consumables consumption helps create a replenishment logic that places orders at the right time. To track the consumption consistently, you should identify which unit and quantity your product will use for each slot .

Unit	Quantity	Example Products
Volume	Lt, Fl oz	Liquid Detergent
Weight	Kg, Oz, Lbs	Ground Coffee, Pet Food
Count	0, 1, 2…	Coffee pods, Dishwasher Tabs
Percentage	100% to 0%	Air Filter, Water Filter, Ink, Toner

Managing inventory updates

When you set up your infrastructure and process inventory updates, you should consider implementing some logic that converts the information you receive from the DRS APIs and the DRS Notifications. The following table provides an overview of what to expect in each country:

	US	UK	DE	FR	IT	ES	JP
Volume	Fl oz	l	l	l	l	l	l
Weight	oz	kg	kg	kg	kg	kg	kg
Count	count	count	count	count	count	count	count

Warning: Consumables across different marketplaces may use a different measurement unit. Please ensure your logic does not expect a specific literal string (e.g. "Fl oz") as different items may have a different spelling (e.g. "oz" or "fl oz"). Consult the Measurement units table for more information.

For example, when an OrderPlacedNotification is received for liquid detergent for a customer in the US, it will show the unit type "fl oz", whilst a notification for a customer in the UK will show "l" or liters.

Example

...
"productInfo": [
    {
        "asin": "B00JGZBTCI",
        "quantity": 103,
        "unit": "fl oz",
        "estimatedDeliverydate": "2016-12-09T07:59:59Z"
    }
],
...

...
"productInfo": [
    {
        "asin": "B077YLQ2R1",
        "quantity": 5.0,
        "unit": "l",
        "estimatedDeliverydate": "2016-12-09T07:59:59Z"
    }
],
...

Measurement units

The following table includes possible variants of the measurement units spelling.

Unit	Quantity Strings
Volume	liters, liter, litre, litres, l, L, ml, milliliter, milliliters, ounces, ounce, oz, fl oz
Weight	kg, kilograms, kilogram, ounces, ounce, oz
Count	count, pod, pods, sheet, sheets

Sending Consumption Data

When smart devices send consumption data to the cloud, this must be captured and sent to Amazon using the slotStatus API. These updates should include the remaining inventory.

Example Request

POST /slotStatus/{SLOT_ID} HTTP/1.1
Host: "https://dash-replenishment-service-na.amazon.com"
{
  "expectedReplenishmentDate": "2018-12-28T10:00:00Z",
  "remainingQuantityInUnit": 3.5,
  "originalQuantityInUnit": 10,
  "totalQuantityOnHand": 20,
  "lastUseDate": "2018-12-21T10:00:00Z"
}

Please see the slotStatus API documentation for more information.

Placing Orders

Detecting when the remaining inventory is below the reordering threshold is important to reduce order cancellations, increase customer retention and provide the best customer experience. Creating a simple logic that ensures orders are placed only when needed, requires as few as 7 lines of code. There are three key factors that can help developers find the perfect threshold: consumption frequency, consumption quantity and inventory left.

To demonstrate the importance of creating a threshold based on the customer usage, let’s take a look at this scenario: customer A, uses a smart coffee machine that has a remaining inventory of 20 pods and brews 1 coffee each day. At this rate,customer A will run out in 20 days. Considering a standard non-Prime shipping time of 5 days, Amazon recommends to place an order 7 days in advance (i.e. 7 pods remaining), which would ensure customers have new coffee pods before they run out.

Now let’s consider customer B, with the same remaining inventory, but who brews 2 coffees each day. If we were to place an order when there are 7 pods left, customer B would run out 2-3 days before the estimated delivery, leading to a poor customer experience.

The following code demonstrates how to create a customer-centric logic to reorder only when needed:

Example Node.JS code

const daysThreshold = 7; // Recommended by Amazon
var inventoryUsed = getInventoryUsedInPeriod(); // 50 pods
var daysInPeriod = getDaysInPeriod(); // 20 days
var currentInventory = getCurrentInventory(); // 20 pods
var burnRate = inventoryUsed/daysInPeriod; // 50/20 = 2.5/day
var podsThreshold = burnRate*daysThreshold; // 2.5*7 = 15 (reordering threshold)
if(currentInventory <= podsThreshold){
  replenishSlot(); // Call the replenish API
}

Calling the replenish API will result in an order being placed for a specific slot. Please refer to the replenish API documentation for more information.

Managing the Customer's Lifecycle

When customers modify the status of their auto-reordering, the manufacturers’ cloud will receive an SNS notification to inform them of a change in the subscription (SubscriptionChangedNotification). Using the replenish API when customers pause auto-reordering will not result in an order being placed, but developers can choose to update the companion app(s) UI to let customers know of the current state change.

If the manufacturer’s cloud stores the customers’ reordering preferences, including the ASIN being replenished for each slot, developers can leverage the same SNS notification to detect a change in the subscription.

When customers decide to permanently deregister their smart device from their Amazon account, DRS will notify the manufacturers infrastructure with a DeviceDeregisteredNotification. This SNS notification must trigger a clean-up of the customer entry in the manufacturers’ database. Companion app(s) must provide the ability to register for DRS again.

Additional resources

In this page we have discussed the possible ways the cloud can communicate with the DRS infrastructure, both inbound and outbound. More information can be found at:

Next Step

Next, we will look at configuring SNS to receive notifications from DRS.

Last updated: Aug 07, 2018