Storefront
Products & catalog
Reading the shop: products, variants, collections, search.
const { products, total } = await mercestack.getProducts({
limit: 24,
collection: "new-arrivals",
sort: "newest",
});
const product = await mercestack.getProduct("air-force-1");
const results = await mercestack.search("running shoes");
const collections = await mercestack.getCollections();
const categories = await mercestack.getCategories();Products are addressed by handle — the URL-safe name, like air-force-1 — or by id. Storefront routes should carry the handle; it is stable, readable and what a customer sees.
Variants and options
A product varies along options (Colour, Size) and each combination is a variant with its own SKU, price, barcode and stock. You add a variant to a cart, never a product.
product.options;
// [{ name: "Colour", values: [{ value: "Black", swatch: "#000" }, …] },
// { name: "Size", values: [{ value: "42" }, …] }]
product.variants[0];
// {
// id: "…",
// sku: "AF1-BLK-42",
// priceMinor: "4500000",
// compareAtMinor: "5000000", the "was" price, or null
// currency: "NGN",
// available: 7, null when stock is not tracked
// availableForSale: true, what your button should read
// selectedOptions: [{ name: "Colour", value: "Black" }, { name: "Size", value: "42" }],
// }
product.priceRange;
// { minMinor: "4500000", maxMinor: "6200000", currency: "NGN" }
// For "from ₦45,000" on a card, without loading every variant.Availability
availableForSale is the flag to render against. It already accounts for whether stock is tracked at all and whether the merchant allows backorders, so your button does not have to combine three fields and get it wrong differently from us.
available is advisory. Stock is only truly held at checkout — it tells a shopper what to expect without promising it.