Saiba o que é a Storefront API da Nuvemshop, quais endpoints ela inclui, o que uma loja virtual perde ao optar por headless e quando vale a pena ter um frontend próprio.
Última atualização: 27/10/2026
A Storefront API é uma API REST pública para criar lojas headless na Nuvemshop. Com ela, você desenvolve um frontend próprio, web ou mobile. Esse frontend consulta por API os produtos e as categorias da loja, em vez de usar um layout da Nuvemshop.
É uma opção para lojas com equipe de desenvolvimento ou agência que precisam de uma experiência que um layout não oferece. Para a maioria, o Novo Editor do layout Ipanema resolve a necessidade com menos desenvolvimento e manutenção.
A Storefront API não vem ativa por padrão. Cada loja precisa de uma liberação manual antes de poder usá-la.
Headless significa que a loja virtual é construída fora da Nuvemshop e apenas consulta dados por API. Hoje, a única ferramenta da Nuvemshop que funciona assim é a Storefront API. As outras três ferramentas que costumam ser confundidas com headless trabalham sobre a loja virtual da Nuvemshop.
| Ferramenta | O que é | É headless? |
|---|---|---|
| Novo Editor | Editor visual do layout Ipanema, que monta a loja com seções e blocos sem código. | Não |
| Nuvemshop CLI e fork do layout | Ferramenta para desenvolvedores e agências editarem o código de um layout. | Não |
| NuvemSDK | Toolkit que executa o código dos aplicativos dentro da loja virtual existente. | Não |
| Storefront API | API que alimenta uma loja virtual separada, construída fora da Nuvemshop. | Sim |
Para conhecer as seções e os blocos do Novo Editor, conferir: Quais seções posso adicionar nas páginas da minha loja com o layout Ipanema na Nuvemshop?
A Storefront API cobre a jornada de descoberta de uma loja e entrega a compra no checkout da Nuvemshop. Não exige criar um aplicativo nem usar OAuth.
| Capacidade | Endpoint | Detalhes |
|---|---|---|
| Listar produtos publicados | GET /products | Retorna até 200 por página. O parâmetro fields seleciona os campos. |
| Buscar produtos | GET /search/products | Retorna apenas a primeira página de resultados. |
| Visualizar um produto | GET /products/{id_or_handle} | Inclui variações e imagens, se solicitadas. |
| Listar categorias | GET /categories | Retorna apenas as categorias visíveis. |
| Visualizar uma categoria | GET /categories/{id_or_handle} | Consulta realizada por ID ou handle. |
| Calcular o frete | POST /shipping-options | Calcula por variação, quantidade e CEP. |
| Iniciar o checkout | POST /checkouts | Retorna uma checkout_url e aceita cupom. |
Os campos personalizados são solicitados com fields=custom_fields. Apenas os criados pela loja são retornados, nunca os de aplicativos.
Sem token a partir do navegador, o limite é de 120 requisições por minuto por loja e IP. Com token a partir de um servidor, o limite é de 1.200 requisições por minuto por loja. Se o servidor enviar o cabeçalho X-LinkedStore-Buyer-IP, o limite passa a ser de 120 por minuto para cada IP de quem compra.
Para conferir a documentação técnica completa, acessar: Documentação oficial da Storefront API
Ao optar por headless, sua equipe ou agência assume tudo o que a Nuvemshop resolve na loja virtual. A loja continua usando o painel administrador (catálogo, estoque, preços e cupons), Nuvem Pago, Nuvem Envio e o checkout da Nuvemshop.
| O que você perde | O que isso significa |
|---|---|
| Novo Editor | Não há edição visual nem pré-visualização em tempo real. Cada alteração de layout exige desenvolvimento. |
| Layouts e atualizações | As melhorias e correções do layout Ipanema não chegam sozinhas. |
| Aplicativos da loja | Os aplicativos que adicionam elementos na loja virtual podem não funcionar da mesma forma. É necessário validar caso a caso. |
| Carrinho | A API não inclui um endpoint de carrinho, portanto o frontend precisa construir o seu próprio. |
| Conta de quem compra, páginas e blog | A API não cobre esses recursos. Eles devem ser construídos no frontend ou com outra ferramenta. |
| Hospedagem, domínio e SSL | Passam a ser de responsabilidade da loja ou de seu provedor. |
| SEO | A Nuvemshop deixa de gerenciar o sitemap, as meta tags e as URLs. |
| Métricas da loja | As estatísticas de visitas e da jornada de compra podem ficar incompletas. É necessário validar caso a caso. |
| Suporte sobre o frontend | O suporte da Nuvemshop cobre o painel administrador e o checkout. O frontend fica sob responsabilidade da equipe ou da agência. |
De modo geral, um projeto headless custa mais do que um layout padrão. Sua equipe ou agência assume a hospedagem, o desenvolvimento e a manutenção. Não há um valor fixo, pois depende do escopo.
A Storefront API vale a pena quando a experiência de compra é o diferencial da marca. Também é necessária uma equipe técnica para manter o frontend próprio.
| Situação | Compatibilidade e alternativa |
|---|---|
| Loja enterprise com equipe própria de desenvolvimento | Alta. Permite controlar a experiência, a performance e a stack. |
| Agência que desenvolve lojas sob medida | Alta. A loja precisa estar ciente do que perde e da dependência da agência. |
| Marca em migração de outras plataformas, como VTEX ou Shopify Hydrogen | Alta. Pode manter seu frontend e migrar apenas o backend de comércio, reduzindo o custo de migração. |
| Loja com aplicativo mobile nativo | Alta. O pagamento é concluído em um navegador, pois não há checkout dentro do aplicativo. |
| Site de conteúdo, landing page ou microsite com produtos | Média. Utiliza o catálogo e o checkout em um site fora da loja virtual. |
| Loja que busca um layout personalizado para gerenciar sem agência | Baixa. O recomendado é criar um fork do layout usando a Nuvemshop CLI. |
| Loja sem equipe técnica | Baixa. O recomendado é usar o layout Ipanema com o Novo Editor. |
| Desenvolvimento de aplicativos para o ecossistema | Baixa. O recomendado é usar o NuvemSDK ou a API Admin. |
Também não é indicado se o lançamento rápido for prioridade. Um layout padrão pode estar online em poucos dias, enquanto um projeto headless costuma levar semanas ou meses, dependendo do escopo. Caso falte apenas uma funcionalidade, é preferível estender o layout com código, NuvemSDK ou App Proxy antes de reescrever o frontend.
A liberação é realizada de forma manual, loja por loja. Para solicitar, entre em contato com nossa equipe de atendimento com os seguintes dados:
Com essas informações, encaminhamos a solicitação para a equipe responsável, que entrará em contato para dar andamento. Se você consumir a API a partir de um servidor, o token também é gerenciado manualmente.
Para personalizar sua loja sem desenvolver um frontend, você pode personalizá-la com o layout Ipanema.