📘

Important

The Buy with Prime API is offered as a preview and might change as we receive feedback and iterate on the interfaces. We are sharing this early documentation to help you learn about the Buy with Prime API as we write and iterate on the content.

You use the Buy with Prime Analytics interface to track Buy with Prime metrics across your site.

Buy with Prime currently supports one report type, the User Event report. This report tracks e-commerce user events such as page views, clicks, and so on. For this type of report, you send user events and then you create and download a report by performing the following steps:

1. Start a report task for a particular time range.
2. Get the status of the report task.
3. Get a URL with which to download the report.
4. Download the report.

Create an analytics report

To create an analytics report, you start a task to generate a report by using the startReportTask mutation. In the request, define the type of report and an optional date range.

All dates are in ISO-8601 UTC format. If you don’t provide a date range, startReportTask defaults to the last seven days. For example, if the current time is 2023-03-08T05:00:00Z and you don’t provide a date range in the request, the response returns a report with data from 2023-03-01T05:00:00Z to 2023-03-08T05:00:00Z .

The response contains a unique taskId that you use to get the status of or get a link to to the report.

The amount of time it takes to generate an analytics report depends on a number of factors:

• The type of report you request: Reports that involve advanced joins takes more time to process.
• The requested data range: The longer the data range, the more time the report takes to process.
• The amount of data you have: If you have a lot of data, such as orders, reports take more time to process.

You can have at most five startReportTask requests in STARTED state at any time. If you submit more than five requests, you get a ThrottlingException.

The following example shows how to call the startReportTask mutation.

// GraphQL mutation
mutation StartReportTask {
  startReportTask(
    input: {
      timeRange: {
        startDate: "2023-06-01T20:58:49Z"
        endDate: "2024-06-03T20:58:49Z"
      }
      reportType: "USER_EVENTS"
    }
  ) {
    taskId
  }
}

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

Get the status of an analytics report

To check the status of a report you use the reportTask query with the taskId that you received when you performed a startReportTask mutation.

Reports expire seven days from the time the report was created. For example, if you called startReportTask on 2023-03-07T05:46:00Z, the report expires on 2023-03-14T05:46:00Z. After the report expires, the report is no longer available to download. However, you can make a new request to startReportTask to create a new report.

The status field of the response contains the status of the report. The status can be STARTED, COMPLETED, FAILED.

If you call reportTask with a taskId for an expired report, you get a ResourceNotFoundException.

The following example shows how to get the status of an analytics report.

// GraphQL query
query ReportTask {
  reportTask(taskId: "example-task-id") {
    status
    requestTime
    lastUpdatedTime
    reportType
    taskId
  }
}

{
  "data": {
    "reportTask": {
      "status": "STARTED",
      "requestTime": "2024-07-21T22:24:33.436Z",
      "lastUpdatedTime": "2024-07-21T22:24:33.692Z",
      "reportType": "USER_EVENTS",
      "taskId": "example-task-id"
    }
  }
}

{
  "errors": [
    {
      "message": "Querying for an invalid or expired taskId",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["reportTask"],
      "extensions": {
        "classification": {
          "type": "ResourceNotFoundError",
          "errorType": "ResourceNotFoundException",
          "errorCode": 404
        }
      }
    }
  ],
  "data": {
    "reportTask": null
  }
}

Get a link to an analytics report

To get a link with which to download an analytics report that you created by using the startReportTask mutation, perform a reportDownloadLink query with the taskId that you received when you performed the startReportTask mutation.

The response to the reportDownloadLink query contains a URL that you can use to download a report. The URL expires five minutes after your call to reportDownloadLink. If five minutes have passed and you need to the report, you can make a new call to reportDownloadLink query to get a new URL.

The report itself is accessible for seven days after the report is created. You can call the reportDownloadLink query to get a new link to the report as many times as needed till the expiry of the report.

After you get a link to the report, you can download the CSV file by using a standard interface in your chosen programming language. For a description of the fields of the report, see Analytics Report Types.

// GraphQL query
query Query {
  reportDownloadLink(
    taskId: "USER_EVENTS:23272b65-efac-412d-a8aa-ce8ef41bb448"
  ) {
    downloadUrl
  }
}

{
  "data": {
    "reportDownloadLink": {
      "downloadUrl": "https://example-download-url"
    }
  }
}

Related topics

• Analytics Interface Examples
• Analytics Interface