Checkout de VTEX: personalizar sin romper
Qué se puede personalizar del checkout de VTEX, qué no conviene tocar y cómo hacer cambios con customData, JS y deploys sin cortar la venta en producción.

Gonzalo Mattia
16 de noviembre de 2026 · 7 min de lectura
El checkout es la parte de una tienda VTEX donde menos margen de error hay. Podés tener una home rota media hora y nadie se entera. Si el checkout falla un rato un sábado a la noche, lo ves en la facturación del lunes.
Aun así, es una de las zonas donde más pedidos de cambio llegan: un campo más para la factura, otro texto en el resumen, un banner de cuotas, un paso que se quiere sacar. En los proyectos que hice trabajando para agencias, casi todos los incidentes graves de checkout vinieron de customizaciones mal planteadas, no de VTEX.
Primero, cómo funciona por dentro
El checkout de VTEX no es una página que vos armás, es un producto de la plataforma. Toda la lógica vive alrededor del orderForm: un objeto que representa el carrito con items, precios, promociones, datos del cliente, envío y pago.
Cada vez que algo cambia (sumás un producto, cargás el código postal, elegís un medio de pago), el checkout le pide al backend que recalcule el orderForm. Vos podés observar y modificar ese objeto por API, pero el motor de cálculo no es tuyo. Entender esto ordena todas las decisiones que vienen después.
Lo que sí se puede personalizar
Hay bastante más de lo que la gente cree, siempre que se use el canal correcto:
- Estilos: con CSS podés cambiar tipografías, colores, espaciados, ocultar elementos decorativos y adaptar el look a la marca.
- Comportamiento en el front: con JavaScript podés agregar mensajes, validaciones extra, banners contextuales o lógica que reaccione a lo que hay en el carrito.
- Datos adicionales: con customData podés guardar información propia dentro del pedido, que después viaja al ERP o al OMS.
- Configuración del orderForm: mínimos de compra, campos obligatorios, comportamiento de algunos pasos.
- Página de confirmación: en Store Framework, la app de order placed se arma con bloques y se puede extender bastante.
Para la parte visual y de scripts, mi recomendación hoy es trabajar con checkout-ui-custom en VTEX IO. Te da un lugar ordenado para el CSS y el JS, versionado y la posibilidad de validar antes de publicar. Editar los archivos a mano desde el admin legacy funciona, pero el cambio impacta producción en el momento.
Lo que no se puede (o no conviene) tocar
Acá es donde se pierden semanas. Hay cosas que directamente no están abiertas:
- El cálculo de precios y promociones: lo resuelve el motor. Si una promo no aplica, se arregla en el módulo de promociones o en las listas de precios, no con JS.
- El formulario de tarjeta: por PCI, los datos de tarjeta se cargan en un entorno aislado. Podés ajustar poco de su apariencia y nada de su lógica.
- El orden y la estructura de los pasos: podés esconder, reordenar visualmente o agregar cosas, pero el flujo base es el que es.
Y hay cosas que técnicamente se pueden, pero no conviene. La más común es ocultar con CSS un campo obligatorio y completarlo por JS para que el usuario no lo vea. Funciona hasta que VTEX cambia un selector, el script no corre y el cliente queda trabado sin entender por qué.
Campos extra: customData bien hecho
El caso típico en Argentina es facturación: condición frente al IVA, razón social, CUIT para factura A. La forma prolija es registrar una app de customData en la configuración del orderForm y escribir ahí desde el front.
Primero se declara la app con sus campos en la configuración del orderForm vía API. Después, desde el checkout:
vtexjs.checkout.setCustomData({
app: 'facturacion',
field: 'condicionIva',
value: 'responsable-inscripto'
});
Ese dato queda guardado en el pedido y lo podés leer desde el OMS o desde la integración con el ERP. Lo que no tenés que hacer es meterlo en un campo que no corresponde, como el complemento de la dirección o el nombre de la empresa, porque después nadie sabe de dónde salió.
Dos detalles que se olvidan seguido: validar en el front y también del lado de la integración, y definir qué pasa si el campo viene vacío. El ERP no puede rechazar el pedido en silencio.
JavaScript en el checkout: reglas para no romperlo
El DOM del checkout cambia. VTEX actualiza el producto y los selectores que hoy usás pueden no existir mañana. Por eso el JS tiene que apoyarse en el orderForm y en los eventos, no en la estructura del HTML.
$(window).on('orderFormUpdated.vtex', function (e, orderForm) {
// reaccionar a cambios del carrito, no a cambios del DOM
});
Algunas reglas que aplico siempre:
- Todo el código envuelto en manejo de errores. Si tu script falla, el checkout tiene que seguir funcionando.
- Nada que bloquee el botón de compra salvo una validación de negocio real y explicada al usuario.
- Escuchar el cambio de paso por el hash de la URL (carrito, email, perfil, envío, pago) en vez de adivinar con timers.
- Scripts de terceros al mínimo. Cada tag en la página de pago es un riesgo de performance y de seguridad.
Ese último punto merece atención. He visto checkouts con cinco o seis píxeles de marketing cargando en el paso de pago. Además de sumar segundos, cualquier script ahí tiene acceso a la página donde el cliente pone sus datos.
El caso argentino
Operar en Argentina agrega complejidad que conviene resolver con criterio:
- Documento: DNI para consumidor final, CUIT para empresas. Definí bien cuándo se pide cada uno y validá el formato.
- Cuotas: el mensaje de cuotas sin interés tiene que salir de las condiciones de pago configuradas, no de un texto hardcodeado que queda desactualizado cuando cambia la promo bancaria.
- Envíos: los códigos postales y la cobertura de cada operador logístico se configuran en logística. Si el checkout muestra un envío que no existe, el problema está en la configuración, no en el front.
- Medios de pago: cada conector tiene su propio flujo y algunos redirigen fuera de la tienda. Probalos todos, incluida la vuelta al sitio y el pedido cancelado.
Cómo deployar sin cortar la venta
El error más caro que vi fue un cambio de JS subido un viernes a la tarde directo desde el admin. Rompía el paso de envío solo en mobile y solo para retiro en sucursal. Se detectó el lunes.
Lo que recomiendo para cualquier cambio en checkout:
- El código en un repositorio, nunca solo en el admin. Tiene que haber historial y una forma rápida de volver atrás.
- Validación en un workspace o entorno de prueba antes de publicar.
- Una matriz de pruebas fija: usuario logueado y anónimo, envío a domicilio y retiro, cada medio de pago, mobile y desktop, carrito con y sin promociones.
- Deploy en horario de baja venta y con alguien mirando pedidos y errores la hora siguiente.
- Plan de rollback escrito, que se pueda ejecutar en minutos.
Parece mucho para un cambio de CSS. Pero el costo de una hora de checkout roto en una marca grande supera largamente el tiempo de hacer las pruebas bien.
Errores que se repiten
Más allá de lo técnico, hay patrones que aparecen en casi todos los proyectos:
- Querer replicar el checkout de otra plataforma pixel por pixel. Se termina peleando contra el producto en vez de aprovecharlo.
- Resolver problemas de catálogo, precio o logística con parches en el front.
- Acumular scripts de distintas agencias a lo largo de los años sin que nadie sepa qué hace cada uno.
- No medir. Si no tenés el embudo del checkout por paso, no sabés si tu cambio mejoró o empeoró la conversión.
¿Y un checkout headless?
Existe la opción de armar un checkout propio consumiendo las APIs. Lo considero solo cuando hay una necesidad de negocio que el nativo no cubre y un equipo capaz de mantenerlo, porque asumís el flujo de pago, la seguridad y cada cambio futuro de la plataforma.
Para la gran mayoría de las tiendas, un checkout nativo bien configurado, con customizaciones limpias y medidas, convierte mejor y da muchos menos dolores de cabeza que uno hecho a medida.
Para cerrar
El checkout se puede adaptar bastante, pero exige disciplina: tocar lo que corresponde por el canal correcto, no depender del DOM y tratar cada deploy como algo que puede costar ventas.
Si sos de una agencia y necesitás un arquitecto o dev VTEX senior para un proyecto de checkout, o si tenés una marca y querés una segunda opinión sobre las customizaciones que ya tenés, escribime y lo charlamos.
¿Te quedó alguna duda sobre tu caso?
Preguntame por WhatsApp