Integrating Pre-registration

• What is Pre-registration
• Overview
  • Pre-requisites
  • Packaging changes: Serial number barcode
• Implementation
  • Step 1 - Back-end implementation
    • Calling the Access Token Exchange API
    • Listening to SNS Notifications
  • Step 2 - Front-end implementation
  • Step 3 - Certification
• API definition
  • Endpoints
  • HTTP header parameters
  • HTTP body parameters
  • HTTP response
  • Examples
    • Example request: application/json
    • Example request: application/x-www-form-urlencoded
    • Example response
  • Error Responses
  • Devices on the Allow List

What is Pre-registration

With Dash Replenishment Service we aim to delight our customers and remove friction from their shopping experience. All DRS-enabled devices allow customers to select a consumable (e.g. coffee pods, detergent, ink) to automatically replenish before it runs out. With pre-registration, we allow customers shopping on Amazon to make that selection when they add the DRS-enabled device to their cart and offer a streamlined set-up experience when they receive the device.

Overview

Currently, when a customer sets up a DRS-enabled device for the first time, they will also be asked to set up the Dash Replenishment Service by selecting one or more products to automatically re-order. At this stage, a device manufacturer can associate the Device Serial Number with the customer's Amazon account so that the customer can receive new supplies before they run out.

When you integrate pre-registration in your solution, we will provide you with the Device Serial Number as soon as the customer purchases the device and sets up the DRS functionality on Amazon. During the Amazon checkout experience, they will be able to select one or more products to automatically re-order and their preference will be saved in the Amazon cloud.

This allows you to directly exchange authorization tokens for pre-registered devices before a customer gets to the out-of-the-box experience, thus further simplifying and speeding up the customer on-boarding. For devices that were not pre-registered during an Amazon purchase, the on-boarding will be completed during the first set-up (Login with Amazon, followed by ASIN selection).

1. Customers purchase a DRS-enabled device on Amazon and select which consumable they want to automatically replenish. This preference is saved in the Amazon DRS cloud.
2. The Device Serial Number on the box is scanned before the product is shipped to our customers. When this happen, we send the device manufacturer an SNS notification with the serial number.
3. Customers receive the product they purchased, open the companion app and click on the "Dash Replenishment Service" option. The device manufacturer will check if the Device Serial Number (DSN) of the device has pre-registered using the API call and redirect customers to the improved experience, thus skipping the product selection.

Pre-requisites

In order to take advantage of the simplified on-boarding experience that pre-registration offers, there are 3 pre-requisites:

1. Serial number barcode on the box - A 1D (or 2D) barcode of the serial number needs to be printed on the box.
2. Regex for serial number validation - For quality control purposes, it is recommended that a regex for device model validation is shared with Amazon. This is a requirement when a new device model is added to the Dash Replenishment Services (DRS) service.
3. Adoption of the new Token Exchange API - To verify that the customer has already selected their reordering preferences at the point of purchase, a request to a Login with Amazon API must be made with the device serial number.

Packaging changes: Serial number barcode

Device manufacturers will be responsible for ensuring a 1D (or 2D) barcode containing the serial number of the device is printed on the box. In order to ensure quality control and that the correct barcode is scanned on the box, Amazon will be performing serial number validation as a part of the scan. Validation will be based on the serial regex provided by device manufacturers corresponding to the device model/ASIN.

Manufacturers will be expected to provide the serial regex and the ASIN at the time the new device model is on-boarded to the DRS service.

Implementation

There are 3 steps required to integrate this solution:

1. Back-end implementation: identify if the device is pre-registered and invoke the new API at the time of device registration for a token exchange.
2. Front-end implementation: your companion apps will require minor changes to the on-boarding flow to handle pre-registration.
3. Certification: Amazon will have to certify the companion app(s), the back-end implementation and perform fulfillment center process testing.

Step 1 - Back-end implementation

When designing the back-end architecture there are two options to consider:

1. Pull (recommended) - When a customer opens the companion app and connects to the device they purchased, a call to the pre-registration endpoint can be initiated with the required parameters. If a 200 OK response is received, it will contain the required access and refresh tokens necessary to communicate with the other DRS API Endpoints.
2. Push - Request the access and refresh tokens when the SNS notification is received. When the purchased device is shipped, we inform the device manufacturer via the deviceRegisteredNotification. At this stage, the pre-registration endpoint can be called with the required parameters. If a 200 OK response is received, it will contain the required access and refresh tokens necessary to communicate with the other DRS API Endpoints. In this scenario, the customer may not connect the device until much later (i.e. when the device has been delivered and connected to the network) which means you will have to renew the access token, as it will have expired.

Amazon strongly recommends to implement option 1, as it will reduce the risk of bad customer experience in case of outage or missed SNS notifications.

Calling the Access Token Exchange API

Amazon will provide manufacturers access to an API that will enable access_token exchange for Dash Replenishment Service, eliminating the need for the customer to go through the Login with Amazon and reducing friction.

Device manufacturers will own the business logic to connect to the device and extract the device details including serial number and device model.

When the request is made, Amazon systems will be responsible for the following:

1. Authenticating and authorizing the client making the API call.
2. Verifying that the device in the request has been configured by the customer in the Amazon systems.
3. Verifying that the customer has signed up for Dash Replenishment. Retail checkout and fulfillment center barcode scan workflows are a prerequisite for a successful token exchange using this API. In the case either of the workflows were skipped/failed/incomplete, this API will fail to return a valid refresh token to the client.

Examples on how this can be achieved are in the API definition section.

Listening to SNS Notifications

When a device that was pre-registered for DRS is shipped, Amazon will send a deviceRegisteredNotification via SNS, that includes the serial number of the pre-registered device to the manufacturer. To receive SNS notifications you must have successfully set-up your infrastructure as per the "Create an SNS Topic" documentation.

The serialNumber field in the SNS notification (see below) will be set to the device serial number (DSN) printed on the box.

Device manufacturers will own the business logic to connect to the device and extract the device details including serial number and device model. They will also be responsible to save the registered SNS notifications if they wish to do so.

An example of the pre-registration notification:

{
    "notificationInfo": {
        "notificationType": "DeviceRegisteredNotification",
        "lwaClientId": "amzn1.application-oa2-client.6b68exxxxxxxxxx9",
        "notificationTime": "2015-10-01T02:23:52.747Z",
        "notificationId": "amzn1.dash.notification.v1.xxxxxxxxxxxxx13",
        "version": "2015-06-05"
    },
    "deviceInfo": {
        "deviceIdentifier": {
            "serialNumber": "DeviceSerialNumber"
        },
        "productIdentifier": {
            "modelId": "myDeviceModel"
        }
    },
    "customerInfo": {
        "directedCustomerId": "amzn1.account.AHxxxxxxxxGA2O5Q"
    }
}

Step 2 - Front-end implementation

This step assumes that you have followed our getting started guides to integrate DRS in your companion app (iOS, Android) or website (Web) already.

To leverage the pre-registration benefits, you will need to add the pre-registration API call before the customer sees the DRS Teaser Page in your app(s).

In pseudo code, it would look like this:

verifyPreRegistration(parameters, callbackFunction)

callbackFunction(response){
  if (response.code == 200){
    // pre-registration was successful. Save access_token, refresh_token and expires_in on the server using SSL
    save(response.data)
    skipDRSTeaserPage()
  }else{
    //We assume the device is not preregistered and continue with the standard DRS flow
    openDRSTeaserPage()
  }
}

Step 3 - Certification

Once you have implemented pre-registration in your server and companion apps, your QA team will need to run pre-certification to validate the integration.

At the end of pre-registration, your updated companion apps can be submitted for official Amazon certification. Please liaise with your Amazon Point of Contact to complete this process.

API definition

Details are subject to change, but the API should be stable going forward. We will notify you if anything changes before go live.

Endpoints

• Prod
• Pre-prod

api.amazon.com/auth/o2/token

api-preprod.amazon.com/auth/O2/token

HTTP header parameters

Content-Type:application/x-www-form-urlencoded

or

Content-Type:application/json

HTTP body parameters

• client_id: the LWA client ID of your cloud application that you on-boarded for DRS.

• client_secret: the LWA client Secret of your cloud application that you on-boarded for DRS.

• grant_type: "device_preregistration"

• scope: the string dash:replenish, the same scope you would have passed in as the "scope" in our standard LWA flow.

• scope_data: a JSON object containing the following fields:

  • "device_serial_number": your device's serial identifier, the same identifier matching the barcode printed on the box.
  • "device_model": your device's model identifier, the same identifier you would have passed in as the "deviceModel" field in our standard LWA flow.

HTTP response

• A JSON object containing the same data you would have received from the /auth/o2/token endpoint in our standard LWA flow:
  • "access_token": The access token for the user device and account.
  • "token_type": The type of token returned. Should be "bearer".
  • "expires_in": The number of seconds before the access token becomes invalid.
  • "refresh_token": A refresh token that can be used to request a new access token.

Examples

Example request: application/json

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/json

{
  "grant_type": "device_preregistration",
  "client_id":"foodev",
  "client_secret":"Y76SDl2F",
  "scope":"dash:replenish",
  "scope_data":{
    "product_instance_attributes": {
      "device_serial_number": "<deviceSerialNumber>",
      "device_model": "<deviceModel>"
    }
  }
}

Example request: application/x-www-form-urlencoded

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded

grant_type=device_preregistration&client_id=foodev&client_secret=Y76SDl2F&scope=dash%3Areplenish&scope_data=%7B%22product_instance_attributes%22%3A+%7B%22device_serial_number%22%3A+%22%3CdeviceSerialNumber%3E%22%2C%22device_model%22%3A+%22%3CdeviceModel%3E%22%7D%7D

Example response

{
   "access_token": "Atza|IQEBLjAsAhQ3yD47Jkj09BfU_qgNk4",
   "expires_in": 3600,
   "refresh_token": "Atzr|IQEBLzAtAhUAibmh-1N0EVztZJofMx",
   "token_type": "bearer"
}

Error Responses

Devices on the Allow List

• device_model: DRS_Test_Device
• device_serial_number: TestAmazonPreReg001

Your Amazon point of contact will share the test Login With Amazon credentials that can be used, along with this listed device on the allow list, to obtain valid refresh and access tokens. When calling the Replenish API with this access token, only test orders will be placed.

Last updated: Aug 07, 2018