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.

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.

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:

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)

export const data = defineSectionData(async ({ storefront, settings }) => ({
  products: await storefront.products.list({
    first: settings.limit,
    collection: settings.collection,
  }),
}));

Grid leve

await storefront.products.list({ first: 24, fields: 'basic', sortBy: 'PRICE' });

Começar

Conceitos-chave

APIs e referências

Guias

Otimizar

Ferramentas

Marketplace

Storefront Components

products.list

storefront.products.list(options)

Parâmetros SDK

ProductSort → backend

⚠️ Status e categoria

Filtros no schema da section

Retorno SDK

useCorvexData

Exemplos

Por categoria (editor)

Grid leve

Referências

​storefront.products.list(options)

​Parâmetros SDK

​ProductSort → backend

​⚠️ Status e categoria

​Filtros no schema da section

​Retorno SDK

​useCorvexData

​Exemplos

​Por categoria (editor)

​Grid leve

​Referências

storefront.products.list(options)

Parâmetros SDK

ProductSort → backend

⚠️ Status e categoria

Filtros no schema da section

Retorno SDK

useCorvexData

Exemplos

Por categoria (editor)

Grid leve

Referências