Dash Replenishment Service APIs

API Endpoints

DRS supports two base URLs which all endpoints are built on. In addition, you will request your LwA access tokens to a third URL.

Authenticating your API requests

To access DRS, you have obtained a Login with Amazon access token in STEP 3, which grants you access to the DRS APIs. When the customer completes the DRS flow by selecting the consumable(s) to replenish, your product will receive a token that you can use to get access.

There are two methods used to obtain an access token for use with DRS:

  • LwA Web API method for microsites or hybrid apps
  • LwA Mobile SDK method for iOS and Android apps

You will use the authorizationCode returned by these methods to contact the LwA endpoint and receive an access token.

Service calls

The following base URL must be used for all service related API calls, for instance replenishing an order or reporting the slot status of a device:

https://dash-replenishment-service-na.amazon.com

The full list of endpoints is described below.

The following base URL must be used for all web-related calls. Use this URL for customer-facing pages and interactions, such as your settings and teaser pages:

https://drs-web.amazon.com

API Versioning

Amazon is using versioning to incrementally update API functionality without directly impacting customers. It is mandatory to pass in the following headers for every Service API call: x-amzn-type-version and x-amzn-accept-type.

  • x-amzn-type-version – Allows you to control the version of requests sent.
  • x-amzn-accept-type – Allows you to control the version of the responses you receive.

Supported versions are supplied for each DRS endpoint.

Versions and Backwards Compatibility

When endpoints have multiple versions available, the syntax for each version is listed in tabs. Although the latest version is the recommended endpoint syntax, you can use the previous versions if you prefer. DRS is always backwards compatible with support for previous versions.

Endpoint list

The following list includes all the endpoints you will communicate with in order to be compliant with the DRS certification guidelines for user experience.

Endpoint Required Use when SNS notification
Replenish Y The consumable associated with your device needs to be reordered. You will receive an Order placed notification.
Slot status Y The content of the slot is consumed. N/A
Device status Y Daily. N/A
Deregistration Y The customer requests to disable the service, from the companion app(s) or web. You will receive an Device deregistered notification.
Subscription info Y Periodically, to verify the customer subscription status, and on-demand to update the companion app information. You will receive an Subscription changed notification.
Cancel test order N You are developing and testing the implementation. This API will work for orders placed when is_test_device: true. You will receive an Order cancelled notification.
Get order info Y After using the Replenish endpoint, to verify the order status, and on-demand to update the companion app information. You will receive an Item shipped notification if the order goes through.
You will receive an Order cancelled notification if the order is cancelled for any reason.

Replenish

This API will place an order for the ASIN the customer selected in the slot. More info

HTTP method:

POST

Path:

/replenish/{SLOT_ID}

Slot Status

This API will report on the current status of the slot and requires the consumable levels to be sent. More info

HTTP method:

POST

Path:

/slotStatus/{SLOT_ID}

Device Status

This API will report on the current status of the device and require the time and date of last usage to be sent. More info

HTTP method:

POST

Path:

/deviceStatus/{SLOT_ID}

Deregistration

This API will remove the device from the customer's Amazon account. More info

HTTP method:

DELETE

Path:

/registration

Subscription Info

This API will report on the current status of the subscription. More info

HTTP method:

GET

Path:

/subscriptionInfo

Cancel Test Order

This test API will cancel test orders placed under development. More info

HTTP method:

DELETE

Path:

/testOrders/slots/{SLOT_ID}

Get Order Info

This API will report on the order status. More info

HTTP method:

GET

Path:

/getOrderInfo/{eventInstanceId}