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.
Web-related Calls
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}
Last updated: Aug 07, 2018