A product listing sells in six shades. Your planning treats them as one line item. Two of those shades are almost the entire business and two are dead stock, and nothing in your reporting distinguishes them.
Variant-level demand is one of the few genuinely hard-to-get signals in marketplace data, and it changes assortment decisions more than almost anything else.
Why it is hard to get
Marketplace listings report sold counts at the listing level. The variant breakdown — which size, shade or pack actually moved — is not in the listing payload, and it is not in most datasets either. It has to be collected specifically.
That is what variant_sold_v1 does: per-variant sold counts for a list of items, up to 50,000 items in a single job, one country per request.
The two shapes you are looking for
Concentrated demand. One or two variants carry most of the volume. This is the common case and it usually means the range is too wide. The tail variants are consuming working capital, shelf attention and photography budget to produce very little.
Even demand. Volume spreads across the range. This means the range is doing real work — different variants are serving genuinely different buyers — and cutting it would cost you customers rather than saving you money.
The mistake is assuming the first without checking. Ranges get pruned on intuition constantly, and intuition tends to protect the variants the team likes rather than the ones that sell.
Running it
Submit a list of items, each with its item id, shop id and country. Poll until complete. Report the sold count per variant, ranked, with each variant's share of the product total.
Billing is 10 credits per item, and this endpoint has a useful property: it deducts only on approval. If the job is rejected or times out after 24 hours, you are not charged.
Like the other deep endpoints it is approval-gated and processes 08:00–18:00 GMT+8, so plan it as an analysis run rather than a nightly job.
Where the item list comes from
This is the step people skip. You need item ids, and picking them by hand reintroduces exactly the bias you were trying to remove.
Better: export the category from the Data API, rank by GMV, and take the top hundred SKUs. Now your variant analysis covers what the category actually buys rather than what you already stock. A top-100 slice of one recent month costs a few dollars, and the free dry-run estimate tells you the exact figure first.
That pairing — panel picks the list, collection deepens it — is the pattern behind most of the useful workflows here.
What it changes
Three decisions, concretely. Which variants to discontinue. Which to make sure never goes out of stock, because it is carrying the listing. And, for a competitor's product rather than your own, which variant to match when you launch against them — because matching their dead shade is free of any competitive value.
Recipe 2.6 in the agent skill has the prompt.