Shopify Storefront API: La guía completa para desarrolladores y comerciantes

La Storefront API de Shopify es una API GraphQL de acceso público que te permite construir experiencias de compra completamente personalizadas, desde tiendas headless y aplicaciones móviles hasta integraciones de IoT y agentes de IA, mientras Shopify maneja el backend de comercio. A diferencia de la Admin API, está diseñada para ser llamada de forma segura desde navegadores y clientes móviles. Si la estás evaluando para un proyecto ahora mismo, la versión estable actual es 2026-04 y ya hay disponible un candidato de lanzamiento 2026-07 para pruebas.

Puntos clave

• La Storefront API es de acceso público y segura para llamar desde el cliente; la Admin API debe permanecer en un servidor seguro.
• Las mutaciones de carrito (cartCreate, cartLinesAdd, cartBuyerIdentityUpdate) son las operaciones de escritura centrales que todo proyecto necesita.
• Las versiones de API siguen un cadencia trimestral: 2026-01, 2026-04, 2026-07, 2026-10. La antigua versión 2024-10 se retira en octubre de 2026.
• Hydrogen 2026.4.0 hizo que el proxy de Storefront API fuera obligatorio y habilitó el modo de consentimiento backend de forma predeterminada, dos cambios disruptivos que requieren una auditoría antes de actualizar.
• A partir de Hydrogen 2026.1.4, cada tienda Hydrogen en Oxygen expone automáticamente un punto final MCP en /api/mcp, lo que la convierte en un punto final de comercio listo para agentes de IA sin código personalizado.

¿Qué es la Shopify Storefront API?

La Storefront API es la API GraphQL orientada al cliente de Shopify. Proporciona a los desarrolladores acceso de lectura a productos, colecciones, metaobjetos y menús, más acceso de escritura para las dos cosas que los compradores realmente hacen: gestionar un carrito y autenticarse como cliente.

Así es como la propia documentación de Shopify presenta su modelo de acceso: la Storefront API es principalmente de solo lectura, con la excepción de autenticación y gestión de carrito. Ese límite es intencional. Puedes obtener todos los detalles del producto, construir una interfaz de filtro en vivo y elaborar un flujo de compra completo sin jamás usar una credencial secreta.

El patrón de punto final es directo:

https://{your-store}.myshopify.com/api/2026-04/graphql.json

Cada solicitud necesita un encabezado Shopify-Storefront-Public-Token (o el equivalente de token privado para llamadas Hydrogen del lado del servidor). El token no es secreto y puede incrustarse en código de navegador o móvil. Tu clave de Admin API y contraseña, por otro lado, nunca deben aparecer en código del lado del cliente.

Storefront API vs. Admin API: la diferencia real

Esta es la pregunta que todos los comerciantes y desarrolladores hacen primero, y la respuesta es arquitectónica, no solo una lista de características.

La Admin API te proporciona acceso completo de lectura y escritura a los datos de tu tienda Shopify: pedidos, clientes, productos, inventario, cumplimiento, análisis y más. La Storefront API deliberadamente carece de esas funciones administrativas. No puedes modificar pedidos, gestionar inventario ni acceder a análisis internos a través de ella. Eso no es una limitación para eludir; es el límite de seguridad que te permite incrustar de forma segura el token en un componente React.

Un error común: usar credenciales de Admin API en código del lado del cliente. Eso expone las credenciales de tu tienda al público. Siempre mantén las llamadas de Admin API en un servidor seguro de backend. Si necesitas acceso del lado del cliente a datos de la tienda, eso es exactamente para lo que existe la Storefront API.

Capacidades principales: qué puedes realmente construir

Consultas de productos y colecciones

Obtén títulos de productos, descripciones, precios de variantes, estado de inventario, imágenes y metafields. Porque GraphQL te permite solicitar solo los campos que necesitas, una consulta de tarjeta de producto puede devolver una respuesta simplificada de 3 campos en lugar de un payload REST inflado. La velocidad y eficiencia de obtener solo los datos que solicitas la hace ideal para aplicaciones sensibles al rendimiento.

Un cambio reciente importante: las variantes de producto GraphQL ahora soportan hasta 2.000 por producto, expandidas del límite anterior de 100 variantes. Si vendes productos configurables (tamaño x color x material), esto importa.

Mutaciones de carrito

El objeto Cart es el corazón de cada construcción de Storefront API. La superficie de mutación actual incluye:

• cartCreate, crear un nuevo carrito y opcionalmente agregar un artículo de línea en una llamada
• cartLinesAdd, agregar una o más variantes de producto a un carrito existente
• cartLinesUpdate, actualizar cantidad en líneas existentes (acepta hasta 250 valores por llamada)
• cartLinesRemove, eliminar líneas por ID
• cartDiscountCodesUpdate, aplicar o borrar códigos de descuento (reemplaza todos los códigos existentes con la lista proporcionada)
• cartGiftCardCodesAdd / cartGiftCardCodesRemove, gestionar el canje de tarjetas de regalo
• cartBuyerIdentityUpdate, asociar un cliente conectado, establecer una ubicación de empresa B2B o configurar preferencias de compra como método de entrega
• cartMetafieldsSet, escribir metafields arbitrarios en el carrito para lógica de compra personalizada

Un agregado reciente que vale la pena conocer: el tipo CartLine ahora devuelve un campo viewKey, para que puedas correlacionar líneas devueltas con el view_key enviado a cartLinesUpdate y cartLinesRemove. Útil cuando construyes actualizaciones de interfaz de usuario optimistas.

Consentimiento compatible con privacidad

Desde la versión 2025-10 de Storefront API en adelante, la directiva @inContext acepta un argumento visitorConsent. Esto te permite codificar el estado de consentimiento directamente en la llamada de creación de carrito e incluirlo automáticamente en el checkoutUrl resultante. El resultado: flujos de cumplimiento de GDPR y CCPA sin una capa separada de escritura de cookies.

Metaobjetos y acceso protegido por token

Algunas características requieren autenticación basada en token más allá del token de acceso público. Las etiquetas de producto, metaobjetos, metafields, menús de navegación de tienda y datos de clientes se encuentran detrás de acceso limitado por token. Solicitar estos permisos se realiza cuando creas la aplicación Storefront API en el administrador de Shopify.

Versionado de API: qué comerciantes y desarrolladores necesitan rastrear

La Storefront API de Shopify sigue una cadencia de lanzamiento trimestral: las versiones se nombran 2026-01, 2026-04, 2026-07 y 2026-10. Cada versión es soportada por 12 meses después del lanzamiento. Las llamadas a versiones de API no soportadas resultarán en que las aplicaciones sean deslistadas o bloqueadas de instalación.

Ahora mismo las fechas clave son:

• 2026-04 es la versión estable actual (más reciente).
• 2026-07 es el candidato de lanzamiento, vinculado a la Edición de Verano 2026 de Shopify (nombre en clave Compass), que incluye 65 actualizaciones de producto incluyendo cambios disruptivos en estructuras de consulta de carrito y producto.
• 2024-10 se retira en octubre de 2026. Si tu construcción headless aún está en esa versión, tienes un tiempo limitado para migrar.

Los cambios disruptivos de 2026-07 afectan cada construcción headless, Hydrogen, Next.js Commerce, Nuxt o completamente personalizada. Shopify proporciona codemods para proyectos Hydrogen para automatizar las migraciones de consulta.

Para comerciantes evaluando si actuar ahora: si ejecutas una construcción headless personalizada en cualquier versión anterior a 2025-04, programa una auditoría de versión con tu desarrollador este trimestre. Consulta nuestra página de servicios de desarrollador Shopify para lo que típicamente implica una auditoría de versión.

La conexión Hydrogen: el proxy de Storefront API ahora es obligatorio

Hydrogen es el framework basado en React de Shopify construido directamente sobre la Storefront API, y en 2026 la relación entre los dos se hizo significativamente más estrecha.

Hydrogen 2026.4.0 (lanzado el 17 de abril de 2026) introdujo dos cambios disruptivos:

1. El proxy de Storefront API ahora siempre está habilitado. La opción de configuración proxyStandardRoutes fue eliminada. Si un manejador de solicitud se ejecuta sin una instancia de escaparate en su contexto de carga, lanza un error en tiempo de ejecución. Cualquier configuración personalizada de Hydrogen que eludiera el proxy necesita ser actualizada.
2. El modo de consentimiento backend ahora es el predeterminado. Hydrogen ya no depende de la cookie _tracking_consent del lado del cliente. El consentimiento ahora se gestiona a través de cookies configuradas por servidor escritas vía el proxy de Storefront API. Los banners de consentimiento personalizados que leen document.cookie para _tracking_consent verán un valor vacío después de actualizar.

La razón por la que estos dos cambios están acoplados: todo el punto del modo de consentimiento backend es que las escrituras de consentimiento no pueden fallar silenciosamente cuando falta un proxy. El proxy volverse obligatorio fue el requisito previo.

Si ejecutas una configuración personalizada de Hydrogen (cualquier proyecto que no sea un esqueleto limpio de create-hydrogen), audita tus llamadas createRequestHandler y lógica de banner de consentimiento antes de actualizar a 2026.4.x.

El cambio más grande en 2026: tu tienda ahora es un punto final de agente de IA

Este es el desarrollo que cambia el rol de la Storefront API de manera más fundamental.

Hydrogen 2026.1.4 agregó soporte integrado de proxy MCP (Model Context Protocol) de Storefront. Cada tienda Hydrogen en Oxygen ahora expone un punto final MCP en /api/mcp sin configuración personalizada. Lo que eso significa en la práctica: asistentes de IA como ChatGPT, Perplexity y agentes de compra personalizados pueden descubrir tus productos, gestionar carritos y guiar a los compradores a través del checkout usando lenguaje natural, todo impulsado por datos en tiempo real de la Storefront API.

Shopify expone tres superficies MCP distintas:

• Catalog MCP, descubrimiento de productos global entre comerciantes Shopify
• Storefront MCP, búsqueda específica del comerciante, políticas y preguntas frecuentes
• Checkout MCP, creación de carrito programática, actualizaciones y finalización de compra

El descubrimiento de productos públicos a través de Storefront MCP no requiere autenticación adicional. Las operaciones de carrito autenticadas usan el encabezado Shopify-Storefront-Private-Token existente que tu aplicación Hydrogen ya envía.

Para verificar que el proxy está activo en tu tienda: accede a /api/mcp en tu despliegue de Oxygen. Si reenvía al servidor Storefront MCP de Shopify, estás activo.

Para comerciantes que aún no están en Hydrogen, esta es una razón concreta para evaluar la migración. Los temas Liquid en la CDN de Shopify ofrecen rendimiento consistente pero fijo. Hydrogen en Oxygen ofrece esa línea de base de rendimiento más integración de agentes de IA sin degradación. El cálculo de ROI para características de comercio de IA está cambiando a favor de Hydrogen. Puedes explorar lo que implica una migración Hydrogen en nuestra página de desarrollador headless Shopify.

Lista práctica de verificación para comerciantes y desarrolladores

Si ejecutas una tienda Hydrogen:

• Confirma que estás en Storefront API 2026-04 (la actual más reciente)
• Audita createRequestHandler para la opción ahora eliminada proxyStandardRoutes
• Verifica que tu banner de consentimiento lea cookies configuradas por servidor, no _tracking_consent
• Prueba /api/mcp en tu despliegue de Oxygen para confirmar que MCP está activo
• Comienza a probar contra el candidato de lanzamiento 2026-07 ahora; no esperes hasta octubre

Si ejecutas una construcción headless personalizada (Next.js, Nuxt, etc.):

• Identifica tu versión de API actual y mapeala contra la retirada de octubre de 2026 de 2024-10
• Revisa el registro de cambios de 2026-07 para cambios disruptivos en estructuras de consulta de carrito y producto
• Planifica codemods o actualizaciones de consulta manual antes del próximo ciclo de Shopify Editions

Si ejecutas un tema Liquid estándar:

• La Storefront API sigue siendo relevante si usas cualquier aplicación de terceros que la llame del lado del cliente
• Verifica que esas aplicaciones estén dirigidas a 2026-04 o más reciente
• Considera si las capacidades de agentes de IA en Hydrogen justifican una evaluación de migración

La Storefront API ya no es solo la API "Shopify headless". Es la capa de datos que conecta tu catálogo a cada superficie que un comprador podría usar, navegador, móvil, voz, y ahora agentes de IA. Mantener tu versión actual y tu configuración Hydrogen alineada con los requisitos de proxy y consentimiento de Shopify es el trabajo de mantenimiento que mantiene esas superficies abiertas.