> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs-loja.usecorvex.com.br/data/resources/product-variant.md).

***

## 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

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { getProductImage, getProductPrice } from '@corvex/theme-sdk';
```

***

## Exemplo mínimo — card

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs-loja.usecorvex.com.br/reference/contracts/data.md)
* [Cart Contract](https://docs-loja.usecorvex.com.br/reference/contracts/cart.md)
* [Product resource](https://docs-loja.usecorvex.com.br/data/resources/product.md)
* [Product Card Cookbook](https://docs-loja.usecorvex.com.br/cookbook/product-card.md) — UI `ProductSummary`
* [Variant Selector Cookbook](https://docs-loja.usecorvex.com.br/cookbook/variant-selector.md) — `options` / `variants` / `addItem`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.