Products

Browse, create, update, and delete products using the Commerce SDK.

Browse Products

Fetch a paginated list of products:

const products = await commerce.productBrowse({
  limit: 10,
  offset: 0,
});

Parameters

Get a Product

Fetch a single product by ID or slug:

const product = await commerce.productGet({
  idOrSlug: "classic-tee",
});

Response

{
  id: "prod_abc123",
  name: "Classic Tee",
  slug: "classic-tee",
  summary: "A comfortable everyday tee",
  description: "Full markdown description...",
  images: ["https://..."],
  taxRate: { id: "tax_abc", name: "Standard VAT", rate: 23, label: null },
  variants: [
    {
      id: "var_xyz",
      sku: "CT-SM-BLK",
      price: "2500",       // net, in cents
      priceGross: "3075",  // gross, in cents
      name: "Small / Black",
      inventory: 42,
    }
  ],
  collections: [...],
  categories: [...],
}

The typed response still declares the merchant-private variant keys — cost, digital, externalId, supplierAliases, reservedQuantity, unavailableQuantity — but read methods always answer with them blanked, so a storefront cannot leak them into its page source. See Merchant-private fields.

Suggested Products

What to show in a product page's "You might also like" section, in display order: the merchant's suggested products first, then products from the same category, never anything a shopper can't buy right now. Available from commerce-kit 0.74.0.

const { data: related } = await commerce.productRelated({
  idOrSlug: "classic-tee",
  limit: 6, // 1–12, default 6
});

Each entry has the same shape as an entry of productBrowse, so the same product card renders both. With no suggestions set, the list still fills from the product's category. See Suggested products for the rules.

Displaying Prices

Prices are stored net. Every variant also carries a gross twin — priceGross, plus originalPriceGross, calculatedPriceGross, and prePromotionPriceGross — so the storefront never computes tax itself. Which one to render is decided by the store's tax behavior:

const { store } = await commerce.meGet();
const shown = store.taxBehavior === "inclusive" ? variant.priceGross : variant.price;

inclusive means shoppers see gross prices with tax included; exclusive means they see net prices and tax is added at checkout. With no tax rate assigned, gross equals net. See Prices and tax for the full field list.

Create a Product

const product = await commerce.productCreate({
  name: "New Product",
  slug: "new-product",
  summary: "A great new product",
  description: "Detailed description in markdown",
});

Update a Product

const updated = await commerce.productUpdate(
  { idOrSlug: "new-product" },
  { name: "Updated Product Name" },
);

Delete a Product

await commerce.productDelete({ idOrSlug: "new-product" });

Working with Variants

Products have variants for different options (size, color, etc.). Manage variants with dedicated methods:

// Create a variant
await commerce.variantCreate(
  { idOrSlug: "classic-tee" },
  { sku: "CT-LG-RED", price: "2500", name: "Large / Red" },
);

// Update a variant
await commerce.variantUpdate(
  { idOrSku: "CT-LG-RED" },
  { price: "2900" },
);

// Delete a variant
await commerce.variantDelete({ idOrSku: "CT-LG-RED" });