related_items: expose each variant axis separately instead of one unlabelled axis

[alistair3149]

The ask

related_items.variant_items groups items that are identical except along one attribute. Which attribute it is changes from product to product, nothing in the payload says which, and the other axes aren't reachable at all.

Three items, same payload shape, three different meanings:

item	size	grade	variant_items contains	axis
Frost-Star SL	0	C	Winter-Star SL (size 0, grade D)	grade
M4A Cannon	2	A	M5A–M9A Cannon (sizes 3-7, all grade A)	size
ADP Arms Grey	1	—	23 × ADP Arms * (same size, no grade)	colour

These are not exotic relations. M4A Cannon's variants are the size ladder, and Frost-Star SL's are the grade ladder. The API already produces both kinds. What it doesn't do is produce more than one per product, or say which one you got, so a consumer can't tell them apart without refetching every member and diffing the attributes itself.

We'd like related_items to expose each applicable axis separately and label it, rather than returning one unlabelled axis chosen per product:

"related_items": {
  "by_size":   [ ... ],   // same line and grade, other sizes
  "by_grade":  [ ... ],   // same line and size, other grades
  "by_color":  [ ... ],   // identical, other colours
  "set_items": [ ... ]    // same set, other slots (already present)
}

The attributes this needs are already on every item record (size, grade, manufacturer, type), and the API already performs exactly this grouping for one axis. Doing it for the others is the same operation. Doing it once here also avoids every downstream client reimplementing the grouping and drifting from each other.

The grouping itself is sound

Worth saying plainly, because this is a request to extend the model rather than to fix it. Across 12,331 items there are zero base_item chains that fail to self-terminate, zero is_base_variant flags contradicting base_item, and zero base items carrying two different set_names. Of 1,306 groups with more than one member (7,150 items), 99.6% vary along exactly one axis:

group shape	count	share
size and grade both fixed (colour variants)	1,168	89.4%
grade varies, size fixed	78	6.0%
size varies, grade fixed	55	4.2%
both vary	5	0.4%

The 5 exceptions are all radars, e.g. Denning grouping Abetti (size 1, grade A), Agrippa (size 2, grade A) and Backlund (size 1, grade B). Those look like genuine errors rather than a design choice.

Where a product varies along two axes, only one is reachable

The three items above each vary along a single axis, so returning one is enough. J-Span coolers vary along two, and the naming encodes both:

	S0	S1	S2	S3
grade B	Cryo-Star SL	Cryo-Star	Cryo-Star EX	Cryo-Star XL
grade C	Frost-Star SL	Frost-Star	Frost-Star EX	Frost-Star XL
grade D	Winter-Star SL	Winter-Star	Winter-Star EX	Winter-Star XL

related_items returns the column — other grades at the same size, the upgrade path. The row, the same product at other sizes, isn't available at all, despite being visible in the naming and in class_name (COOL_JSPN_S0*_FrostStar*). Nothing indicates a second axis exists.

---

Three further problems with related_items are independent of this request and cheaper to fix, so they're filed separately:

• set_name populated from the manufacturer, category or a class identifier — set_name: return null instead of substituting the manufacturer, category or class identifier #202
• items missing grouping data while their own variants are grouped without them — Items are missing related_items while their own variants are grouped without them #203
• cosmetic variant families split across several base_item groups — Cosmetic variant families are split across several base_item groups #204

Reproducing these numbers

Full sweep on 18 September 2026 — the list endpoint accepts the include, so no per-UUID fetching is needed:

GET /api/v2/items?limit=200&page=N&include=related_items&locale=en_EN

62 pages, 12,331 items, no duplicate UUIDs.

	count	share
set_name present	6,098	49.5%
base_item present	7,150	58.0%
variant_items non-empty	6,773
set_items non-empty	1,755
no grouping data at all	5,053	41.0%

Every item name above links to its record at /api/v2/items/<uuid>?include=related_items&locale=en_EN.

Happy to share the sweep script and resulting items.jsonl, or to re-run it after a change.