Amazon variants scraper: map the whole product family, sizes and colours

Give it one product. Get back every sibling it has: each size, each colour, each pack count, with the ASIN of each and, crucially, what varies between them.

An Amazon listing is rarely one product. A shirt is fourteen ASINs pretending to be one page, and which one you land on depends on which link you followed. If you are tracking a price, comparing against a competitor, or building a catalogue, working on one ASIN when there are fourteen means you are working on a fraction of the thing and do not know it.

Seventeen fields per product, nineteen marketplaces, and no dependence on the buy box, so this Actor works where the price ones return nothing.

What each row carries

The family. variantAsins is every sibling ASIN. variantCount is how many. parentAsin is the listing they all hang from, when Amazon exposes it.

What actually varies. variantAttributes names the dimensions of the family: ["size", "color"], or just ["style"], or nothing at all. This is the field that tells you whether you are looking at a size run or a colour run, and it is the one most tools do not return.

Enough to identify the one you have. colour, material, unitCount, plus title and brand. When a family has fourteen members these are how you tell which row is which.

Enough to act on it. price, currency and inStock for the ASIN you asked about, plus image.

How the family is read, and why that took two sources

Amazon puts the variant data in two different places depending on the page, and an earlier version of this engine looked in only one of them.

It searched for element names like variation_color_name, which some pages carry. Other pages keep the same information inside a block of page state, and those came back with no variants at all. The fix was to read both, and it took the variant attribute coverage from one product in six to five in six.

That is why variantAttributes is a field here rather than a footnote: getting it required knowing about the second source, and it is the difference between "this product has 6 siblings" and "this product comes in 6 sizes".

Every field it returns

Seventeen per product. Deliberately narrow: this Actor answers one question and gives you enough context to act on the answer.

Price and offer

Field	What it holds
price	Current price from Amazon's own buy box data
currency	Three-letter code, from the page itself

Stock and delivery

Field	What it holds
inStock	True, false, or null when Amazon does not say

Identity and catalogue

Field	What it holds
asin	The product id
parentAsin	The parent listing, for variant families
title	Full product title, shortened only past 1000 characters
brand	Brand name
marketplace	Which shop this row came from
url	The page this was read from
scrapedAt	Timestamp of the read

Description, media and variants

Field	What it holds
image	Main image at the largest size Amazon offers
variantAsins	Sibling products in the variant family (this is what you are charged for)
variantCount	How many variants there are
variantAttributes	What varies, such as size and colour

Specifications, pulled apart

Field	What it holds
colour	Colour
material	Material
unitCount	How many units in the pack

What it charges for

This Actor charges on variantAsins, and on nothing else.

A product with no siblings is a real and useful answer, but it is not the answer this Actor sells. If a listing turns out to be a single standalone product, the row still arrives with the price, the colour and the rest, and you are not charged for it.

That means running it across a mixed list is safe: you pay for the families and not for the singletons. Measured across a sixty product run on 26 August 2026, fifty-two of fifty-eight delivered products carried a family, so roughly one row in ten arrived free.

A real row

asin                B00FXNABPI
parentAsin          null
title               Amazon Basics Slim Velvet Non-Slip Suit Hangers
brand               Amazon Basics
variantCount        20
variantAsins        20 ASINs
variantAttributes   ["size", "color"]
colour              Black
material            Velvet
unitCount           30
price               8.95
currency            GBP
inStock             true
image               https://m.media-amazon.com/images/I/...
scrapedAt           2026-08-26T09:14:22.031Z

Twenty siblings varying by size and colour. No parent ASIN on that listing, which is common: Amazon does not always expose it, and its absence does not mean the family is not there.

What to do with the sibling ASINs

variantAsins gives you the list. To get full data on each sibling, feed that list back in as input, either to this Actor or to one of its relatives. Two runs, and you have the whole family with prices.

This Actor deliberately does not expand the family for you. Doing so would mean deciding on your behalf how many siblings are worth fetching and charging you for that decision. On a catalogue of a thousand parent listings with an average of six siblings, that decision is the difference between a thousand charged rows and six thousand. Handing you the list and letting you choose is cheaper and clearer.

The usual pattern is two steps: run this Actor on your list, collect the union of all variantAsins, then run the price tracker or the stock checker on that union.

What to put in

ASINs or product URLs. Paste them in any shape: a bare B08N5WRWNW, a full URL with tracking parameters, a spreadsheet cell that still says ASIN: B08N5WRWNW. Duplicates are removed across everything you give it.

A search term or category link, if you want to find which products in a category are families and which are standalone. That is a useful question on its own: a category full of fourteen-variant listings is a different competitive picture from one full of single products.

Settings worth knowing about

Setting	What it does
marketplace	One of nineteen. Variant families differ per marketplace: the same parent listing can carry six sizes in the United States and three in Germany.
proxyCountry	Leave empty and it follows the marketplace.
maxItems	Hard ceiling on delivered products. Zero means no ceiling.
maxItemsPerList	How many products to take from each search term or category link.
maxListPages	How deep to walk each list.
lanes	How many products are read at once. Eight by default. Variant data does not come from the buy box, so pushing to sixteen costs less here than on the price Actors.
maxAttempts	Attempts per product, each from a different address. Twelve by default.
residentialFallback	Off by default. Measured 2026-08-26: on it cost roughly six times as much and returned two more products out of sixty.
economical	Leave it off. The variant block sits in the page state rather than at the top, so hanging up early costs you the field you came for.

How it works, in plain terms

Amazon refuses roughly six requests in ten to an address it has not seen before. Every product gets up to twelve attempts, each from a different exit address, and the same address is never used twice in a row. Addresses that work are remembered for the rest of the run and tried first. When refusals climb the runner slows down instead of pushing harder, because pushing harder is how a whole run gets locked out.

Anything still refused at the end goes into a second pass at half speed, using only the addresses that already proved themselves.

The retry rule follows the variant family rather than the price, so a page that handed over twenty sibling ASINs on the first attempt is not asked again just because Amazon left the buy box out.

Reading the run log

Done: 16 charged (+3 delivered without a price, free), 1 refused by Amazon, 0 other. 559 KB per charged result, 109 attempts in total.
Exit addresses: 74 used, 1 proven good, 11 burned.
Attempts by outcome: {"refused by Amazon":71,"ok":16,"http_500":2,"page did not carry the field this Actor needs":19,"delivered, product unavailable":1}

charged is products that came back with at least one sibling. The bracketed number are the standalone products, delivered and free.

If a run ever delivers rows and charges for none of them, the log says so in capitals at the bottom.

Reliability, measured

Three consecutive runs of twelve products on 26 August 2026, at the default settings:

run 1   12 of 12 delivered, 9 with a variant family
run 2   12 of 12 delivered, 9 with a variant family
run 3   11 of 12 delivered, 9 with a variant family

And one run of sixty products the same day: 58 delivered, 52 with a variant family, in 7.5 minutes.

Worth reading out of that: the longer run has the better delivery rate, 97 percent against 97, and that is not luck. The engine spends the first products of a run working out which exit addresses Amazon is tolerating today, so a short run pays the whole warm-up over fewer products. If delivery matters more to you than turnaround, batch your work into larger runs.

The second is the residential switch, and the honest version is less dramatic than it sounds. Measured 26 August on the same sixty products, twice: with the switch off, fifty-one came back with the field this Actor charges on, for $0.0205 of platform usage. With it on, fifty-three came back, for $0.1192. Two more products for roughly six times the cost.

That is why it is off by default. It is in your input form, so if a marketplace is refusing almost everything you can turn it on and pay for the difference.

What you can build with it

A complete price watch. Expand every parent listing into its siblings before you start tracking, so you are not watching the black one while the competition discounts the blue.

A catalogue import. One row per family gives you the structure; a second run on the sibling list gives you the detail.

A size-run audit. variantAttributes across a category tells you whether competitors offer three sizes or nine, which is a stocking decision as much as a listing decision.

A cannibalisation check. When your own listing sits in a family with a competitor's, variantCount and variantAsins show you exactly who you are sharing a page with.

A gap finder. A family of six colours where two are permanently out of stock is a gap, and the stock checker in this family will tell you which two.

Working it into your stack

Every run writes to a dataset you can download as CSV, JSON, Excel or XML, or pull through the API.

One shape note: variantAsins and variantAttributes are lists, so a strict flat export will stringify them. If your destination wants one row per sibling rather than one row per parent, expand them on the way in; the API makes that a few lines.

Schedules take a cron expression. Variant families change when a seller adds a colour, which is rarely, so weekly is usually plenty.

Marketplaces

Nineteen, from amazon.com to amazon.co.jp, read in their own language.

Variant data does not depend on the buy box, so this Actor works on marketplaces where prices do not. Measured on amazon.de, where no product returned a price: variant data came back normally. The price column will be empty there, the family will not.

Worth knowing: families are per marketplace. The same parent listing can carry six sizes on amazon.com and three on amazon.de, and that difference is real rather than a scraping artefact.

Pricing

Four dollars per thousand products with a variant family, plus three cents to start a run.

Mapping a hundred listings costs forty-three cents: a hundred times four tenths of a cent, plus the three cent start fee. You are not charged for standalone products or for products that never arrived, and platform usage is included.

Because the charge is on the family rather than on the row, a catalogue that turns out to be mostly single products costs you very little to find that out.

The rest of this family

Eleven Actors on one engine. The natural next steps after mapping a family:

• Amazon Price Tracker on the sibling list, so you watch every colour rather than one.
• Amazon Stock Checker to see which siblings are actually buyable.
• Amazon Product Specs when each sibling needs its own catalogue row.
• Amazon Product Scraper for all sixty-four fields on the siblings that matter.

Questions people ask

Why is variantAttributes sometimes empty when variantAsins is not. Because Amazon lists the siblings without naming what distinguishes them. It happens on older listings. You still get the ASINs.

Why is parentAsin often empty. Amazon does not expose it on every page. When it is there you get it; when it is not, variantAsins still gives you the family.

Does the list include out of stock siblings. Yes. Amazon lists them and so does this Actor. Whether a sibling is buyable is a separate question, and the stock checker in this family answers it.

Is the ASIN I asked about in variantAsins. Yes, the list is the whole family including the one you asked for. Deduplicate on your side if you are building a union.

How many products can it handle. No built-in ceiling. Sixty products took 7.5 minutes on the measured run, so a hundred is around 13.

What it does not collect

No review text, no reviewer names, no customer questions, no seller names. Those are personal data, and scraping them out of a public website is almost always a GDPR problem in Europe.

Legal note

This Actor reads public pages and takes product facts: which products belong together and what distinguishes them. Business information about items, not information about people.

You are responsible for what you do with the output. Check Amazon's terms for your own use case.