📘

Buy with Prime API is now available for early access

Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.

Sign Up

To create a data retrieval request, you use the startPersonalDataRetrievalTask mutation. In the request, you must provide the customer's email address.

You can optionally provide a clientToken to serve as an idempotency key that ensures that multiple identical requests are only processed once with an eight-hour period. This is particularly useful in scenarios where network issues might cause you to need to retry a request. If you don’t provide a clientToken, a default clientToken is generated for each request.

Data retrieval tasks run immediately after they have been initiated and can't be canceled.

The response to the data retrieval request contains a taskId, which you can provide to the personalDataRetrievalTask query if the customer later asks for an update on their data retrieval request before you receive a data retrieval event.

Step 1: Subscribe to data retrieval events

Follow the Steps to Subscribe to Buy with Prime Events to subscribe to the following events:

• PERSONAL_DATA_RETRIEVAL_TASK_COMPLETED
• PERSONAL_DATA_RETRIEVAL_TASK_FAILED

Step 2: Create a data retrieval request

Create a data retrieval request by using the startPersonalDataRetrievalTask mutation. In the request, provide the following information:

• Customer's email address: (Required) The email address identifies the customer.
• Client token: (Optional) The clientToken field of the request serves as an idempotency key that ensures that multiple identical requests are only processed once with an eight-hour period. This is particularly useful in scenarios where network issues might cause you to need to retry a request. If you don’t provide a clientToken, a default clientToken is generated for each request.

The following example shows how to submit a data retrieval request.

// GraphQL mutation
mutation {
    startPersonalDataRetrievalTask(input: {
        dataSubject: {
            type: SHOPPER
            email: "[email protected]"
        }
    }) {
        taskId
    }
}

{
  "data": {
    "startPersonalDataRetrievalTask": {
      "taskId": "example-task-id"
    }
  }
}

Step 3: Receive a data retrieval event

When you receive an event of type PERSONAL_DATA_RETRIEVAL_TASK_COMPLETED or PERSONAL_DATA_RETRIEVAL_TASK_FAILED, parse the resources array of the event to get the task ID. For details about how to interpret the resources array of an event, see Subscribe to Events.

For example, in the following event, the task ID is example-data-retrieval-task-id.

{
  "version": "0", 
  "id": "example-event-id", 
  "detail-type": "PERSONAL_DATA_RETRIEVAL_TASK_COMPLETED", 
  "source": "aws.partner/buywithprime/partner-event-source-name",
  "account": "example-aws-account-id", 
  "time": "2023-10-27T12:34:56Z", 
  "region": "us-east-1", 
  "resources": [
    "businessProduct/business-product-id/personalDataRetrievalTask/example-data-retrieval-task-id",
  ], 
  "detail": {}
}

Step 4: Query the data retrieval task

Call the personalDataRetrievalTask query, providing the task ID that you found in the resources array of the event in the previous step.

The way you handle the response depends on whether the data retrieval request succeeded (the event was PERSONAL_DATA_RETRIEVAL_TASK_COMPLETED) or failed (the event was PERSONAL_DATA_RETRIEVAL_TASK_FAILED):

• If the data retrieval request succeeded, the response to the personalDataRetrievalTask query includes a pre-signed URL that you can use to download the customer's data.
• If the data retrieval request failed, the response to the personalDataRetrievalTask query includes an errors array where you can find information about why the request failed.

Step 5: Download the requested data

When the data is ready, the response to the personalDataRetrievalTask query includes a link that you can use to download the customer personal data.

When you use the URL, keep the following facts in mind:

• The URL expires in 60 seconds.
• After the download has started, the expiry time doesn’t affect the download. If the link has expired, you must call the personalDataRetrievalTask query again to get a new URL.

The file that you download from the URL is a zip file. The name of the zip file is in the format dsar-emailprefix-submitDate.zip, where emailprefix refers to the full part of the shopper's email address before the '@' symbol, and submitDate is the submission date in the format YYYYMMDD. An example of a zip file name is dsar-tom-20240823.zip.

The structure of the zip file is as follows:

dsar.zip  
│  
├── name1.zip  
│ ├── README  
│ ├── file1.csv  
│ ├── file2.json  
│ └── ...  
│  
├── name2.zip  
│ ├── README  
│ ├── file1.jpeg  
│ ├── file2.mp3  
│ └── ...  
│  
└── ...

For example, a shipping address zip file includes a ShippingAddress.csv and a README for ShippingAddress.csv.

The following is an example of a README file for ShippingAddress.csv:

placeId: Place identifier, such as 1ea2742263944f18848208ff8af84b39.
Country Code: Shipping address country, such as "US".
State: Shipping address state, such as "WA".
City: Shipping Address city, such as "Seattle".
Address Line 1: Shipping address major line, such as "123 Main Street".
Address Line 2: Shipping address minor line, such as "Suite 111".
Zip Code: Postal code, such as "98109".
Name: Shipping address contact name, such as "Tom".
Phone Number: Shipping address contact number, such as 11234567890.

Related topics

• Retrieve and Delete Shopper Data
• Query Privacy Requests