What you need to build is a field contract, not a data pipeline. The failure mode of an Amazon product data JSON API is seldom “no data came back” — it is data that looks correct and is not. The same price field means different things across variants. size holds RAM, not storage. The asin inside a review payload belongs to a different product than the one you requested. A field contract exists to pin these boundaries down before you write the parser: which fields are required, which are nullable, what an empty value means, and whether a key keeps its unit across variants. This article takes two child ASINs sharing one parent (B0GP8D698X) plus a page of reviews, walks through every trap the real payloads contain, and ends with a field dictionary, null-value rules, a schema diff script, and contract tests you can run today.

1. Why field-level evaluation beats endpoint-level evaluation

The most common mistake in vendor evaluation is making “can this API return product data” the acceptance criterion. Every vendor passes that test. The real differences live one layer down, at the field. The same concept takes different shapes across vendors, across variants, and across endpoints within one vendor — and those differences surface as dirty data after you ship.

Here is a case we measured. Take one iPhone 15 Pro Renewed, 512GB, in white and in black. Both are children of parentAsin B0GP8D698X. Their strikethroughPrice objects share a structure, share a type, and are non-empty — yet they carry different meanings. The white variant returns {"key": "List Price", "value": "$649.00"}. The black variant returns {"key": "Typical price", "value": "$629.95"}. If your parser reads strikethroughPrice.value and calls it “the original price,” you have just written a manufacturer’s suggested retail price and a 90-day median transaction price into the same column. The insert succeeds, the dashboard renders, and the comparison is wrong.

Field-level defects share one property: they are silent. No parse exception, no null, no failed job — just two incomparable quantities averaged together. That rules out error-based detection. The only viable test is whether your assumption about a field holds across every variant and every marketplace. That is the job of the field contract. It is not documentation. It is a set of assertions.

One more property of fields gets overlooked: nullability itself carries business meaning. In the same two variants above, one shipper is an empty string and the other is "Amazon". One inStock reads " Only 13 left in stock - order soon. " and the other reads " In Stock ". Treat an empty shipper as “the shipper is blank” and every downstream delivery-time calculation drifts. An empty value is never “no information.” It is either “this field does not apply to this variant” or “the value was unavailable at capture time” — and those two cases need different handling.

2. Divide the objects first: four classes, four cadences

Before writing a field dictionary, group the payload by business object. The fields are not a flat bag of keys. They belong to four objects, each with its own update frequency, stability, and usage pattern. Getting this division right is what makes the required-versus-optional call defensible.

Identity fields. asin, parentAsin, title, itemName, brand, category_id, breadCrumbs. They answer “what is this product and where does it sit in the category tree.” They are stable, almost never change, and serve as the source of every join key. But watch the asin ambiguity — the same key means “the product you requested” in the product endpoint and “the product this review belongs to” in the reviews endpoint. Those are not always the same, as section 4 shows.

Transaction fields. price, strikethroughPrice, savingsPercentage, coupon, inStock, shipper, has_cart, seller. They answer “what does it cost right now, is it available, who sells it.” This is the fastest-moving part of the payload, fluctuating by the minute, and the part most business logic depends on. It also has the highest null rate and the least consistent units.

Reputation fields. star, rating, ratingDistribution, reviews, aiReviewsSummary. They answer “how is it received.” Daily cadence, but layered on the inside: distribution percentages can sit still for a long time while review content keeps accumulating.

Spec fields. attributes, productOverview, features, productDescription, variantDetails, images, videos. They answer “what are the technical parameters.” Most numerous, least consistent in structure, and the richest source of buried traps — attributes came back with 48 entries on one variant and 49 on its sibling, with different key sets.

Once grouped, the required-versus-optional rule writes itself: identity fields must be non-empty; transaction fields must permit null but every null needs defined semantics; reputation aggregates and reputation details need separate models; spec fields must be handled as “use it if present, degrade if absent” and never given strict validation. Marking spec fields required is the standard beginner error — it makes the pipeline throw on any product with incomplete attribute coverage, and incomplete attribute coverage is the norm on Amazon, not the exception.

3. Required vs optional: never infer business nullability from key presence

Here is the counterintuitive rule: the presence of a key does not make it business-optional, and an empty string does not mean the field is absent. Key presence and business nullability are independent dimensions. Conflating them produces two opposite modeling errors.

At the code level, the fix is to model three distinct states. The TypeScript below separates “required and non-empty,” “required but nullable,” and “optional.” The key move is using | null rather than ? to express “the key is always there, the value may be blank.”

// Field contract: three nullability states, modeled as three types
type NonEmpty<T> = T;                 // always present, never blank
type Nullable<T> = T | null;          // always present, value may be blank
type Optional<T> = T | undefined;     // the key itself may be absent

interface ProductContract {
  // --- Identity: required, non-empty ---
  asin: NonEmpty<string>;
  title: NonEmpty<string>;
  parentAsin: NonEmpty<string>;

  // --- Split title fields: key always present, value may be empty string ---
  // Legacy listings always return an empty itemHighlights; do not use ?
  itemName: Nullable<string>;
  itemHighlights: Nullable<string>;

  // --- Transaction: key always present, value may be blank ---
  price: Nullable<string>;             // e.g. "$628.95", currency symbol included
  inStock: Nullable<string>;           // free text, not an enum
  shipper: Nullable<string>;           // may be ""; "" != "no shipper"
  savingsPercentage: Nullable<string>; // e.g. "6%", percent sign included

  // --- Structured price: nested, and key is NOT a stable enum ---
  strikethroughPrice: Nullable<{
    key: string;   // observed: "List Price" and "Typical price"
    value: string;
    tip: string;
  }>;

  // --- Spec fields: always optional, absence means degrade ---
  attributes?: Array<{ key: string; value: string }>;
  productOverview?: Array<{ key: string; value: string }>;
  size?: string;                      // note: this is RAM, not storage capacity
}

Three parts of that definition deserve their own paragraph, because each maps to a measured trap.

First, itemName and itemHighlights. As of 2026-07-27 Amazon splits the product title into two parts: itemName is the title body, itemHighlights is the title suffix (material, use case, selling points). The product we sampled is a legacy listing that has not been migrated. On such listings itemName equals the full title and itemHighlights is an empty string. Assume that itemName plus itemHighlights reconstructs the full title and the second half drops out of your index on legacy listings. Assume itemHighlights always has a value and every legacy listing fails. The correct handling: use itemName, and fall back to title when itemHighlights is empty.

Second, size. This product returns size: "8 GB". It reads like storage. It is RAM. In the same payload, the attribute Memory Storage Capacity is "512 GB" and RAM Memory Installed is "8 GB". Write size into a capacity column and every storage filter you run is off by a factor of 64. The problem compounds because the field’s meaning is not stable across categories: for apparel size is a garment size, for phones it has been repurposed as a memory spec. Identical field name, different semantics.

Third, size inside variantDetails. That is a variant option value, and its values look like " 512GB " — leading and trailing spaces, no space between number and unit. It has nothing to do with the top-level size of "8 GB". The word “size” appears twice in this JSON, once meaning RAM and once meaning storage. Same-name-different-meaning fields are what a contract exists to record.

4. Variants: field drift inside a single parent

Variants are where field evaluation concentrates, because the traps are densest and only appear under comparison. We ran a field-level diff across two children of parentAsin B0GP8D698X. The results:

Two rows deserve a pause.

Resolution strings do not follow one spelling. Two color variants of one product: white returns "2556 × 1179 pixels" (fullwidth multiplication sign U+00D7, spaces between numbers), black returns "2556x1179 pixels" (lowercase letter x, no spaces). Same physical spec, unequal strings. If you exact-match on spec text — for filtering, for deduplication — these two variants register as different products. Spec normalization has to happen before storage: unify the multiplication sign, the case, and the whitespace, then compare. This is not a vendor defect. The Amazon page itself is inconsistent, and every scraper reproduces it as written.

The attributes key set drifts. The two variants carry 48 and 49 entries; the extra key is “Model Series,” present on black and absent on white. You therefore cannot premise anything on “every variant has attribute X,” and you cannot expand the array into fixed columns. Treat attributes as a sparse map: index by key, apply defaults on absence, never assume completeness. The same applies to productOverview, which is not a superset — it covers the page’s “important information” block only, overlapping with attributes without being equal to it. In fact both contain RAM and storage, under key names that differ by a word (“RAM Memory Installed Size” vs “RAM Memory Installed”).

The practical modeling advice is to group by parentAsin. asin identifies a variant; parentAsin identifies the product family. Within a family, ratings and reviews are shared (both variants return (5258)) while price and stock are independent. Storing the two levels apart is what lets you do reputation analysis at family level and price monitoring at variant level. Collapse them and you get the classic error: treating one variant’s rating as the family rating, or spreading a family review count across individual variants.

The review payload’s asin field is not the ASIN you requested

This is the single most important finding in this article, and the best illustration of why a field contract has to be verified field by field. We requested reviews for ASIN B0CMZFCQ6D. The API returned 10 reviews. We inspected the asin field on each:

// requested asin = B0CMZFCQ6D; asin distribution across 10 returned reviews
B0CMYXFK3R  ×2
B0CMZL2TJ9  ×3
B0CMZBXYWX  ×1
B0CMZ7L14T  ×1
B0CRJRNTNS  ×1
B0CMZ9KS3G  ×1
B0CMZCGQDK  ×1
─────────────────────────────
distinct ASINs = 7
reviews whose asin equals the requested asin = 0

Not one of the ten reviews carries the ASIN we requested. This is not an API defect. It reflects how Amazon attributes reviews: reviews attach to specific variants, and the variants of a Renewed product family share a review pool that the page aggregates for display. Each review’s asin tells you which variant it came from.

That fact drives two decisions. First, if your code writes reviews[].asin back onto the main product record, it corrupts the data — reviews end up attached to the wrong product. Second, if you need “this variant’s own” reviews, you must filter by asin after receiving the payload; you cannot assume the response was scoped to your request. The contract line reads: reviews[].asin identifies the specific variant and may not equal the requested asin; filter on that field for variant-level reviews; aggregate by parentAsin for family-level reputation.

There is a finer format divergence hiding in the same field name. The reviews endpoint returns star as "1.0 out of 5 stars", while the reviews array inside the product payload returns "5 out of 5 stars". The first carries a decimal, the second is an integer. One field name, two endpoints, two formats. Share a single parser between them and one side mis-parses or truncates without an error. Extract the numeric value and compare as a number; never compare these as strings.

5. Null rules: keep null, empty string, and absent apart

Null handling is the part of a contract that is easiest to write and easiest to implement wrong. The principle is one line: distinguish “not applicable,” “unknown,” and “unavailable,” and define a downstream behavior for each. The table below maps every null shape we observed to its semantics.

In implementation, do not normalize empty strings into null for uniform handling. The table shows the two carry different information: an empty shipper means the shipper was not captured this run, while a null reviews means this product page has no review module at this capture. Merge them into one empty state and you lose both the ability to measure a vendor’s field fill rate and the ability to tell, when fill rate drops, whether the cause is collection or a page change.

Null rules must also cover a scenario that is easy to miss: the same field can have different nullability across variants. On one product, one variant has a shipper value and the other does not; one reads “only 13 left” and another reads “in stock.” That is normal variation, not a data quality problem. Your alerting must count “field is empty” apart from “field value is anomalous,” or you will fire on every run for variants that are empty by nature.

inStock is free text, not an enum

inStock deserves its own section because it is the most misused field in the payload. The two observed values are " Only 13 left in stock - order soon. " and " In Stock " — note the surrounding whitespace. The field carries Amazon’s raw page copy. Its forms include in-stock, only-N-left, and unavailable-for-now, and the wording changes over time.

The right approach is to store it as raw text and derive an enum in a second step:

import re

def normalize_stock(raw: str | None) -> tuple[bool | None, int | None]:
    """Normalize inStock free text into (available, units_left).

    (None, None) means undeterminable; the caller must treat it as
    unknown and must not default to available.
    """
    if not raw or not raw.strip():
        return None, None
    text = raw.strip().lower()
    if "left in stock" in text:
        m = re.search(r"(\d+)\s+left in stock", text)
        return True, int(m.group(1)) if m else None
    if "in stock" in text:
        return True, None
    if "unavailable" in text or "out of stock" in text:
        return False, 0
    return None, None   # unrecognized form; keep raw text for review

The most important line is the final return None, None. Faced with an unrecognized stock string, the correct behavior is to mark it unknown and preserve the raw text — not to default to available. Reading out-of-stock as available breaks your restock alerts. Reading available as out-of-stock triggers pointless emergency repricing. Both mistakes cost money; “unknown” does not. It surfaces an unmapped form so you can extend the rules.

6. Versioning: how to handle field drift

Fields change. Amazon splits title fields (the itemName / itemHighlights structure in our sample postdates 2026-07-27), adjusts attribute key sets, and ships page redesigns that introduce new field shapes. Vendors change response structures too. A field contract is therefore not a static document; it needs a versioning strategy to absorb change.

Ours is to version the contract and detect drift with a schema diff. Three steps.

Step one: freeze the field inventory as a snapshot. After each evaluation or vendor change, sample a set of products and record every field path (strikethroughPrice.key, attributes[].key), its type, nullability, and frequency. That file is the machine-readable form of the contract.

Step two: diff the snapshot against new samples. The script below compares two field snapshots and reports added fields, removed fields, and type changes. Its value is turning “a field changed without notice” into a reviewable diff.

import json
from collections import defaultdict

def flatten(obj, prefix: str = "") -> dict:
    """Flatten nested JSON into {path: type}; arrays are suffixed with []."""
    out = {}
    if isinstance(obj, dict):
        for k, v in obj.items():
            out.update(flatten(v, f"{prefix}.{k}" if prefix else k))
    elif isinstance(obj, list):
        out[prefix + "[]"] = "array"
        for item in obj[:5]:          # first 5 samples only; keep it bounded
            out.update(flatten(item, prefix + "[]"))
    else:
        out[prefix] = type(obj).__name__
    return out

def schema_diff(baseline: dict, current: dict) -> dict:
    added    = sorted(set(current) - set(baseline))
    removed  = sorted(set(baseline) - set(current))
    retyped  = sorted(
        p for p in set(baseline) & set(current)
        if baseline[p] != current[p]
    )
    return {"added": added, "removed": removed, "retyped": retyped}

def load(path):
    with open(path, encoding="utf-8") as f:
        return flatten(json.load(f))

if __name__ == "__main__":
    diff = schema_diff(load("baseline.json"), load("current.json"))
    for label, items in diff.items():
        print(f"[{label}] {len(items)}")
        for item in items:
            print("   ", item)
    # exit code usable in CI: any field change marks the run for review
    raise SystemExit(1 if any(diff.values()) else 0)

The exit code is deliberate: any difference returns 1 so the pipeline marks the run “needs human review” rather than failing outright. Added fields are harmless in most cases and can be accepted without review. Removed fields and type changes can break parsing. A contract test is a warning system, not a gate — it stops what needs human judgment without blocking routine releases.

Step three: wire contract tests into CI. Three classes of test. Structural assertions validate that required fields exist and are non-empty, and that nullable fields have the right type. Semantic assertions verify the known traps using fixed samples — that strikethroughPrice.key classifies right whether it reads List Price or Typical price, that the two resolution spellings normalize to equal, that reviews filtered by asin never contaminate the main product record. Fill-rate assertions compute the non-empty ratio per field across the sample set and alert when it falls below baseline — the earliest signal that an upstream page change has dropped a batch of fields.

All three classes answer one question: is the structure right and the semantics stable? None of them answer a second question: how old is this value? A field can fill on every single call and still carry a two-hour-old cached snapshot. Freshness needs its own check, which we wrote about in how to measure whether real time is real — a three-clocks model to date the payload, five cache signatures to classify it, and a 48-hour protocol to confirm it. Field contracts and freshness verification are two parallel gates, and skipping either leaves a blind spot.

7. The field dictionary: what to request

Everything above collapses into one table. These are the fields most often needed for product monitoring and analysis, grouped by the four objects, with type, nullability, and the handling note that matters. Use it as the starting point for your team’s contract.

One further denominator problem belongs in the record. For the same product, the product endpoint returns rating as "(5258)", while the reviews endpoint filtered to critical returns totalReviews as "942". The two numbers have different denominators: the former is the review count displayed on that variant’s page, the latter the number of results under the current filter. Put them in one column and chart the trend and you get a meaningless curve. A contract must annotate the denominator for aggregate fields, not just the type.

8. Cost and efficiency: the trade-offs field choices create

Field evaluation ends at a cost question: which fields do you pay to collect at high frequency, and which do you collect on a slow cycle. Collecting everything at the highest frequency wastes budget. Collecting everything on the slowest cycle makes key decisions wrong. Tiering is the only sound answer.

Transaction fields (price, stock, Buy Box, coupons) move fastest and drive business actions — worth minute-level polling. Reputation aggregates (rating, rating count) are fine daily, since their day-over-day movement is small. Review content and spec fields can run weekly unless you are tracking review-bombing or a competitor’s listing revision. Identity fields are collected once and reused; no need to re-request them.

That tiering sets the cost structure. Per product, minute-level price polling means thousands of calls a day, while weekly spec collection means dozens. If your scenario only needs daily prices, do not pay for real-time capability. If you are monitoring a price war, a daily snapshot will have you making wrong decisions for the better part of a day after a competitor repriced. Set the tolerated delay per field first, then choose the cadence, and only then compare vendors — reverse that order and the price comparison is meaningless.

Field acquisition cost can also be optimized through endpoint choice. Product detail endpoints return dozens of fields per call at low unit cost, while review, ranking, and category endpoints often bill per page or per object at a higher unit cost. Design the flow to carry identity, transaction, and spec fields on the product endpoint, call the reviews endpoint only when review detail is needed, and prefer a critical-star filter to raise signal density per record. Choosing endpoints by field requirement rather than stacking every field an endpoint can return is the most direct cost control available. For the pricing structure itself, see how to compute cost per thousand usable records.

Replace verbal agreement with runnable contract tests

A field contract that never becomes a test is just documentation, and documentation does not alert you when a field drifts. Here are three minimal contract tests covering the trap classes we measured.

import re
import pytest

# ---------- Trap 1: strikethroughPrice.key semantics are unstable ----------
@pytest.mark.parametrize("payload,expected", [
    ({"key": "List Price",    "value": "$649.00"}, "list_price"),
    ({"key": "Typical price", "value": "$629.95"}, "typical_price"),
])
def test_strikethrough_key_is_classified(payload, expected):
    """The two variants' keys mean different things; classify, never merge."""
    assert classify_strikethrough(payload["key"]) == expected

def classify_strikethrough(key: str) -> str:
    k = key.strip().lower()
    if "list price" in k:
        return "list_price"
    if "typical" in k:
        return "typical_price"
    return "unknown"          # unmapped forms must surface for review

# ---------- Trap 2: spec text does not follow one spelling ----------
def normalize_resolution(value: str) -> str:
    """'2556 x 1179 pixels' and '2556x1179 pixels' must normalize equal."""
    v = value.replace("\u00d7", "x").replace("\u00d7", "x")
    v = re.sub(r"\s+", "", v.lower()).replace("pixels", "")
    return v

def test_resolution_writing_variants_are_equal():
    assert normalize_resolution("2556 \u00d7 1179 pixels") == \
           normalize_resolution("2556x1179 pixels")

# ---------- Trap 3: review asin != requested asin ----------
def test_reviews_are_not_implicitly_filtered(reviews, requested_asin):
    """Returned reviews may all belong to sibling variants; filter on that field."""
    own = [r for r in reviews if r["asin"] == requested_asin]
    others = [r for r in reviews if r["asin"] != requested_asin]
    assert len(own) + len(others) == len(reviews)
    # the point: writing back without filtering corrupts the product record
    if others:
        assert all(r["asin"] != requested_asin for r in others)

# ---------- Fill-rate monitor: earliest signal of an upstream change ----------
def test_fill_rate_does_not_regress(products, baseline: dict):
    for field, floor in baseline.items():
        filled = sum(1 for p in products if p.get(field) not in (None, "", []))
        rate = filled / len(products)
        assert rate >= floor, f"{field} fill rate {rate:.2%} below baseline {floor:.2%}"

The three tests share one property: they assert normalized equality and explicit unknowns, not constant values. Upstream spellings for specs, stock copy, and discount baselines will change; hard-coded constants produce constant false alarms, and a test suite that cries wolf gets ignored. Asserting equivalence after normalization survives spelling changes and fails only when semantics shift.

9. How this plays out on Pangolinfo

Every field sample in this article came from putting two sibling products and one page of reviews through this contract process. The traps — the title-field split boundary, the size semantics drift, the unstable discount baseline, the review asin not matching the request — were measured, not read off a spec sheet. That is the posture we recommend: do not trust what a field name appears to mean; diff two variants of the same parent and most of the problems surface on their own.

Pangolinfo’s Amazon Scraper API returns structured JSON covering all four field classes above, and supports ZIP-code-specific collection so prices and delivery estimates match the region you care about. We hold a 99% success rate and 3-second median latency at over 30 million calls a day, with field fill rate monitored as its own metric. For review detail, the Amazon Review API filters by star rating, sort order, and media type, so you can pull critical reviews only and raise signal density per record.

On integration: if you are building a pipeline rather than pulling data once, start with which layers you still own in an Amazon data pipeline and decide where the field contract lives. If you are still comparing vendors on field coverage, this field-level comparison of the major Amazon data APIs applies one measuring stick across all of them. On the implementation side, the Python and Node.js walkthroughs already contain runnable skeletons, and field validation slots in right after the parse layer. For exact endpoint field definitions and response samples, see the Pangolinfo developer docs.

10. Start from the field contract, not the integration

Back to the opening question: evaluating an Amazon product data JSON API is not about whether data comes back, but about whether each field is usable once it does. Using two variants of the same parent plus one page of reviews, this article pulled out five facts that belong in a contract: title fields have a split boundary, size drifts by category, the discount baseline key is unstable, review asin is not the requested product, and one field name can carry two formats across two endpoints.

Not one of those five raises an exception, and every one of them becomes a wrong decision after launch. The value of a field contract is not documentation completeness; it is turning silent defects into executable assertions. The path there is short: group fields into the four objects, diff two variants of the same parent, write each measured trap as an assertion in CI, and add fill-rate monitoring as your upstream-change early warning.

Do those four things and your pipeline’s understanding of the payload upgrades from “key names” to “semantics.” That is the line between collecting data as an asset and accumulating it as technical debt.

Data note: all field samples in this article were collected on 2026-09-14 via Pangolinfo MCP tools on the amz_us marketplace. Product samples are B0CMZFCQ6D and B0CMZ5KBNS under parentAsin B0GP8D698X; the review sample is one page of critical reviews for B0CMZFCQ6D. Field values are quoted verbatim.