listing-dimensions

name	listing-dimensions
description	Pull product and carton dimensions out of a supplier listing - Alibaba, AliExpress, Amazon, 1688/Taobao, eBay, or any B2B catalogue - normalise them, cross-check them for the ways listings are routinely wrong, and feed the result into the pallet, container and cost calculations. Use when given a product URL, a screenshot of a listing, or pasted specification text and asked how it ships.

Dimensions from a listing

The calculations in this plugin are only as good as the four numbers going in: carton length, width, height and gross weight. Listings state those numbers badly, and every common failure changes a container quantity by tens of percent without looking wrong. This skill gets them, then checks them.

Never invent a dimension. Not a plausible one, not a typical one for the category, not one interpolated from a photo. If the listing does not say, the answer is a question for the supplier — a fabricated carton size produces a container quantity that looks authoritative and is wrong, which is worse than having no figure. Say what is missing and ask.

1. Get the page

Work down this list and stop at the first route that returns the packaging block. Marketplace listings are JS-rendered and bot-walled, so expect to escalate:

1. WebFetch — fine for straightforward catalogue pages and most vendor sites.
2. A fetch-to-markdown MCP tool, if one is configured. Better on pages that block the default fetcher, and egresses from wherever that server runs, which matters for geo-fenced regional catalogues.
3. A browser MCP — Claude in Chrome, Playwright, or similar. Necessary for Alibaba, AliExpress, Amazon and 1688: the packaging figures sit behind a tab or an accordion that only exists after JavaScript runs. Take the page, then read the specification and packaging sections specifically.
4. curl via Bash — last resort, useful mainly for inspecting what a block actually returns.

If every route fails, or the page renders but the packaging block is genuinely absent, ask the user to paste it. That is a normal outcome on these sites, not a failure to report as one. Screenshots are fine too — read the figures off the image rather than guessing around it.

Record the source URL and the date you read it. Listings change without notice and a quantity computed six months ago against a since-edited page is indefensible.

2. Find the right numbers

The distinction that matters most: product dimensions are not carton dimensions, and a single-unit package is not a master carton. Freight is charged on the outermost box that actually travels.

Platform	Where the figures are	What to watch
Alibaba	The Packaging and delivery block: Packaging Details, Selling Units, Single package size, Single gross weight, Package Type.	Single package size means one selling unit. Read Selling Units first: "Single item" makes it one retail box; "1 carton = 12 pieces" makes the same field the master carton. The spec table's "Product size" is the bare product.
AliExpress	Specification table, occasionally a package size; weight sometimes only in the shipping estimator.	Usually gives product dimensions only. Retail-quantity listings often have no master carton at all — ask the seller for one if you are buying at volume.
Amazon	Product Dimensions versus Package Dimensions; Item Weight versus Shipping Weight.	Third-party sellers frequently paste the product figures into both fields. If the two match exactly, treat the packaging figure as unconfirmed.
eBay	Seller-entered package dimensions, often only visible via the shipping calculator.	Frequently rounded to the nearest inch or absent.
1688 / Taobao	外箱尺寸 (outer/master carton size) is the one you want. Also 包装尺寸 (package size), 内箱 (inner box), 装箱数 / 每箱 (units per carton), 毛重 (gross weight), 净重 (net weight).	Chinese suppliers quote the master carton readily and it is usually the most reliable packaging data of any platform.
B2B catalogues (crates, totes, industrial)	Usually publish external and internal dimensions plus a litre capacity.	Use external for freight, always. See the internal-dimensions trap below.
US vendors	Inches, and gallons for capacity.	Convert with --dim-units in. Watch the near-miss footprint trap below.

3. Traps, in the order they bite

• Net versus gross weight. Freight is billed on gross. A listing quoting only net understates the payload, and payload is what binds on dense cargo.
• Product versus carton versus master carton. Three different boxes, often on the same page, sometimes all labelled "size".
• Internal versus external. Crate and tote vendors publish both, and their internal figures disagree with each other by ~10% in litres on the same mould, because some measure the top opening and some the base of a tapered wall. Both are honest; neither is the freight figure. Use external, and pass --internal to verify if the only figure available is the cavity.
• Units. 40*30*25 is centimetres on Alibaba and millimetres in a European engineering catalogue. 0.4 m and 40 cm are the same box. Each figure gets its own flag: --dim-units for the carton, --unit-dim-units for the product.
• Dimension order. L × W × H is a convention, not a guarantee. For anything with an obvious upright orientation, confirm which figure is the height — swapping height and length changes both the layer pattern and the layer count.
• Per set, per pair, per metre. A "unit" in a price list is not always a thing that occupies space.
• Volumetric weight quoted as weight. Some listings state a chargeable weight. It is a billing artefact, not the mass of the object.
• Near-miss footprints. A US tote at 24 × 15 in is 610 × 381 mm — one centimetre longer than a Eurobox. It reads as a 600 × 400 module in a catalogue and is not one: 3 per pallet layer instead of 4, 73% of the deck instead of 100%. Being close to the module is worth nothing; hitting it is worth 27%.

4. Check before you compute

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/freight.py verify \
  --package 40x30x25 --dim-units cm \
  --unit 180x130x120 --unit-dim-units mm --per-carton 12 \
  --gross-weight 6.0 --net-weight 5.2 --stated-cbm 0.03

verify re-derives everything the listing claims and reports what does not hang together:

• the CBM the dimensions imply against any stated CBM, naming a litres/m3 mix-up when the ratio says so;
• whether the claimed pack count physically fits the carton, using the same packer as the rest of the plugin — this catches "12 per carton" against a carton that holds 8, which no amount of reading catches;
• packing efficiency, flagging both a carton that is more than half air and one so tight it must be the internal cavity;
• gross-versus-net plausibility, and density in kg/m3 with which containers run out of payload before cube at that density (267 kg/m3 for a 13.6 m trailer, 347 for a 40 HC, 849 for a 20 GP — figures the tool computes from the data rather than a rule of thumb);
• units-of-measure absurdities in both directions;
• how the footprint sits on a pallet deck, and the nearest module that would do better.

Findings come back as error, check, ok, info and note. Resolve every error before computing a load — the tool prints the next commands but they are only meaningful once the inputs agree with each other. A check is a question for the supplier, and it can be carried forward as long as you state it.

5. Then compute, and keep the provenance

Hand the verified external carton figure to the other skills: pallet-quantity, container-load, packing-options if the carton is still open, freight-cost once a rate exists — or size-a-shipment to run the sequence and write a brief.

Save the normalised record so the page never has to be scraped twice. The template is examples/listing-record.json: it keeps the source URL, the date read, each figure with whether it was stated, derived or assumed, and the open questions. When you present numbers, that distinction travels with them.

6. When the listing is silent

Ask the supplier directly, and ask for the loading plan rather than the pallet:

Please confirm, for the packed goods: master carton external dimensions (L × W × H, in cm), gross weight per carton, units per carton, and whether the container will be floor loaded or palletised. If palletised, the pallet size and the maximum gross build height. If the pallets are wooden, please confirm ISPM 15 heat treatment with the IPPC mark and send the certificate with the documents.

That wording gets a usable answer where "what size are your boxes?" gets a paragraph. Once they reply, run verify on their figures too — a supplier's numbers are a claim, not a measurement, and this is exactly where a 25% difference in units per container gets caught before it is booked.