Logo

¿Qué ha cambiado en el mecanismo de actualización del token offline de Shopify?

avatar jayce 03 Sep 2026

Si recientemente has estado manteniendo el código de autorización de la aplicación de Shopify, esta actualización merece una mirada más cercana.

El 10 de diciembre de 2025, Shopify especificó en el changelog para desarrolladores: el token de acceso offline ahora admite caducidad y actualización. El 20 de marzo de 2026, otro changelog añadió una declaración más contundente: después del 1 de abril de 2026, las nuevas aplicaciones públicas creadas y que llamen a la API de administración, deberán utilizar un token de acceso offline que caduque.

Este no es un cambio que interrumpa de inmediato todas las aplicaciones antiguas. Las aplicaciones públicas existentes, las aplicaciones personalizadas y las aplicaciones creadas por los comerciantes en el backend no están sujetas a esta regla del 1 de abril. Sin embargo, si estás desarrollando una nueva aplicación o planeas lanzar una nueva aplicación pública este año, es mejor que incorpores esta lógica de actualización desde la primera versión.

La suposición anterior de “instalar y usar indefinidamente” ha desaparecido

Muchas tareas de backend de las aplicaciones de Shopify dependen del token offline. Por ejemplo, sincronización de pedidos, procesamiento de webhook, actualización programada de productos, generación de informes para la tienda. Cuando el comerciante no está en línea, la aplicación también necesita poder llamar a la API de administración, por lo que el token offline siempre ha sido la opción predeterminada.

El manejo en el código antiguo era bastante simple: el comerciante obtenía el token al instalar, lo almacenaba en la base de datos; luego, cada vez que se hacía una solicitud a la API de administración, se incluía en el X-Shopify-Access-Token. Siempre que el comerciante no desinstalara la aplicación, el equipo generalmente asumía que este token seguiría siendo válido.

El nuevo token offline que caduca ha desmantelado esta suposición. La documentación oficial ahora lo deja claro: la validez del token de acceso offline que caduca es de 1 hora, y el campo expires_in en la respuesta es 3600. Al mismo tiempo, se devuelve un refresh_token, que la aplicación puede usar para obtener un nuevo token de acceso sin molestar al comerciante.

Por ejemplo, un sitio independiente que vende suministros para mascotas, con alrededor de doscientos SKU, sincroniza el inventario cada 15 minutos. Anteriormente, la tarea de sincronización solo necesitaba leer el token offline de la tabla de la tienda. Ahora, al menos necesita verificar dos campos más: cuándo caduca el token de acceso y si el refresh token sigue siendo válido. De lo contrario, la tarea de sincronización de la madrugada que se encuentra con un 401 por primera vez podría detener toda la sincronización de inventario durante la noche.

La actualización no es volver a pasar por el proceso de instalación

Un punto clave de este cambio de Shopify es que la actualización ocurre en el endpoint del token, sin necesidad de que el comerciante vuelva a autorizar.

El endpoint de token OAuth que proporciona la documentación oficial es:

POST https://{shop}.myshopify.com/admin/oauth/access_token

Si utilizas el intercambio de tokens, al obtener el token offline puedes incluir requested_token_type=urn:shopify:params:oauth:token-type:offline-access-token y establecer expiring en 1. Si utilizas el grant de código de autorización, también lo haces al intercambiar el código mediante expiring=1 para solicitar un token offline que caduque.

En la respuesta, no solo debes guardar el access_token. Al menos también debes guardar lo siguiente:

• expires_in: el número de segundos restantes para el token de acceso actual, que ahora es 3600 segundos según la documentación oficial.

• refresh_token: el que se utilizará para la próxima actualización del servidor.

• refresh_token_expires_in: el período de validez inicial del refresh token, que la documentación oficial indica como 7776000 segundos, es decir, 90 días.

No debes fijar 3600 de forma rígida. La documentación oficial también advierte que la aplicación debe leer expires_in de la respuesta y no asumir que la validez permanecerá invariable.

El mayor riesgo es la actualización concurrente

La lógica de actualización parece bastante común, pero el verdadero problema radica en la rotación.

La documentación de Shopify es muy detallada: cada vez que se actualiza, se devolverán un nuevo access token y un nuevo refresh token. La aplicación debe almacenar ambos, y la próxima vez que se actualice, debe utilizar el nuevo refresh token.

El antiguo refresh token no se invalidará instantáneamente en el segundo en que Shopify emita un nuevo token. Se invalidará en el primer momento que ocurra entre varias condiciones: la aplicación ha utilizado el nuevo refresh token; la aplicación ha vuelto a obtener un nuevo token a través del intercambio de tokens o del grant de código de autorización; el antiguo refresh token ha sido utilizado para actualizar por primera vez durante 30 días; o ha caducado su período original de 90 días.

Esta regla tiene un impacto directo en la implementación. Supongamos que tu trabajador de webhook y la tarea programada descubren al mismo tiempo que el token está a punto de caducar, y ambos procesos intentan actualizar simultáneamente. Ambos escribirán los resultados en la base de datos, y el que se escriba después sobrescribirá al anterior. La próxima vez que se haga una solicitud, el token que se obtenga podría depender de la carrera de condiciones.

Una práctica más segura es agregar un bloqueo a nivel de tienda, o realizar una actualización condicional en la base de datos: solo se permite escribir un nuevo token si el refresh token en el registro actual es el que acabas de leer. Si la actualización falla, vuelve a leer el registro una vez más, y no expulses al comerciante de inmediato de OAuth.

El 401 no es el único punto de activación

Actualizar solo después de recibir un 401 puede recuperar algunas solicitudes, pero las tareas de backend fallarán una vez más. Esto es aceptable para tareas como webhook que tienen reintentos, pero para exportaciones manuales o actualizaciones masivas, la experiencia será bastante áspera.

La recomendación oficial es actualizar unos minutos antes, y al recibir un 401, realizar una actualización adicional. En la implementación, puedes guardar expires_at para cada tienda y verificar antes de la solicitud si está a punto de caducar. Por ejemplo, si queda menos de 5 minutos para la caducidad, actualiza primero y luego solicita a la API de administración.

Las fallas en la actualización también deben ser reportadas por separado. Las razones pueden ser que el refresh token ha caducado, el client secret ha sido rotado, el comerciante ha desinstalado la aplicación, o tu almacenamiento no ha guardado correctamente el nuevo refresh token. Todos estos pueden manifestarse como un 401, pero el manejo será diferente.

Las aplicaciones antiguas pueden tomarse un respiro, pero no sigas acumulando deuda técnica

La exigencia del 1 de abril de 2026 solo se aplica a las nuevas aplicaciones públicas. Shopify también ha indicado que las aplicaciones públicas creadas antes del 1 de abril no se verán afectadas por el momento.

Sin embargo, la documentación sobre los tokens de acceso contiene otra línea de tiempo: las aplicaciones públicas deberán utilizar tokens de acceso offline que caduquen para solicitar la API de administración a partir del 1 de enero de 2027. Las aplicaciones personalizadas y las aplicaciones creadas por comerciantes no están incluidas en este ámbito.

Por lo tanto, las aplicaciones antiguas no necesitan migrar hoy, pero si ya estás modificando la capa de autorización, es mejor que dejes la estructura de la tabla y la ruta de actualización listas. Al menos, elimina comentarios como “el token offline nunca caduca” y no clasifiques automáticamente el 401 como una desinstalación del comerciante en las tareas de backend.

No he intentado confirmar línea por línea la implementación interna de la última biblioteca en un proyecto de plantilla de Shopify real. La documentación oficial dice que si utilizas plantillas y bibliotecas de aplicaciones de Shopify, esta parte ya está manejada. Para proyectos que implementan OAuth, aplicaciones antiguas de Rails, o que han modificado la capa de autorización de la plantilla, aún deberías revisar el almacenamiento de tokens y la ruta de actualización.

Puedes comenzar a modificar estos puntos

No es necesario reescribir todo el sistema de autorización desde el principio. Primero, revisa cuatro áreas:

• ¿Hay un lugar en la base de datos para almacenar refresh_token, expires_at, refresh_token_expires_at?

• En el encapsulamiento de solicitudes de la API de administración, ¿se puede verificar el tiempo de caducidad antes de la solicitud?

• ¿Las tareas de backend y los trabajadores de webhook intentarán actualizar simultáneamente el token de la misma tienda?

• En los registros de 401, ¿se puede distinguir entre la caducidad del token, el alcance insuficiente y la desinstalación de la aplicación?

Si la aplicación aún está utilizando un token offline no caducado, la nueva versión puede agregar expiring=1 al instalar o al intercambiar el token, y luego conectar la lógica de actualización a un cliente API unificado. De esta manera, la sincronización de productos, la sincronización de pedidos y las tareas de informes no necesitarán escribir el código de actualización por separado.

Este cambio no es ostentoso, pero se asemeja a que Shopify está llevando la autorización de la aplicación hacia un comportamiento de OAuth más estándar. Las tareas de backend aún pueden seguir funcionando, solo que no podrán depender de un token permanente para sostener todo el ciclo de vida.

Fuentes oficiales:

• https://shopify.dev/changelog/offline-access-tokens-now-support-expiry-and-refresh

• https://shopify.dev/changelog/expiring-offline-access-tokens-required-for-public-apps-april-1-2026

• https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens

预约免费 30 分钟咨询