The SP-API Reports Pattern Everyone Gets Wrong (Async, Step by Step)

The number-one mistake: expecting report data back from the create call. createReport returns a reportId, not rows. Amazon generates the report in the background; you have to poll for it, then fetch the finished document separately. Four steps, in order:

1. Create the report → get a reportId.
2. Poll the report until its processingStatus is DONE.
3. Fetch the report document → get a download URL.
4. Download and decompress the file, then parse it.

Specify the report type, the marketplaces, and an optional date window:

POST /reports/2021-06-30/reports
{
  "reportType": "GET_FLAT_FILE_OPEN_LISTINGS_DATA",
  "marketplaceIds": ["ATVPDKIKX0DER"],
  "dataStartTime": "2026-07-01T00:00:00Z",
  "dataEndTime":   "2026-07-07T00:00:00Z"
}

You get back a reportId. That's your handle for everything downstream.

Call GET /reports/2021-06-30/reports/{reportId} and watch processingStatus:

Poll with backoff. A tight polling loop is the fastest way to a 429. Start around 10–30 seconds between polls; big reports can take minutes.

Once status is DONE, the report carries a reportDocumentId. Exchange it for a download:

GET /reports/2021-06-30/documents/{reportDocumentId}
→ { "reportDocumentId": "...",
    "url": "https://tortuga-prod-...s3...",   // presigned, short-lived
    "compressionAlgorithm": "GZIP" }

The url is a presigned S3 link that expires quickly — download it promptly, don't cache it for later.

The gotcha that produces "garbage bytes": when compressionAlgorithm is GZIP, the downloaded file is gzip-compressed. You must decompress before parsing.

import gzip, requests
raw = requests.get(doc["url"]).content
data = gzip.decompress(raw) if doc.get("compressionAlgorithm") == "GZIP" else raw
# most flat-file reports are tab-delimited; some newer ones are JSON
rows = data.decode("utf-8").splitlines()

Flat-file reports are usually tab-delimited text; newer report types may be JSON. Check the report type's documented format.

Creating the same report over and over wastes quota and can throttle you. Before creating, call getReports to see if a recent one for that type and range already exists, and reuse it. For recurring needs, use report schedules so Amazon generates them on a cadence and you just fetch the latest.

Why does createReport return no data?

Because it's asynchronous. createReport only returns a reportId. You poll getReport until it's DONE, then fetch the document separately.

What does CANCELLED mean?

Usually that there's no data for the requested range — not a failure. Stop polling and move on. FATAL, by contrast, means generation failed and you should log it and retry the create.

My downloaded report is unreadable bytes. Why?

It's gzip-compressed. When compressionAlgorithm is GZIP, decompress the file before parsing.

How often should I poll?

With backoff — start around 10–30 seconds between polls. Tight polling loops are the most common cause of 429 throttling on the Reports API.

Why did my download URL stop working?

The document url is a presigned S3 link that expires within minutes. Fetch it right after you get it; don't store it to use later.