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

# products.list

> Listar produtos da vitrine com filtros, ordenação e paginação.

# storefront.products.list(options)

Lista produtos da vitrine via SDK.

A listagem devolve o **payload completo** (`variants`, `physical`, `metafields`, …). O SDK só normaliza aliases (`slug` → `handle`, `pricing` → `Money`, etc.).

## Parâmetros SDK

| Campo | Tipo | Nota | Descrição |
| - | - | - | - |
| `first` | `number` | `limit` | Quantidade. O SDK usa 20 se `first` e `limit` faltarem. Não aplica teto no cliente |
| `after` | `string` | `page` | Cursor → página calculada |
| `collection` / `category` | `ResourceRef` | `categoryId` | Uma categoria |
| `categories` | `ResourceRef[]` | `categories` | Várias categorias (OR, CSV) |
| `featured` | `boolean` | `featured` | Só destaques |
| `inStock` | `boolean` | `inStock` | Só `stock > 0` |
| `query` / `search` | `string` | `search` | Busca no nome |
| `sortBy` | `ProductSort` | `sortBy` | Ordenação (mapeada) |
| `sortOrder` | `asc` \| `desc` | `sortOrder` | Ordem explícita |
| `reverse` | `boolean` | `sortOrder` | Inverte (se `sortOrder` omitido) |
| `minPrice` / `maxPrice` | `number` | idem | Faixa de preço |
| `fields` | `basic` \| `full` | `fields` | `basic` = grid leve |
| `type` | string | `type` | `PHYSICAL`, `DIGITAL`, `MEMBERSHIP` |
| `types` | string | `types` | CSV de tipos |
| `status` | `ACTIVE` \| `PUBLISHED` | `status` | **Opcional** — ver aviso abaixo |

### ProductSort → backend

| SDK | Backend `sortBy` |
| - | - |
| `BEST_SELLING`, `RELEVANCE`, `CREATED_AT` | `createdAt` |
| `UPDATED_AT` | `updatedAt` |
| `PRICE` | `price` |
| `TITLE` | `name` |

### ⚠️ Status e categoria

| Cenário | Recomendação |
| - | - |
| Filtrar por categoria | **Não envie** `status`, ou use `status: 'ACTIVE'` |
| Checkbox "só com estoque" | `inStock: true` — **não** `status=PUBLISHED` |
| Listagem geral | Omita `status` (API retorna ACTIVE + PUBLISHED) |

Enviar `status=PUBLISHED` + `categoryId` costuma retornar **0 produtos** quando itens ainda estão `ACTIVE` no banco.

## Filtros no schema da section

| Setting | SDK | Backend |
| - | - | - |
| `{ "type": "collection", "id": "collection" }` | `collection` | `categoryId` |
| `{ "type": "text", "id": "query" }` | `query` | `search` |
| `{ "type": "checkbox", "id": "featured" }` | `featured: true` | `featured` |
| `{ "type": "checkbox", "id": "inStock" }` | `inStock: true` | `inStock` |
| `{ "type": "range", "id": "limit" }` | `first` | `limit` |

Exemplo completo: [Section product-list](https://docs-loja.usecorvex.com.br/data/sections/product-list.md).

## Retorno SDK

`Connection<Product>`: `{ nodes, pageInfo }`. Lista vazia da API vira `nodes: []`. Erro de rede sobe do cliente HTTP. `get('')` de um produto é outro método e devolve `null`. Ver [Product](https://docs-loja.usecorvex.com.br/data/resources/product.md).

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const { nodes, pageInfo } = await storefront.products.list({
  first: 8,
  collection: 'uuid-categoria',
  inStock: true,
  fields: 'full',
});
```

## useCorvexData

O hook ainda exporta dois modos. O comentário no código chama o primeiro de legado:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
useCorvexData('products', {
  limit: 8,
  collectionId: 'uuid-categoria',
  query: 'camisa',
  featured: true,
  inStock: true,
  sortBy: 'BEST_SELLING',
});
```

Aliases aceitos: `collectionId`, `categoryId`, `limit`, `name`.

## Exemplos

### Por categoria (editor)

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
export const data = defineSectionData(async ({ storefront, settings }) => ({
  products: await storefront.products.list({
    first: settings.limit,
    collection: settings.collection,
  }),
}));
```

### Grid leve

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
await storefront.products.list({ first: 24, fields: 'basic', sortBy: 'PRICE' });
```

## Referências

* [Public Products API (backend)](https://docs-loja.usecorvex.com.br/data/queries/public-products-api.md)
* [Product resource](https://docs-loja.usecorvex.com.br/data/resources/product.md)
* [Coleção](https://docs-loja.usecorvex.com.br/data/resources/category.md)


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