La API de Shopify 2025-10 ya no tiene soporte: cómo pasar a 2026-10 sin romper nada

El 16 de octubre de 2026 a las 15:00 UTC, la versión 2025-10 de las APIs de Shopify dejó de estar accesible. Es la fecha que aparece en la tabla de la página de versiones de la API de Shopify, donde 2025-10 ya figura como Unsupported. Esa tarde no se cayó nada. Las apps que todavía piden 2025-10 siguieron recibiendo respuestas con HTTP 200. Lo que cambió es que esas respuestas ya no salen de 2025-10.

Esta guía explica qué significa eso para una app que ya tienes en marcha: cómo ver qué versión responde de verdad, dónde se esconde la versión en el código, qué cambia la versión 2026-10 en pedidos, impuestos y metafields, cómo probar el cambio en una tienda de desarrollo y cómo dejar un aviso programado para que la próxima fecha no te pille desprevenido.

La app que nadie vuelve a abrir

Las apps más expuestas no son las públicas de la App Store. Esas tienen un equipo, un proceso de revisión y casi siempre alguien que lee el changelog. Las expuestas son la app a medida que se hizo para una tienda en 2024, la integración que sincroniza pedidos con un ERP, el script que un freelance escribió para actualizar precios desde una hoja de cálculo. Alguien fijó una versión de la API el día en que se escribió, funcionó, y desde entonces nadie ha tenido motivo para abrir el archivo.

Si no tienes claro qué tipo de app es la tuya, apps de Shopify públicas, a medida o privadas explica las diferencias. Para el versionado todas se comportan igual: cada petición nombra una versión, y esa versión tiene fecha de caducidad la vigile alguien o no. Con las credenciales pasa lo mismo, por eso conviene leer junto a este artículo el de tokens offline con caducidad antes de 2027.

Cómo funcionan las versiones trimestrales de Shopify

Shopify publica una versión nueva de la API cada tres meses, el primer día de cada trimestre, y la nombra por la fecha: 2026-01, 2026-04, 2026-07, 2026-10. La página de versiones da dos garantías: cada versión estable tiene soporte durante un mínimo de 12 meses, y dos versiones consecutivas se solapan al menos nueve meses. El mismo día de cada versión estable se publica la release candidate de la siguiente, y existe una versión unstable para probar cosas antes de tiempo. Ninguna de las dos es para producción.

El día en que se escribe esto, la tabla publicada dice lo siguiente:

• 2025-10: publicada el 1 de octubre de 2025, accesible hasta el 16 de octubre de 2026 a las 15:00 UTC. Sin soporte.
• 2026-01: accesible hasta el 16 de enero de 2027 a las 15:00 UTC. Estable.
• 2026-04: accesible hasta el 16 de abril de 2027 a las 15:00 UTC. Estable.
• 2026-07: accesible hasta el 16 de julio de 2027 a las 15:00 UTC. Estable.
• 2026-10: publicada el 1 de octubre de 2026, accesible hasta el 16 de octubre de 2027 a las 15:00 UTC. Última estable.
• 2027-01: release candidate.

Un detalle a tener en cuenta: las notas de la versión 2026-10 dicen que está disponible para producción "until at least October 1, 2027 at 15:00 UTC", mientras que la tabla de versiones dice 16 de octubre de 2027. Planifica con la fecha más temprana. El aviso automático que aparece más abajo usa el mínimo documentado de 12 meses justo por eso.

Qué pasa cuando una app pide una versión que ya no existe

La página de versiones lo dice sin rodeos: "If your app targets an inaccessible version, Shopify falls forward and responds using the oldest accessible stable version." Es decir, si la app pide una versión inaccesible, Shopify avanza y responde con la versión estable accesible más antigua. No rechaza la petición ni devuelve un estado de error. La atiende con otra versión.

Hoy la versión estable accesible más antigua es 2026-01. Así que una app que pide /admin/api/2025-10/graphql.json está leyendo y escribiendo, ahora mismo, a través de 2026-01. El 16 de enero de 2027, cuando 2026-01 llegue a su fecha de la tabla, la misma petición volverá a moverse, a 2026-04 si la tabla se mantiene. La app no cambia. La versión que tiene detrás cambia tres veces al año.

Es un riesgo silencioso por tres motivos. Primero, no hay ningún error sobre el que alertar: el código de estado es 200 antes y después. Segundo, el salto se salta la revisión: lo que cambió entre 2025-10 y 2026-01 ya se aplica a tus consultas sin que nadie haya leído las notas de 2026-01. Un campo eliminado, un valor nuevo en un enum o una validación más estricta aparecen como datos incorrectos o como un proceso que falla, no como un aviso de deprecación. Tercero, también afecta a los webhooks. La documentación de Shopify dice que los payloads de webhooks se versionan igual y avanzan cuando la versión elegida deja de estar accesible, así que un handler de pedidos puede empezar a recibir una estructura con la que nunca se probó.

Cómo ver qué versión respondió de verdad

Cada respuesta lo dice. Según la documentación de versiones, "API responses include the X-Shopify-API-Version header reflecting the version used to fulfill the request": las respuestas incluyen esa cabecera con la versión que atendió la petición. Si no coincide con la que pediste, Shopify ha avanzado de versión. Las entregas de webhooks por HTTPS llevan la misma cabecera. Comprobarla cuesta una línea, y es la única señal que vas a tener.

Con curl, imprime las cabeceras de la respuesta y quédate con la que importa:

curl -sS -o /dev/null -D - \
  -X POST "https://$SHOP/admin/api/2025-10/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ADMIN_TOKEN" \
  -d '{"query":"{ shop { name } }"}' \
  | grep -i '^x-shopify-api-version'

Según la tabla actual, una petición a 2025-10 debería mostrar 2026-01. Es el valor que se espera según la documentación, no una respuesta capturada: ejecútalo contra tu propia tienda y lee lo que devuelve.

Con fetch, comprueba la cabecera en cada llamada, dentro de la única función por la que pasan todas tus llamadas a la Admin API. Esta versión también maneja los errores, que se explican más abajo en la sección sobre respuestas 200:

// admin-graphql.mjs: todas las llamadas a la Admin API pasan por esta función.
const SHOP = process.env.SHOPIFY_SHOP; // tu-tienda.myshopify.com
const TOKEN = process.env.SHOPIFY_ADMIN_TOKEN;
const API_VERSION = process.env.SHOPIFY_API_VERSION || '2026-10';

export async function adminGraphql(query, variables = {}) {
  const res = await fetch(`https://${SHOP}/admin/api/${API_VERSION}/graphql.json`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-Shopify-Access-Token': TOKEN },
    body: JSON.stringify({ query, variables }),
  });

  // La versión que respondió de verdad. Si no coincide, Shopify avanzó de versión.
  const served = res.headers.get('X-Shopify-API-Version');
  if (served && served !== API_VERSION) {
    console.warn(`Se pidió la Admin API ${API_VERSION}, respondió ${served}`);
  }

  if (!res.ok) {
    // 401, 403, 404, 5xx: falló la propia petición. No la leas como datos.
    throw new Error(`Admin API HTTP ${res.status}: ${await res.text()}`);
  }

  const body = await res.json();
  // Un 200 puede traer errores: sintaxis, un campo desconocido, THROTTLED
  // y, en 2026-10, un filtro de metafield que la definición no permite.
  if (body.errors?.length) {
    const err = new Error(body.errors.map((e) => e.message).join(' | '));
    err.codes = body.errors.map((e) => e.extensions?.code).filter(Boolean);
    err.partialData = body.data; // puede ser null o parcial
    throw err;
  }
  return body.data;
}

Con la librería oficial @shopify/shopify-api, la versión es la opción apiVersion de shopifyApi(), y es obligatoria. El enum ApiVersion del código actual de la librería incluye October26 = '2026-10'; si la versión que tienes instalada no lo trae, actualiza primero el paquete. El ejemplo es para una app a medida creada desde el admin de la tienda, lo que la librería llama custom store app. El cliente GraphQL devuelve las cabeceras de la respuesta y lanza GraphqlQueryError cuando la respuesta contiene errores:

// shopify.server.ts: el único sitio donde se elige la versión de la Admin API.
import '@shopify/shopify-api/adapters/node';
import { shopifyApi, ApiVersion, GraphqlQueryError } from '@shopify/shopify-api';

export const SHOPIFY_API_VERSION = ApiVersion.October26; // '2026-10'

export const shopify = shopifyApi({
  apiSecretKey: process.env.SHOPIFY_API_SECRET ?? '',
  adminApiAccessToken: process.env.SHOPIFY_ADMIN_TOKEN ?? '',
  isCustomStoreApp: true, // app a medida creada desde el admin de la tienda
  isEmbeddedApp: false,
  hostName: 'tu-tienda.myshopify.com',
  apiVersion: SHOPIFY_API_VERSION,
});

export async function servedVersion(shop: string): Promise<string | undefined> {
  const session = shopify.session.customAppSession(shop);
  // Sin apiVersion aquí, así que el cliente usa SHOPIFY_API_VERSION.
  const client = new shopify.clients.Graphql({ session });
  try {
    const response = await client.request('{ shop { name } }');
    // Los nombres de cabecera pueden llegar en cualquier caja, y el valor como texto o como array.
    const headers = response.headers ?? {};
    const key = Object.keys(headers).find((k) => k.toLowerCase() === 'x-shopify-api-version');
    const value = key ? headers[key] : undefined;
    return Array.isArray(value) ? value[0] : value;
  } catch (error) {
    if (error instanceof GraphqlQueryError) {
      // Los errores que vienen dentro de una respuesta 200 terminan aquí.
      console.error(error.body?.errors?.graphQLErrors, error.headers);
    }
    throw error;
  }
}

Dónde queda fijada la versión, y cómo tenerla en un solo sitio

Una app casi nunca fija su versión en un único lugar. Estos son los sitios donde buscar:

• La configuración de la librería: apiVersion en shopifyApi(), o su equivalente en los clientes de Ruby, PHP o Python.
• Clientes con versión propia: new shopify.clients.Graphql({ session, apiVersion }) acepta su propia versión y pisa la general sin avisar.
• URLs escritas a mano: cualquier texto con /admin/api/2025-10/, muchas veces en scripts viejos, tareas cron y colecciones de Postman.
• Imports de recursos REST: @shopify/shopify-api/rest/admin/2026-01 lleva la versión en la ruta del import.
• shopify.app.toml: [webhooks] api_version es la versión con la que se serializan los webhooks, y [events] api_version la que valida y ejecuta las consultas de suscripción a eventos. Las dos son obligatorias según la documentación de configuración de apps.
• Suscripciones de webhooks creadas por API: para las suscripciones por tienda creadas con la GraphQL Admin API, la documentación de webhooks dice que la versión la determina la URL de la petición, no el archivo TOML.
• shopify.extension.toml: las extensiones declaran un api_version en el nivel superior. Para las extensiones de UI, la página de versiones indica que Shopify CLI bloquea los deploys que apuntan a versiones de más de 12 meses.
• Variables de entorno: SHOPIFY_API_VERSION o similar, definida por entorno y a veces distinta en staging y en producción.

Una sola búsqueda encuentra casi todos. Ejecútala desde la raíz del repositorio:

grep -rnE "admin/api/(20[0-9]{2}-[0-9]{2}|unstable)|api_version|apiVersion|ApiVersion\.|rest/admin/20|SHOPIFY_API_VERSION" \
  --exclude-dir=node_modules --exclude-dir=.git .

Después reduce la lista a dos fuentes de verdad: una constante en el código que importen todos los clientes, y los campos del TOML, que no pueden importar nada. Elimina cada versión propia de un cliente salvo que tenga al lado un motivo por escrito. El check del final de esta guía lee ambas fuentes, así que un TOML olvidado durante una actualización rompe el build en lugar de avanzar de versión tres meses después.

Qué cambia 2026-10 en pedidos, impuestos y metafields

Las notas de 2026-10 empiezan diciendo que varios cambios "require code updates, especially around order taxes, draft order discounts, metafield filters, and customer account checkouts": exigen tocar código, sobre todo en impuestos de pedidos, descuentos de borradores, filtros de metafields y checkouts de cuentas de cliente. Esto es lo que las notas, y las entradas del changelog que enlazan, recogen de verdad en estas tres áreas, y nada más.

Impuestos: cambiar la dirección de envío ahora los recalcula

Desde 2026-10, actualizar la dirección de envío de un pedido sin preparar recalcula los impuestos según el nuevo destino. Aplica a la mutación orderUpdate y al endpoint REST de actualización de pedidos. Antes, la dirección se guardaba pero las líneas de impuestos originales se quedaban, y los totales dejaban de corresponder al destino. Los pedidos preparados en parte o del todo mantienen sus impuestos, igual que las peticiones hechas con versiones anteriores a 2026-10. La entrada está marcada como cambio que rompe la API. Si tu app edita direcciones, vuelve a leer taxLines, totalTaxSet y los totales del pedido después de actualizar, y cuenta con un webhook orders/edited. Si el saldo de un pedido ya pagado sube, la entrada sugiere orderMarkAsPaid dentro de tu margen de tolerancia u orderInvoiceSend para importes mayores; si baja, refundCreate.

Pedidos: un campo eliminado y tres cambios de forma

• Se elimina el campo deprecado priceRule de DraftOrderDiscountNotAppliedWarning. Una consulta que lo pida falla la validación en 2026-10.
• Order.displayFulfillmentStatus puede devolver FULFILLMENT_NOT_REQUIRED en lugar de UNFULFILLED para pedidos sin nada pendiente de preparar. Cualquier switch o tabla de correspondencias sobre ese enum necesita un caso nuevo.
• orderCancel devuelve ahora un jobResult estructurado, para confirmar que la cancelación asíncrona terminó bien.
• Los gastos de envío de devoluciones tienen campos de impuestos nuevos.

Metafields: los filtros inválidos ahora fallan

Hasta 2026-07, una consulta products filtrada con metafields.custom.material:cotton sobre un metafield que no admite filtros ignoraba el filtro en silencio, y la consulta devolvía resultados igualmente. Desde 2026-10, la API valida los filtros de metafields y devuelve un error que nombra el filtro. Las causas habituales son un metafield sin definición, una definición que no permite filtrar o una comparación que su tipo no admite. Este cambio puede hacer que un proceso que "funcionaba" empiece a fallar, y es el mejor motivo para manejar bien el array errors. El objeto Metafield gana además un campo translatable no nulo, y las extensiones de UI de checkout y de cuentas de cliente pasan a exigir owner_type en sus declaraciones de metafields.

Las notas de 2026-10 no recogen ningún cambio en metaobjects. El resto de puntos que exigen acción quedan fuera de estas tres áreas: ProductVariant.barcode queda deprecado en favor de una conexión barcodes (todavía no se elimina), las funciones de consultas de segmentos usan MATCHES y NOT MATCHES, el consentimiento de marketing por SMS está ahora disponible como smsMarketingConsent en CustomerPhoneNumber, se elimina el error ITEM_NOT_STOCKED_AT_LOCATION y la Customer Account API pierde lastIncompleteCheckout. Las extensiones de UI de POS tienen además dos cambios que rompen compatibilidad.

Una advertencia importante: una app que pasa de 2025-10 a 2026-10 se salta tres versiones. Las notas de 2026-01, 2026-04 y 2026-07 también le aplican, y este artículo no las cubre. Léelas antes de cambiar la constante.

Para las tres áreas anteriores, estas búsquedas encuentran el código que hay que revisar:

grep -rnE "orderUpdate|shippingAddress|taxLines|totalTaxSet" src/
grep -rnE "metafields\.[a-z0-9_]+\.[a-z0-9_]+:" src/
grep -rnE "priceRule|UNFULFILLED|displayFulfillmentStatus|orderCancel" src/
grep -rnE "barcode" src/

Prueba en una tienda de desarrollo antes de producción

Cambiar la versión es una línea. Demostrar que no cambió nada más lleva una tarde en una tienda de desarrollo, en este orden:

1. Lee las notas de cada versión que te saltas y apunta los puntos que tocan tus consultas.
2. En una rama, pon la constante y los campos del TOML en 2026-10.
3. Ejecuta shopify app dev --store tu-tienda-dev.myshopify.com. Crea una vista previa de desarrollo en esa tienda con tu configuración local, incluido [webhooks] api_version, sin afectar a otras tiendas.
4. Abre shopify app graphiql --store tu-tienda-dev.myshopify.com --version 2026-10 y pega cada consulta y mutación que envía tu código. Un campo eliminado o un filtro de metafield inválido falla aquí, en segundos.
5. Prueba el comportamiento que cambió con datos reales: crea un pedido de prueba sin preparar, cambia su dirección de envío a otra zona fiscal con orderUpdate y compara totalTaxSet antes y después. Ejecuta cada filtro de metafield. Procesa un pedido que no necesite preparación y comprueba que tu código maneja FULFILLMENT_NOT_REQUIRED.
6. Envía a tu handler un payload de webhook de 2026-10 con shopify app webhook trigger --topic orders/updated --api-version 2026-10 --delivery-method http --address https://tu-tunel.example/webhooks. El payload es fijo y el comando no prueba tus suscripciones, pero demuestra que el handler entiende la estructura nueva.
7. Comprueba la cabecera en tus tests de integración: la versión que responde debe ser igual a la constante.
8. Despliega primero el código y después la configuración. shopify app deploy --no-release crea una versión de la app sin publicarla, así que el cambio del TOML entra en producción cuando tú decidas.

Un 200 no significa que funcionó

La referencia de la GraphQL Admin API advierte que puede devolver "a 200 OK response code in cases that would typically produce 4xx or 5xx errors in REST": un 200 donde REST daría un 4xx o un 5xx. Los errores llegan en un array errors en el nivel superior, cada uno con un message y normalmente un extensions.code como THROTTLED. La función adminGraphql() de arriba convierte ese array en una excepción, así que quien la llama no puede leer data sin enterarse.

Las mutaciones añaden una segunda capa. Cuando la operación es válida pero los datos de entrada no, la respuesta no trae errores en el nivel superior, y el problema está en userErrors, que solo recibes si lo pides:

const data = await adminGraphql(
  `mutation UpdateAddress($input: OrderInput!) {
    orderUpdate(input: $input) {
      order { id totalTaxSet { shopMoney { amount currencyCode } } }
      userErrors { field message }
    }
  }`,
  { input: { id: orderId, shippingAddress: newAddress } },
);

const { order, userErrors } = data.orderUpdate;
if (userErrors.length) {
  // No se guardó nada. Muestra o registra el motivo; no reintentes con los mismos datos.
  throw new Error(userErrors.map((e) => `${(e.field || []).join('.')}: ${e.message}`).join('; '));
}
// En 2026-10 los impuestos pueden haber cambiado: compáralos antes de dar el cambio por bueno.
console.log(order.totalTaxSet.shopMoney);

Trata los tres casos de forma distinta. Un error HTTP significa que la petición no llegó bien a la API. Una entrada en errors significa que la operación no es válida para esta versión, o que te limitaron por exceso de peticiones. Una entrada en userErrors significa que se rechazaron los datos. Solo el caso de límite de peticiones merece un reintento automático.

Una lista trimestral, con un aviso que se ejecuta solo

Shopify publica el 1 de enero, el 1 de abril, el 1 de julio y el 1 de octubre. Reserva una tarea recurrente de una hora en la primera semana después de cada versión:

• Lee las notas de la versión nueva y las entradas del changelog marcadas como breaking o action required.
• Ejecuta la búsqueda de versiones de arriba y confirma que cada punto fijado sigue apuntando a la constante.
• Revisa en tus logs si la cabecera X-Shopify-API-Version no coincide con lo pedido.
• Si tu versión fijada es la más antigua con soporte, empieza ya la actualización, en una tienda de desarrollo.
• Actualiza @shopify/shopify-api o tu librería cliente, para que exista el nuevo ApiVersion.

Un recordatorio en el calendario depende de una persona. Un check en CI, no. Este script lee las versiones fijadas y falla cuando a una le quedan 30 días o menos de soporte garantizado, con un aviso a partir de 90. Usa el mínimo documentado de 12 meses desde la fecha de publicación, que cae antes que las fechas que la tabla ha mostrado hasta ahora, así que nunca avisa tarde:

// scripts/check-shopify-api-version.mjs
// Hace fallar el CI cuando una versión fijada de la API de Shopify está cerca del fin de su soporte.
// Node 20+, sin dependencias. Se ejecuta desde la raíz del repositorio.
import { existsSync, readFileSync, readdirSync } from 'node:fs';
import { join } from 'node:path';

const WARN_DAYS = Number(process.env.API_VERSION_WARN_DAYS || 90);
const FAIL_DAYS = Number(process.env.API_VERSION_FAIL_DAYS || 30);

// Cada archivo que fija una versión. Añade el tuyo si está en otro sitio.
const files = ['shopify.app.toml', 'app/shopify-api-version.ts'].filter(existsSync);
if (existsSync('extensions')) {
  for (const f of readdirSync('extensions', { recursive: true })) {
    if (String(f).endsWith('shopify.extension.toml')) files.push(join('extensions', String(f)));
  }
}

const MONTH = { January: 1, April: 4, July: 7, October: 10 };
const found = [];
for (const file of files) {
  const text = readFileSync(file, 'utf8');
  // TOML: api_version = "2026-10"
  for (const m of text.matchAll(/api_version\s*=\s*"(\d{4})-(\d{2})"/g)) {
    found.push({ file, year: Number(m[1]), month: Number(m[2]) });
  }
  // @shopify/shopify-api: ApiVersion.October26
  for (const m of text.matchAll(/ApiVersion\.(January|April|July|October)(\d{2})\b/g)) {
    found.push({ file, year: 2000 + Number(m[2]), month: MONTH[m[1]] });
  }
  // Una constante de texto: SHOPIFY_API_VERSION = '2026-10'
  for (const m of text.matchAll(/SHOPIFY_API_VERSION\s*=\s*['"](\d{4})-(\d{2})['"]/g)) {
    found.push({ file, year: Number(m[1]), month: Number(m[2]) });
  }
}

if (found.length === 0) {
  console.log('::error::No se encontró ninguna versión fijada. Revisa la lista de archivos de este script.');
  process.exit(1);
}

let failed = false;
for (const v of found) {
  const name = `${v.year}-${String(v.month).padStart(2, '0')}`;
  // Shopify garantiza al menos 12 meses desde la publicación, el día 1 del mes.
  // La tabla publicada ha mostrado hasta ahora el día 16 a las 15:00 UTC; el día 1 es el límite seguro.
  const end = Date.UTC(v.year + 1, v.month - 1, 1);
  const days = Math.floor((end - Date.now()) / 86_400_000);
  const where = `${v.file}: ${name}`;
  const when = days < 0 ? `terminó hace ${-days} días` : `termina en ${days} días`;
  if (days <= FAIL_DAYS) {
    console.log(`::error::${where} - el soporte garantizado ${when}. Actualiza ya.`);
    failed = true;
  } else if (days <= WARN_DAYS) {
    console.log(`::warning::${where} - el soporte garantizado ${when}. Planifica la actualización.`);
  } else {
    console.log(`${where} - quedan ${days} días de soporte garantizado.`);
  }
}

process.exit(failed ? 1 : 0);

Los prefijos ::error:: y ::warning:: son anotaciones de GitHub Actions, así que el mensaje aparece en el resumen de la ejecución. Ejecútalo en cada pull request y una vez por semana, porque una versión caduca en una fecha, no en un commit:

# .github/workflows/shopify-api-version.yml
name: Shopify API version
on:
  pull_request:
  schedule:
    - cron: '0 7 * * 1'   # lunes a las 07:00 UTC
  workflow_dispatch:
jobs:
  check:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - name: Comprobar versiones fijadas
        run: node scripts/check-shopify-api-version.mjs

Dos detalles de la documentación de GitHub sobre schedule importan aquí. Las notificaciones de una ejecución programada que falla llegan al usuario que modificó por última vez la línea del cron, así que esa persona debería ser la responsable de la app. Y en un repositorio público, los workflows programados se desactivan tras 60 días sin actividad, que es justo el tipo de repositorio para el que sirve este check. Lo habitual en apps a medida es un repositorio privado; si el tuyo es público, deja el disparador de pull request y comprueba en cada revisión trimestral que el schedule sigue activo.

El trabajo de 2025-10 ya va con retraso, pero no es difícil: encontrar dónde está fijada la versión, leer tres notas de versión, probar las consultas afectadas en una tienda de desarrollo y añadir el check. Si prefieres delegarlo, forma parte de nuestro trabajo de mantenimiento de apps privadas.