API de edición de pedidos de Shopify: crea un flujo seguro de principio a fin

Por qué importan las tres etapas de la API#

Editar un pedido es una transacción, no una sola actualización. Shopify crea una versión calculada del pedido, permite que la aplicación prepare los cambios en ella y aplica esa versión cuando la aplicación confirma la edición.

Entre más de 10 millones de pedidos de tiendas que usan Revize, aproximadamente 1 de cada 19 pedidos, o el 5,2 %, se editó después de la pantalla de pago (Revize, 2026). Es un volumen suficiente para tratar la edición como parte habitual de las operaciones, en lugar de una excepción para el equipo de atención al cliente.

El objeto CalculatedOrder se parece a una copia de prueba de una lista de preparación de pedidos del almacén. Puedes añadir y quitar líneas de esa copia, revisar el resultado y, después, publicar una única versión final.

El momento de la edición importa tanto como usar correctamente la API. En las tiendas que usan Revize, la mediana de tiempo hasta la edición es de 4,6 minutos después de la pantalla de pago (Revize, 2026). Si la preparación empieza durante ese intervalo, incluso un código técnicamente correcto puede dar lugar a un paquete equivocado.

Cómo funciona la API de edición de pedidos de Shopify#

En la API de Shopify Admin 2026-07, el flujo es orderEditBegin, una o más mutaciones para preparar cambios y, después, orderEditCommit. Las referencias de mutaciones de Shopify aceptan tanto el ID del pedido calculado como el de la sesión de edición para preparar y confirmar cambios. Esta guía usa siempre calculatedOrder.id.

1. Llama a orderEditBegin con el ID del pedido de Shopify.
2. Guarda calculatedOrder.id como $calculatedOrderId.
3. Ejecuta cada mutación de preparación con ese ID.
4. Revisa las líneas calculadas, los totales y todos los arrays userErrors.
5. Pasa el mismo ID a orderEditCommit.

Shopify documenta este modelo de inicio, preparación y confirmación. La aplicación necesita el permiso de acceso write_order_edits.

Una mutación inicial mínima puede solicitar ambos objetos para facilitar el diagnóstico y, a la vez, elegir un solo identificador para el resto del flujo:

mutation BeginOrderEdit($orderId: ID!) {
  orderEditBegin(id: $orderId) {
    calculatedOrder {
      id
      lineItems(first: 50) {
        nodes {
          id
          quantity
        }
      }
    }
    orderEditSession {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Detén el proceso si userErrors no está vacío. Una solicitud de red correcta solo demuestra que Shopify recibió la solicitud, no que aceptó la operación.

La guía de edición para esta versión documenta operaciones para preparar cambios en variantes, cantidades, artículos personalizados, descuentos de líneas de pedido y líneas de envío. Consulta la referencia de la mutación para 2026-07 correspondiente antes de implementarla y cada vez que cambies de versión de la API.

Cómo implementar un cambio completo de variante#

Para cambiar una variante, añade la sustituta y establece en cero la cantidad de la línea calculada original dentro de la misma sesión de edición. Confirma la edición solo cuando ambas operaciones se hayan completado y el resultado calculado coincida con lo que confirmó el cliente.

Supongamos que un cliente pidió una talla mediana y necesita una grande.

1. Inicia la edición y guarda calculatedOrder.id.
2. Añade la variante de talla grande con ese ID:

mutation AddReplacement(
  $calculatedOrderId: ID!
  $variantId: ID!
  $quantity: Int!
) {
  orderEditAddVariant(
    id: $calculatedOrderId
    variantId: $variantId
    quantity: $quantity
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

3. Busca la talla mediana original en el pedido calculado. Usa el ID de su línea calculada en vez de copiar el ID de una línea del pedido original sin comprobar el estado calculado devuelto.

4. Establece en cero la cantidad de la línea original:

mutation RemoveOriginal(
  $calculatedOrderId: ID!
  $lineItemId: ID!
) {
  orderEditSetQuantity(
    id: $calculatedOrderId
    lineItemId: $lineItemId
    quantity: 0
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

5. Consulta de nuevo el pedido calculado. Confirma que la variante sustituta esté presente, que la cantidad de la original sea cero y que los totales coincidan con la confirmación del cliente.
6. Confirma la edición con el mismo ID del pedido calculado:

mutation CommitOrderEdit(
  $calculatedOrderId: ID!
  $notifyCustomer: Boolean!
  $staffNote: String
) {
  orderEditCommit(
    id: $calculatedOrderId
    notifyCustomer: $notifyCustomer
    staffNote: $staffNote
  ) {
    order {
      id
      updatedAt
    }
    userErrors {
      field
      message
    }
  }
}

Advertencia: No confirmes la edición si se añadió la variante sustituta, pero todavía no se quitó la original. Eso convertiría el cambio en un artículo adicional.

Rechaza los clics de confirmación duplicados, registra qué etapa se completó y vuelve a consultar el pedido antes de confirmar si otro proceso pudo haberlo modificado.

Qué mutación corresponde a cada edición#

Usa el flujo del pedido calculado para cambiar líneas de pedido, cantidades, descuentos y líneas de envío. Usa orderUpdate y las mutaciones de cancelación y reembolso solo para las tareas que documentan sus referencias de versión.

La referencia de orderUpdate para 2026-07 incluye atributos como el correo electrónico del cliente, la dirección de envío, las etiquetas y los metacampos, y muestra actualizaciones de notas en sus ejemplos. Para cambios importantes, como añadir o quitar líneas de pedido, cambiar cantidades o modificar descuentos, remite a orderEditBegin.

Las consideraciones sobre la edición de pedidos de Shopify indican que no se pueden editar los códigos de descuento, los descuentos automáticos ni los descuentos de scripts. Tampoco se pueden añadir, quitar ni cambiar descuentos aplicados al pedido completo. Las mutaciones de descuento de líneas de pedido no eliminan esos límites.

Dónde termina la API de edición de pedidos de Shopify#

Confirmar una edición y resolver el saldo son dos pasos distintos. Shopify señala que una edición que cambie el total puede dejar un saldo pendiente de pago para el cliente o requerir un reembolso.

Si el total aumenta, vuelve a consultar el pedido confirmado y comprueba cómo se cobrará el saldo antes de enviarlo a preparación de pedidos (fulfillment). No interpretes una respuesta correcta de orderEditCommit como prueba de que el pago se completó.

Si el total disminuye, confirmar la edición no sustituye un proceso de reembolso deliberado. Calcula el importe previsto, llama a la operación de reembolso adecuada y revisa su respuesta. Una edición sin diferencia de importe no requiere cobro ni reembolso, pero sí una última comprobación del estado del pedido.

Suscríbete al webhook orders/edited de Shopify y vuelve a consultar el pedido antes de que actúe un sistema posterior. Los webhooks son señales para leer el registro actual, no una razón para confiar en una copia local anterior.

No permitas que un proveedor logístico externo, o 3PL, prepare un pedido cuya edición o situación financiera siga sin resolverse. Prueba la retención, la regla basada en el estado del pago o la señal de liberación con el sistema de almacén que realmente descarga los pedidos.

Cómo diagnosticar los fallos de edición#

Empieza por comprobar la elegibilidad, los identificadores, la validación y los cambios simultáneos. Registra el nombre de la mutación, el ID del pedido de Shopify, el ID de edición elegido y el array userErrors completo, sin guardar datos confidenciales del cliente ni del pago.

Los requisitos de edición de pedidos de Shopify indican que las aplicaciones necesitan write_order_edits, solo pueden editar líneas de pedido no preparadas y no pueden editar pedidos archivados ni pedidos realizados antes del 1 de enero de 2019. De forma predeterminada, las aplicaciones tienen acceso a los pedidos de los últimos 60 días; para consultar pedidos más antiguos necesitan read_all_orders.

Son reglas distintas. read_all_orders amplía el acceso a registros antiguos, pero no permite editar un pedido archivado o anterior a 2019.

No bases el comportamiento de la aplicación en una cadena de error supuesta. Lee el campo y el mensaje devueltos para esa solicitud y, después, reproduce el fallo con un pedido de prueba controlado.

Crear tu solución con Revize o empezar por las API#

Revize es la opción más sólida cuando buscas que el cliente edite su pedido por sí mismo antes de la preparación; el código personalizado encaja con una coordinación interna propia. La decisión depende de si quieres un recorrido de cliente ya preparado o asumir cada interfaz, transición y medida de protección del almacén.

El código personalizado tiene una función clara cuando un comerciante necesita una consola propia para el personal o un proceso de aprobación que abarque sistemas internos. Revize no ofrece una API general de edición de pedidos ni una cola de aprobación para comerciantes.

Las agencias pueden conectar los activadores documentados de Shopify Flow a los eventos de edición de Revize, usar las etiquetas de edición y liberación de Revize en la lógica de preparación de pedidos o usar la Public Cancellation API para ofrecer la cancelación desde una interfaz externa. La Public Cancellation API está disponible solo en Pro, requiere que el equipo de soporte la habilite y aplica el plazo de edición, las restricciones y la política de reembolsos del portal.

Entre las ediciones posteriores a la compra en tiendas que usan Revize, el 92,2 % las completaron los clientes sin ayuda de un agente de soporte (Revize, 2026). La guía para agencias sobre la edición de pedidos después de la compra explica qué conviene analizar antes de la implementación.

La disponibilidad de las funciones varía según el plan. Las adiciones y los cambios de productos, los reembolsos en crédito de la tienda, el recálculo de descuentos, envíos e impuestos, el motor de reglas, Reverse Unpaid Edits y la Public Cancellation API están disponibles solo en Pro, como se detalla en la documentación de facturación de Revize.

Instala Revize: Order Editing & Upsell si necesitas que los clientes puedan editar sus pedidos por sí mismos en lugar de otra interfaz interna de edición.

Cómo completa Revize el flujo#

Revize ofrece a los clientes un flujo de edición controlado en la página de estado del pedido de Shopify. El comerciante define el plazo, las acciones disponibles, la política de reembolsos y el modo de procesamiento de pedidos.

Cuando una edición aumenta el total, Revize muestra Pay now y redirige al cliente a la pantalla de pago de Shopify únicamente para pagar la diferencia. Si el total disminuye, muestra Refund; si no cambia, muestra Confirm. Shopify ejecuta el pago o el reembolso, tal como se describe en el flujo del cliente de Revize.

El comerciante configura el plazo en Order Editing > Order edit window. La guía para configurar el plazo de edición documenta opciones de duración fija, duraciones personalizadas, horas de cierre programadas y el modo que permite editar hasta la preparación del pedido. Este último modo no retiene un pedido por sí solo.

Con el modo de procesamiento recomendado, Revize aplica una retención de preparación de pedidos de Shopify durante el plazo de edición y la libera cuando ese plazo termina. Los sistemas que ignoran las retenciones pueden necesitar la alternativa documentada de captura manual del pago. Como otra opción, una etiqueta de liberación puede avisar a un sistema de preparación de pedidos configurado para esperar esa etiqueta.

Revize comprueba el inventario en tiempo real según la zona de envío antes de permitir que un cliente cambie de variante. La guía sobre retenciones de preparación de pedidos explica la parte del flujo que corresponde al almacén.

Qué probar esta semana#

Prueba un pedido desde la pantalla de pago hasta la preparación corregida, incluidos los fallos. Una mutación correcta en un cliente GraphQL es solo la primera comprobación.

1. Crea un pedido de desarrollo o un pedido preliminar representativo.
2. Prueba un cambio sin diferencia de precio, un aumento de valor y una disminución.
3. Revisa userErrors después del inicio, de cada mutación de preparación y de la confirmación.
4. Comprueba el pedido calculado antes de confirmar.
5. Verifica por separado cómo se gestionan los cobros y los reembolsos.
6. Envía el pedido editado a través del sistema real de preparación de pedidos.
7. Prueba un pedido archivado, uno antiguo, intentos simultáneos y un proceso abandonado.
8. Revisa los límites de la edición nativa de pedidos de Shopify antes de habilitar el acceso en producción.