Buy with Prime | Developer Documentation
Documentation

Steps to Process Privacy Requests

📘

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

You can create, cancel, and query privacy requests for customer personal data contained within your Buy with Prime account. Buy with Prime supports two types of privacy requests: data retrieval and data deletion. The processing of privacy requests with Buy with Prime is an asynchronous workflow.

This topic describes the steps to handle both types of privacy requests for Buy with Prime.

For details about privacy requests, see Retrieve and Delete Customer Data.

Steps to process a data retrieval request

To process a data retrieval request, take the following steps:

  1. Subscribe to data retrieval events.
  2. Create a data retrieval request.
  3. Receive a data retrieval event.
  4. Query the data retrieval task.
  5. Download the requested data.

Step 1: Subscribe to data retrieval events

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

Step 2: Create a data retrieval request

Create a data retrieval request by using the startPersonalDataRetrievalTask mutation. For an example, see Create a data retrieval request.

In the request, you 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.

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 How to handle 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 zip file contains multiple zip files that correspond to the shopper's personal data in Buy With Prime's system (for example, ordering, clickstream, and so on). Each zip file includes an optional README file that provides details about the data that one or more data files that hold the shopper’s data contain. The file names and contents might include various formats such as CSV, JSON, JPEG, PNG, MP3, MP4, WAV, and so on.

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.

Place IdCountry CodeStateCityAddress Line 1Address Line 2Zip CodeNamePhone Number
1ea2742263944f18848208ff8af84b39USWASeattle123 Main StreetSuite 11198109Tom11234567890

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.

Steps to process a data deletion request

To process a data deletion request, take the following steps:

  1. Subscribe to data deletion events.
  2. Create a data deletion request.
  3. Receive a data deletion event.
  4. Query the data deletion task.

Step 1: Subscribe to data deletion events

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

Step 2: Create a data deletion request

Create a data deletion request by using the startPersonalDataDeletionTask mutation. For an example, see Create a data deletion request.

In the request, you provide the following information:

  • Customer's email address: (Required) The email address identifies the customer.
  • Holding period: (Optional) When you create a data deletion request, you can specify a holdingPeriod before the data will be deleted. The holding period can range from 0 to 180 days. If you don’t specify a holding period, the default value is 10 days. During the holding period, you can cancel the request by using the cancelPersonalDataDeletionTask mutation.
  • 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.

To avoid fulfillment issues, the data deletion request fails if the customer has any open Buy with Prime orders. In this case, the data isn't deleted and you receive a PERSONAL_DATA_DELETION_TASK_FAILED event. You must resubmit the startPersonalDataDeletionTask request after all orders for that customer are closed.

Step 3: Receive a data deletion event

When you receive an event of type PERSONAL_DATA_DELETION_TASK_COMPLETED or PERSONAL_DATA_DELETION_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 How to handle events.

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

{
  "version": "0", 
  "id": "example-event-id", 
  "detail-type": "PERSONAL_DATA_DELETION_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/personalDataDeletionTask/example-data-deletion-task-id",
  ], 
  "detail": {}
}

Step 4: Query the data deletion task

Call the personalDataDeletionTask 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 deletion request succeeded (the event was PERSONAL_DATA_DELETION_TASK_COMPLETED) or failed (the event was PERSONAL_DATA_DELETION_TASK_FAILED):

  • If the data deletion request succeeded, you might choose to notify the customer of the successful deletion of their data.
  • If the data deletion request failed, the response to the personalDataDeletionlTask query includes an errors array where you can find information about why the request failed.

Related topics

Updated 6 days ago