Qué es la Storefront API
La Storefront API es la API pública de Shopify pensada para construir tiendas headless. Está basada en GraphQL y expone los datos que un comprador puede ver: productos, colecciones, variantes, precios, inventario, carrito, checkout, blog, páginas, menú y cliente autenticado.
Funciona con un token público (Storefront Access Token), pensado para que un frontend la consuma directamente desde el navegador o desde un framework server-side, sin necesidad de un backend intermedio.
Diferencia con la Admin API
Shopify ofrece dos APIs principales con propósitos distintos:
| Aspecto | Storefront API | Admin API |
|---|---|---|
| Quién la usa | Compradores (frontend) | Administradores y apps |
| Protocolo | GraphQL (REST en partes legacy) | GraphQL + REST |
| Token | Storefront Access Token (público) | Admin Access Token (privado) |
| Datos | Solo lo que el cliente puede ver | Todo: pedidos, clientes, inventario, finanzas |
| Mutaciones | Carrito, checkout, login cliente | Crear/editar productos, gestionar pedidos |
| Rate limits | Generosos, por IP/buyer | Estrictos por app |
La Storefront API es la elegida para headless commerce porque está pensada para vivir en el frontend, mientras que la Admin API queda para integraciones internas, ERPs y dashboards.
Casos de uso típicos
- Tienda headless en Astro, Next.js, Nuxt, SvelteKit o Vue: catálogo y carrito gestionados desde Shopify, frontend totalmente custom.
- PWA o app móvil que reutiliza el backend de la tienda Shopify.
- Quioscos físicos o terminales con interfaz propia conectados al mismo catálogo.
- Microsites de campaña que comparten checkout con la tienda principal.
- Multi-tienda con diseño compartido: varios frontends consumiendo distintos canales de venta de Shopify.
Ejemplo de consulta
Pedir los primeros 5 productos de una colección:
query GetCollectionProducts($handle: String!) {
collection(handle: $handle) {
title
products(first: 5) {
edges {
node {
id
title
handle
priceRange {
minVariantPrice { amount currencyCode }
}
images(first: 1) {
edges { node { url altText } }
}
}
}
}
}
}Se envía por HTTP POST al endpoint https://tu-tienda.myshopify.com/api/2024-07/graphql.json con el header X-Shopify-Storefront-Access-Token.
Lo que sí expone
- Catálogo: productos, variantes, opciones, imágenes, vídeos, metafields públicos.
- Colecciones manuales y automáticas.
- Inventario disponible por variante (cantidad, disponibilidad).
- Precios con impuestos según mercado.
- Blog, páginas estáticas, menú de navegación.
- Carrito (Cart API): crear, modificar, aplicar descuentos.
- Checkout vía el Cart API (que genera la URL de checkout alojada en Shopify).
- Cliente: login, registro, historial de pedidos.
Lo que no expone (limitaciones)
- Datos sensibles: márgenes, costes, datos internos de pedidos ajenos.
- Apps de terceros en general no exponen UI por aquí.
- Reglas de descuento avanzadas completas; algunas solo se aplican vía checkout.
- Pagos personalizados: el checkout sigue corriendo en Shopify por motivos de PCI.
- Algunos campos administrativos: tags privados, notas internas, etc.
Rate limits
La Storefront API tiene límites generosos pero medibles:
- Sin autenticar (público): aproximadamente 1.000 puntos de cost por minuto por IP.
- Con buyer identity: límites compartidos con el comprador.
- Las queries GraphQL cuestan según complejidad (cada campo suma). Las consultas grandes hay que paginar.
Si rebasas el límite, recibes un error THROTTLED. Buena práctica: cache en frontend, ISR en Next, prerender en Astro, y un proxy Worker que cachee respuestas frecuentes.
Versionado
Shopify versiona la API por cuatrimestres: 2024-07, 2024-10, 2025-01. Cada versión se mantiene 12 meses. Conviene fijar versión en el endpoint y revisar el changelog antes de actualizar.
En IMPERO
Cuando un cliente Shopify necesita más libertad de diseño y rendimiento que el que permite Liquid, montamos la tienda con Storefront API + Astro. El servicio dedicado es Shopify a Astro headless: mantiene Shopify como backend (pagos, pedidos, fiscalidad) y construye un frontend Astro que carga rápido y se posiciona mejor.