Shopify Storefront API: Qué cambió y qué debes hacer ahora

La Shopify Storefront API es una API GraphQL pública que permite a los desarrolladores crear experiencias de compra completamente personalizadas en cualquier plataforma, desde tiendas headless hasta aplicaciones móviles y agentes de IA. En 2026 ha avanzado más que en cualquier otro año anterior: la versión 2026-04 es la versión estable actual, 2026-07 se lanza como candidato de lanzamiento hoy (30 de junio de 2026) con cambios de ruptura, y la versión 2024-10 se retira en octubre, dando a los equipos cinco meses para migrar. Si tu tienda headless no está en una versión compatible ahora mismo, el reloj ya está en marcha.

Puntos clave

• 2026-04 es la versión actual estable de Storefront API; 2026-07 es el candidato de lanzamiento activo con cambios de ruptura en consultas de carrito y productos.
• La versión heredada 2024-10 se retira en octubre de 2026, los compilados personalizados enfrentan costos de remediación de 8.000, 40.000 dólares si se dejan demasiado tarde.
• La versión 2025-10 introdujo el parámetro visitorConsent en la directiva @inContext, codificando el consentimiento GDPR/privacidad directamente en la URL de pago.
• A partir de 2026-07, el carrito emite advertencias PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION y DELIVERY_SELECTED_OPTION_NOT_AVAILABLE para que tu interfaz pueda mostrarlas a los compradores.
• Las herramientas de Storefront MCP get_cart/update_cart están obsoletas a favor de UCP Cart MCP, con mantenimiento de las herramientas antiguas solo hasta 31 de agosto de 2026.

El modelo de versionado: cómo funciona el ciclo de lanzamiento trimestral de Shopify

Shopify lanza una nueva versión de Storefront API cada tres meses, en enero, abril, julio y octubre. Cada versión estable está garantizada de no cambiar durante su tiempo de vida compatible, y cada versión estable cuenta con soporte mínimo de 12 meses, lo que significa que hay al menos nueve meses de superposición entre dos lanzamientos consecutivos. Esa superposición es tu ventana de migración.

Hay tres tipos de pista a entender:

• Estable (por ejemplo, 2026-04), segura para producción, compatibilidad hacia atrás garantizada.
• Candidato de lanzamiento (por ejemplo, 2026-07), publicada el mismo día que el nuevo lanzamiento estable, disponible ahora para pruebas pero no recomendada para producción.
• Inestable, actualizada continuamente, las características pueden desaparecer sin aviso; solo para desarrollo y pruebas.

Una trampa que vale la pena conocer: si tu integración apunta a una versión inaccesible (retirada), Shopify avanza silenciosamente y sirve la versión estable más antigua accesible. El encabezado de respuesta X-Shopify-API-Version será diferente de lo que solicitaste, esa es tu señal de que te has desviado de una versión compatible y estás en riesgo de cambios de ruptura silenciosos.

Para aplicaciones publicadas en la App Store de Shopify, las apuestas son más altas. Las aplicaciones que continúan usando recursos no compatibles después de la fecha límite de actualización se eliminan de la App Store, bloqueando a los usuarios de instalarlas durante un mínimo de siete días.

Comparación de versiones de API: pistas estable, candidato de lanzamiento e inestable

Qué cambió realmente en 2026-04 (la versión estable actual)

Esqueleto de Hydrogen actualizado a 2026-04. Si fijaste tu configuración de Hydrogen a 2026-01, necesitas actualizar. El paquete de esqueleto (skeleton@2026.4.0) ahora apunta a 2026-04 en todas las llamadas de Storefront API y Customer Account API.

Acceso a metaobjetos en Shopify Functions. 2026-04 permite que Shopify Functions consulte datos de metaobjetos directamente. Si tienes lógica de descuentos o entrega basada en Functions que podría beneficiarse de leer definiciones de metaobjetos en tiempo de ejecución, ahora está disponible.

Límite de metafield JSON a 128KB. A partir de la versión de API 2026-04, Shopify limita los valores de metafield JSON a 128KB. Si tu tienda headless lee metafields JSON grandes, audita tus datos ahora antes de que cualquier actualización de versión rompa cargas silenciosamente.

Los cambios de ruptura de 2026-07: qué necesitan parchar los compilados headless

La Edición de Verano de Shopify 2026 (nombre en clave Compass) lanzó 65 actualizaciones de productos. La Storefront API 2026-07 introduce cambios de ruptura en estructuras de consultas de carrito y productos que afectan a todos los compilados headless, Hydrogen, Next.js Commerce, Nuxt, o completamente personalizados.

Aquí está lo que requiere atención antes de octubre:

Señales de advertencia del carrito. A partir de 2026-07, el objeto Carrito emite dos nuevos tipos de advertencia:

• PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION, se activa cuando una línea del carrito contiene un producto no disponible en la ubicación del comprador. Cada línea de carrito afectada devuelve su propia advertencia, con el target establecido en el ID de línea del carrito para que puedas mapearlo nuevamente a la línea correcta en tu interfaz.
• DELIVERY_SELECTED_OPTION_NOT_AVAILABLE, se activa cuando la opción de entrega elegida por un comprador se vuelve no disponible (por ejemplo, después de un cambio de dirección del carrito). Anteriormente, el sistema cambiaba opciones de entrega silenciosamente sin notificación al comprador. Ahora puedes detectar esto programáticamente y pedir al comprador que elija de nuevo.

Eliminación de enumeración de metaobjetos. Las enumeraciones de control de acceso obsoletas PRIVATE y PUBLIC_READ en definiciones de metaobjetos se eliminan en 2026-07. Si tu aplicación o tienda headless hace referencia a estos valores de enumeración, actualiza al modelo de control de acceso actual antes de que el lanzamiento se estabilice.

Reestructuración de campos de descuento. 2026-07 reestructura campos relacionados con descuentos en el Carrito. Si tu tienda headless tiene cualquier visualización de descuento personalizada o lógica de cupones, comienza a refactorizar contra el candidato de lanzamiento ahora. Los usuarios de Hydrogen obtienen codemods para la mayoría de cambios de nombre de campos estructurales; los marcos personalizados están por su cuenta, y las estimaciones de remediación se sitúan entre 8.000 y 40.000 dólares dependiendo de la complejidad de la tienda.

La fecha límite de octubre de 2026 es firme. La versión de API 2024-10 se retira en octubre de 2026. Cinco meses suena cómodo, no lo es, una vez que factorizas despliegues de ensayo, pruebas de regresión, y el hecho de que la lógica del carrito suele ser la parte más frágil de cualquier pila headless. Comienza a probar contra el candidato de lanzamiento 2026-07 ahora.

Pagos que cumplen con privacidad con @inContext visitorConsent

Este llegó en 2025-10 y sigue siendo una de las adiciones más prácticamente útiles a la Storefront API en memoria reciente. La directiva @inContext ahora acepta un parámetro visitorConsent, permitiendo a los desarrolladores pasar preferencias de consentimiento del comprador, análisis, preferencias, marketing, y venta de datos, a operaciones de carrito.

La mecánica es limpia: codificas el consentimiento en la mutación cartCreate o cartBuyerIdentityUpdate así:

@inContext(visitorConsent: {
  analytics: true,
  preferences: true,
  marketing: false,
  saleOfData: false
})

La información de consentimiento se codifica automáticamente e incluye en la checkoutUrl resultante, asegurando cumplimiento de privacidad durante todo el proceso de pago. Shopify lee el parámetro _cs que añade a la URL durante el pago, no lo elimines.

Esto importa para GDPR y regímenes similares. Las tiendas headless que anteriormente no tenían una forma limpia de propagar el consentimiento de un banner de cookies hasta el pago ahora tienen un mecanismo de primera parte integrado en la API en sí. No hay excusa para que un compilado headless moderno no implemente esto.

Límites de velocidad: la nueva realidad de bots y agentes

Shopify ahora aplica límites de velocidad más estrictos a bots y agentes que acceden a la Storefront API y páginas de tienda en línea alojadas por Shopify. Los bots y agentes que no firman sus solicitudes están sujetos a los límites más estrictos; para calificar para límites de velocidad más altos, los operadores deben firmar solicitudes usando Web Bot Auth.

Para comerciantes y desarrolladores legítimos, la implicación práctica es doble:

1. Si operas un rastreador personalizado, agregador de precios, o agente de compra de IA que golpea puntos finales de Storefront API, firma tus solicitudes o espera limitación de velocidad.
2. Si estás construyendo una integración de Storefront MCP (ver la siguiente sección), asegúrate de que tu perfil de agente esté debidamente registrado para que reciba el nivel de acceso apropiado.

Ten en cuenta que la Storefront API no tiene límite de velocidad aplicado al número de solicitudes de compradores legítimos, está diseñada para escalar a través de ventas flash sin que gestiones la concurrencia. Los nuevos límites específicamente orientan el tráfico de bots maliciosos o no identificados.

Comercio con agentes: Storefront API se encuentra con UCP y MCP

Este es el cambio más estructuralmente significativo en el papel de la Storefront API en 2026. La API ya no es solo la columna vertebral para tiendas headless orientadas al ser humano. Ahora es el punto de entrada para agentes de IA.

Shopify codesarrolló el Protocolo de Comercio Universal (UCP) con Google como el estándar abierto para cómo los agentes de IA transan con comerciantes. UCP cubre el viaje de comercio completo desde descubrimiento hasta carritos y pago, y cuenta con amplio apoyo de la industria incluyendo Amazon, Meta, Microsoft, Salesforce, Stripe, y Wayfair.

Para desarrolladores, la superficie de implementación concreta es el servidor Storefront MCP. Cada tienda Shopify tiene su propio punto final MCP exponiendo características de tienda incluyendo búsqueda de productos, operaciones de carrito, y preguntas de política. Las herramientas search_catalog, lookup_catalog, y get_product se conforman a la especificación UCP.

Nota crítica de migración: Las herramientas de carrito heredadas de Storefront MCP (get_cart y update_cart) están siendo obsoletas a favor de UCP Cart MCP. Las herramientas obsoletas se mantendrán hasta el 31 de agosto de 2026, que es el mismo trimestre que el retiro de API 2024-10. Dos migraciones convergen en la misma fecha límite de otoño.

Si estás construyendo un agente con marca o una experiencia de compra de IA personalizada, la arquitectura es directa:

• Usa Storefront MCP para búsqueda de catálogo y recuperación de detalle de producto.
• Usa UCP Cart MCP para operaciones de carrito (añadir, actualizar, leer artículos de línea).
• Usa Checkout Kit (o el próximo Checkout MCP, actualmente en vista previa de socio) para el traspaso de pago.

Para comerciantes que no están construyendo agentes personalizados, la acción práctica es más simple: activa los canales de IA que quieres vender en el administrador de Shopify a través de Storefronts con agentes, y Shopify gestiona el trabajo de protocolo. ChatGPT, Google AI Mode, Perplexity, y Microsoft Copilot son todos accesibles a través de una configuración única de administrador.

Autenticación y tokens de acceso: qué cambia en enero de 2027

Un elemento que cae fuera del ciclo de versión de API de 2026 pero que afecta directamente a integraciones de Storefront API: a partir del 1 de enero de 2027, todas las aplicaciones públicas deben usar tokens de acceso sin conexión que expiran para llamadas de Admin API. Este es un cambio de Admin API, no un cambio de Storefront API, pero muchas integraciones usan ambas juntas, si tu compilado headless se basa en un token de Admin API de larga duración para operaciones de backend (sincronización de inventario, gestión de pedidos, escrituras de metafields), necesitas planificar esa migración junto con tu actualización de versión de Storefront API.

Tu lista de verificación de migración para el resto de 2026

Aquí está la lista de acciones secuenciadas, ordenada por urgencia:

1. Comprueba tu versión fija actual. Abre tu configuración de Hydrogen o encabezados de consulta GraphQL. Cualquier cosa más antigua que 2025-07 necesita atención inmediata.
2. Prueba contra 2026-07 RC. Configura un ambiente de ensayo contra el candidato de lanzamiento. Enfócate en mutaciones de carrito y cualquier lógica de visualización de descuento personalizado.
3. Implementa visitorConsent en @inContext. Si tu compilado headless aún no propaga el consentimiento de cookies a través de la checkoutUrl, añádelo ahora. Requiere versión de API 2025-10 o posterior.
4. Reemplaza enumeraciones de metaobjetos obsoletas. Elimina cualquier referencia PRIVATE o PUBLIC_READ antes de que 2026-07 se estabilice el 1 de julio.
5. Migra de herramientas de carrito de Storefront MCP a UCP Cart MCP. Fecha límite: 31 de agosto de 2026.
6. Audita metafields JSON mayores a 128KB. Requerido antes de cualquier actualización a 2026-04 o posterior.
7. Registra una firma de Web Bot Auth si operas cualquier bot o agente que golpee puntos finales de Storefront API.

Si necesitas ayuda práctica planificando o ejecutando cualquiera de estas migraciones, los servicios de desarrollador de Shopify que ofrezco cubren actualizaciones de versión, revisiones de arquitectura headless, y auditorías de rendimiento de Storefront API.