Product Contract

Contrato canônico do objeto Product na Corvex.

Esta página é o contrato canônico para o objeto Product na Corvex.

Fonte normativa: Product, ProductSummary, ProductVariant, ProductOption em @corvex/theme-sdk types (ApiVersion 2026-08).

Campos não listados aqui MUST NOT ser tratados como API estável para terceiros.

---

Disponibilidade

Contexto	Acesso
Página product	usePage('product').product
schema.data: ["product"]	prop data.product
Listagem	storefront.products.list() → Connection<Product>
Detalhe	storefront.products.get(id) / getByHandle(handle)
Settings	type: "product" / product_list → UUID em settings

---

ProductSummary

Campos comuns em cards e listas (Product extends Summary):

Campo	Tipo	Nullable	Descrição
id	string	não	Identificador único
handle	string	não	Slug URL
url	string	não	Caminho relativo (ex.: /products/camiseta)
title	string	não	Nome do produto
name	string	sim	Deprecated — usar title
featuredImage	Image	sim	Imagem principal
price	Money	não	Preço de venda
compareAtPrice	Money	sim	Preço comparativo / riscado
availableForSale	boolean	não	Alguma variante comprável
featured	boolean	não	O mapper sempre envia boolean

---

Product (extends ProductSummary)

Campo	Tipo	Nullable	Descrição
description	string	sim	Descrição texto
descriptionHtml	string	sim	Descrição HTML
vendor	string	sim	Fabricante / marca
images	Image[]	não	Galeria
variants	ProductVariant[]	não	Variantes
options	ProductOption[]	não	Opções (Cor, Tamanho, …)
categories	Category[]	não	Categorias vinculadas
tags	string[]	não	Tags
seo	Seo	não	title, description
createdAt	string	não	ISO 8601
updatedAt	string	não	ISO 8601

mapProductSummary também devolve stock, shortDescription e reviewSummary. mapProduct (usado por get e por list) também repassa status, sku, variantCount, physical, logistics e metafields quando a API envia. A interface Product em types/index.d.ts não lista esses campos. Não invente chave que a resposta não trouxe.

---

ProductOption

Campo	Tipo
name	string
values	string[]

---

ProductVariant

Ver Product Variant.

---

Image (aninhado)

Campo	Tipo	Nullable
id	string	não
url	string	não
altText	string	sim
width	number	sim
height	number	sim

---

Money (aninhado)

Campo	Tipo
amount	string
currencyCode	string
formatted	string

Usar price.formatted para exibição. Helpers: formatPrice() no SDK.

---

Helpers públicos

import { getProductImage, getProductPrice } from '@corvex/theme-sdk';

---

Exemplo mínimo — card

function ProductCard({ product }) {
  const img = product.featuredImage;
  return (
    <a href={product.url}>
      {img && <img src={img.url} alt={img.altText || product.title} />}
      <span>{product.title}</span>
      <span>{product.price.formatted}</span>
    </a>
  );
}

---

Restrições

• Use title em tema novo. name existe e o mapper copia title.
• Confira availableForSale antes do botão de compra.

---

Veja também

• Data Contract
• Cart Contract
• Product resource
• Product Card Cookbook — UI ProductSummary
• Variant Selector Cookbook — options / variants / addItem