Amazon Review API: From Product Links to Issue Lists with Source Evidence

When extracting product improvement clues from Amazon reviews, the first step is not having a model split all content into positive and negative feedback. You first need to know: which country marketplace the review comes from, which product it is associated with, whether it appears repeatedly across multiple requests, and exactly which sentence each issue conclusion cites. Otherwise, reading the same popular review ten times might be interpreted by reports as ten buyers raising the same issue.

This guide is intended for developers and product leads who need to integrate reviews into internal research workflows. We start with an authorized product link and establish the relationship among products, reviews, observation logs, and classification evidence. The final output is a verifiable issue list, rather than sales forecasting, review authenticity verification, or total buyer satisfaction.

Distinguish Product Catalogs from Review Research

The official Amazon Creators API provides product catalog access, including product search, product details, variants, and category node operations, tailored for Amazon Associates shopping experiences. It is not the same product as amazon.reviews in EveryInfra; official product catalog documentation cannot serve as authorization proof for third-party review reading.

Before integrating, confirm the specific marketplace, data usage permissions, processing purposes, retention periods, and whether source text can be displayed or processed by models. Amazon.com terms of use under LICENSE AND ACCESS set restrictions on general licensing and data collection methods, and other marketplaces and specific programs must be checked separately. Owning a product brand does not automatically grant arbitrary reuse rights for all review content.

If existing permissions only allow using a specific export data set, you can start directly from the identity, deduplication, and classification steps below without performing network reads. Keep the permission scope within the workflow, and exclude fields or purposes outside that scope from subsequent pipelines.

Review Current Review Contracts Without Borrowing Parameters from Other Actions

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=amazon' \
  | jq -e '.capabilities[] | select(.action == "reviews") | {
      platform, action, required_params, optional_params, param_meanings,
      mode, returns_list, default_limit, max_limit, response_fields
    }'

When checking 2026-09-04, reviews requires url, optional parameters list domain, execution mode is sync, and results are returned as a list. The current catalog does not declare specific values for default_limit and max_limit; empty values can only be recorded as undeclared, cannot be interpreted as unlimited item counts, and certainly cannot guarantee obtaining all historical reviews.

Also, do not add these fields to Amazon requests simply because other platforms support sort, since, or cursor. Optional parameters must correspond to the current action, and interface-accepted parameters and active filtering must be verified separately. The current catalog is insufficient to support tutorials on continuous pagination sorted by newest; a small sample request is demonstrated below.

Confirm Country Marketplaces Before Product Identities

Use the full product link for url; use the marketplace domain for domain, such as amazon.com or amazon.co.jp, without https:// or product paths. Local input parsing extracts ten-character uppercase letters or numbers forming the ASIN from paths like /dp/, /gp/product/, and /product-reviews/. Store homepages and keyword search pages cannot serve as confirmed product inputs.

Pay special attention to non-US marketplaces: in the current implementation, the default value for the review marketplace is amazon.com, and automatic inference of country marketplaces from arbitrary input links is not guaranteed. When preparing products for the Japan marketplace, explicitly pass amazon.co.jp to match the link. Do not treat Japanese body text, country fields in reviews, or page-displayed currency as substitutes for request domains.

• Product lists save the original URL, verified marketplace, request ASIN, business product number, and inclusion rationale. Titles are for reading only and do not serve as primary product keys.
• Product associations separately save product_asin and variant from the response; they must not overwrite request ASINs without verification, and should not guess sub-variants when missing.
• Different tracking links for the same marketplace and ASIN can be merged into a single target before sending requests, while preserving original link mappings. Requests changing marketplaces, targets, or parameters must not be merged based solely on title similarity.

The request marketplace is the source scope for this observation, not the nationality of the review author. country may be regional text in varying formats, and variant may also be incomplete; grouping by region or specification is only appropriate after clear normalization and verification. Unconfirmed records enter "unspecified" and should not be silently placed into the US marketplace or default specifications.

Complete Minimal Requests with a Single Target

Below is a request template, not a live customer call for this round. Put authorized full product links and matching marketplaces into environment variables, and keep API Keys strictly in your own runtime environment. Place limit in params as a general list count request; setting it to 3 is intended for checking small structures, not guaranteeing exactly three items returned, server-side processing limited to three items, or billing based on three items.

: "${EVERYINFRA_API_KEY:?set the API Key first}"
: "${EVERYINFRA_AMAZON_PRODUCT_URL:?set the authorized full product URL first}"
: "${EVERYINFRA_AMAZON_DOMAIN:?set the site domain matching the URL first}"
jq -cn --arg url "${EVERYINFRA_AMAZON_PRODUCT_URL}" \
  --arg domain "${EVERYINFRA_AMAZON_DOMAIN}" '{
    platform: "amazon",
    action: "reviews",
    params: {url: $url, domain: $domain, limit: 3}
  }' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

Check HTTP status and response types first, then read results, request identifiers, and available billing info according to the actual wrapper. Timeouts indicate that the client did not receive complete results, not that the server failed to execute; retain request context before verifying to avoid direct retransmissions. Empty results indicate this request delivered no usable reviews, and products must never be marked as "never having had reviews" based on this.

Separate Reviews Themselves from Observation Logs

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=amazon&action=reviews' \
  | jq '{fields, undocumented}'

The current dictionary contains review_id, title, text, rating, rating_scale, posted_at, helpful_count, is_verified_purchase, is_vine, variant, country, url, author_name, product_asin, and platform. It describes what may be returned, without guaranteeing complete values for every record.

• Review records: save source scope, stable review_id, available title/text/rating/ratings scale and source links. IDs are kept as strings; missing values are separated from explicit false and 0.
• Observation logs: save task numbers, requested products, parameter snapshots, observed_at, and actual returned review associations. Reading old reviews in a request is a new observation, not a new review.
• Analysis records: save adopted review versions, classification rule versions, themes and evidence snippets, and review status. Changing classification rules does not require rewriting raw reviews.

rating and rating_scale are handled together; product-level aggregate ratings, total rating counts, and review counts obtained this time are distinct metrics. Rating records without text can be counted in separate rating samples, but opinions cannot be fabricated and mixed into text theme analysis. author_name is only a display name, unsuitable as a unique identity, and definitely does not require stitching author cross-site profiles for product issue analysis.

is_verified_purchase is purchase verification status, not a guarantee of viewpoint accuracy or complete content authenticity; false and unreturned fields must be distinguished. is_vine identifies Vine program-related evaluations. Official Amazon documentation states that Vine-invited reviewers may experience products for free before posting opinions; therefore, this status can be used as a sample stratification field, but Vine reviews cannot be directly judged as fake, nor can missing fields be judged as non-Vine.

Preserve Associations During Deduplication Without Deleting Based Solely on Similar Text

Application layers can first use "source platform + marketplace + review_id" to identify reviews within the same scope, then separately record under which requested products they were observed. If identical keys correspond to conflicting product attributions or content, retain conflicting records for verification first without silent overwriting. Cross-site occurrences of identical IDs or text must not be automatically merged without reliable correspondence.

When review_id is missing, confirmed review permanent links can assist association; remainders enter the pending deduplication area if still uncertain. Combinations of text, date, and ratings only provide approximate candidates and cannot prove two authors are the same person. Two instances of "works great" might genuinely be different reviews, and translated synonymous text cannot serve as a unique key.

When the same review appears again later, compare actually available text, ratings, helpful counts, and product associations. Changes are recorded first as observation discrepancies; differences in language, field availability, and time ranges may also cause variations. Failing to return a specific review in this round can only be marked as "not observed this round," without generating deletion events.

Issue Classification Must Reference Back to Source Locations

Use a small sample of authorized samples for manual determination of classification boundaries before connecting models. Themes can start from actionable issues like compatibility, packaging, manuals, and logistics, while retaining "no clear issue" and "insufficient evidence." Multiple themes are allowed per review; do not fabricate quality conclusions for "unopened" items just to fill tag quotas.

Data passed to classifiers should be minimized to task-essential content. Reviews are material to be analyzed, not system instructions; sentences like "ignore rules" or "visit this address" occurring within them should not cause models to invoke tools or change processing objectives. Outputs must bind at least review IDs, source text fields, start/end positions, themes, rule versions, and pending review status.

function validateAnnotation(review, annotation) {
  const topics = new Set(["compatibility", "packaging", "instructions", "shipping"]);
  if (typeof review.review_id !== "string" || !review.review_id.trim()) {
    throw new Error("review id required");
  }
  if (annotation.review_id !== review.review_id
      || annotation.taxonomy_version !== "issues-v1"
      || !topics.has(annotation.topic)) {
    throw new Error("unknown review or classification rule");
  }
  const field = annotation.source_field;
  if (!["title", "text"].includes(field)) throw new Error("invalid source field");
  const source = review[field];
  const {start, end, quote} = annotation;
  if (typeof source !== "string" || typeof quote !== "string"
      || !quote.trim() || !Number.isInteger(start) || !Number.isInteger(end)
      || start < 0 || end <= start || end > source.length
      || source.slice(start, end) !== quote) {
    throw new Error("evidence does not match source");
  }
  return {
    review_id: review.review_id, topic: annotation.topic,
    source_field: field, start, end, quote,
    taxonomy_version: "issues-v1", review_status: "unreviewed"
  };
}

// synthetic text; demonstrates evidence checks only, not a real product review.
const sample = {review_id: "synthetic-review", text: "the API cannot reach the legacy model，wrapper intact."};
console.log(validateAnnotation(sample, {
  review_id: sample.review_id, taxonomy_version: "issues-v1",
  topic: "compatibility", source_field: "text",
  start: 0, end: 9, quote: "the API cannot reach the legacy model"
}));

This validator only proves that citation locations match input text, not that theme judgments are correct. If a model cites "packaging complete" but flags packaging issues, character checks may still pass, requiring semantic checks or manual reviews to intercept. start/end use JavaScript string indices; if data is passed to another language, index conventions must be explicit, and byte offsets or character counts must not be mixed.

Actual production must also bind marketplaces, product associations, and review versions at outer layers, limiting output counts per item and field types. Model self-reported confidence is not calibrated accuracy; select manual annotation samples before launch, and separately count omissions, false positives, and unsupported evidence instead of compressing all errors into a single pretty overall accuracy figure.

OWASP categorizes instructions hidden in web pages, documents, and user reviews as indirect prompt injection risks, and recommends verifying tool calls based on user permissions and current tasks. Therefore, review classifiers should only produce constrained candidate tags; actions like modifying products or sending messages are not authorized by review content.

Issue Proportions Must State Denominators

In a pure synthetic example, among 10 deduplicated, readable reviews included in analysis, 3 were verified to involve compatibility, allowing the statement "compatibility issue mention rate in this sample is 3/10." This cannot be rewritten as "30% of buyers encountered compatibility issues." When a review involves two themes, theme proportions may sum to over 100%; composition charts summing to 100% are only appropriate after defining mutually exclusive categories.

Attach marketplace and product sets, sampling times, actual request parameters, return counts, deduplicated counts, readable text counts, pending review counts, and rule versions to every report. Review posted_at and reading observed_at are separated: reading a review from last year today does not mean a new incident occurred today.

Cross-week comparisons also require fixing or explaining changes in product sets, fetch order, language processing, and time ranges. Consistently reading only the same set of early reviews will not expand independent samples through increased task frequency. When catalogs do not provide complete pagination or time window guarantees, reports should position themselves as observed sample analyses rather than full-volume trend monitoring.

Reports can also borrow the derivation record concept from W3C PROV to link each issue conclusion to review versions and classification activities. This ensures that when source text is corrected, affected tags and summaries can be found; recording relationships does not prove classification correctness, and semantic verification must still be retained.

Bring Issue Lists into Practical Improvement Workflows

A conclusion worth handing to product teams should include affected confirmed specifications, representative evidence, sample denominators, unexcluded alternative explanations, and next verification steps. For example, reproduce connection issues on older models before deciding to add compatibility notes or adjust products; reviews themselves do not replace engineering testing, orders, or after-sales records.

Initial integrations can select just one authorized product to complete input verification, response checking, deduplication, source evidence validation, and manual review. Only when these steps are replayable will expanding product lists yield useful information. Next, check parameters according to Amazon capability pages and handle request states according to general documentation; do not scale up quantities first only to guess where each review came from later.