📘

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.

The Order Fees report provides a consolidated view of all of the Buy with Prime fees charged as part of the order lifecycle, including:

• Prime service fees
• Payment processing fees
• Payment processing authorization fees
• Payment processing cross-border fees, if applicable
• Fulfillment fees, which vary based on the number of units and size tier

You can use the report to reconcile fees in your accounting and finance systems and to help evaluate the profitability of Buy with Prime orders.

To get the report, you start the report generation with ORDER_FEES as the report type. Once the report is ready, you can download it from the report download link. You can also get the status of a report.

Step 1: Start the report

To generate a report, use the startReportTask mutation. In the request, you can set a date range. Dates are in ISO-8601 UTC format. If you don’t provide a date range, startReportTask defaults to the last seven days.

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 a 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: "ORDER_FEES"
    }
  ) {
    taskId
  }
}

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

Step 2: (Optional) Get the status of the 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 a 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": "ORDER_FEES",
      "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
  }
}

Step 3: Get the report

To get a link to download the report, use the reportDownloadLink query with the taskId from 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, 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.

The following example shows how to get the download link for a report.

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

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

Order Fees reports have the following fields.

Example report

The following table shows an example of an Order Fees report.

Related topics

• Get Analytics Reports
• Troubleshoot Analytics Errors
• Get User Engagement Data