Si vendés con Shopify y manejás IVA, el flujo mínimo es este: validar el dato fiscal, revisar el pedido después del checkout, guardar prueba por orden y separar reglas de AR, UE y UK. Si no hacés esas 4 cosas, te quedan pedidos con exenciones mal aplicadas, VAT IDs sin control y tax_lines que no cierran con la regla fiscal.
Yo lo bajaría así, en simple:
orders/create, orders/paid y cambios de dirección o cliente.En otras palabras: no conviene usar la API para reescribir el impuesto cobrado. Conviene usarla para validar, comparar, marcar desvíos y dejar respaldo para finanzas, soporte, auditoría y atención al cliente en WhatsApp.
Flujo de integración Shopify + VAT API: validación fiscal paso a paso
| Tema | Qué conviene hacer |
|---|---|
| Checkout | Validación asíncrona, sin frenar compra salvo exención B2B obligatoria |
| Creación de pedido | Revalidar con orders/create |
| Pago confirmado | Conciliar con orders/paid |
| Almacenamiento | Metafields en Shopify + respuesta completa fuera de Shopify |
| UE/UK | Validar VAT ID antes de eximir o aplicar reverse charge |
| Argentina | Controlar CUIT y condición fiscal antes de pasar a facturación |
| Fallo de API | Cobrar tasa estándar, marcar VAT-RETRY y reintentar |
Con ese esquema, yo armaría la integración pensando menos en “calcular impuestos” y más en controlar decisiones fiscales pedido por pedido.
Con el problema ya claro, ahora toca dejar Shopify y la API fiscal hablando el mismo idioma. Antes de integrar nada, resolvé tres frentes: la configuración fiscal en Shopify, las credenciales de la API y el lugar donde vas a guardar los datos. Si salteás esta parte, después aparecen inconsistencias molestas y difíciles de seguir.
El primer paso está en Settings → Taxes and duties. Ahí tenés que revisar que la registración fiscal de Argentina esté cargada con las alícuotas correctas según las reglas de AFIP, y que las categorías de tasa reducida y exportaciones estén separadas como corresponde.
Después, andá a Settings → Markets y revisá mercado por mercado. En ese punto definís si el precio se muestra con o sin impuesto. Para B2C, conviene mostrar el precio final. Para B2B, trabajá sin impuesto y dejá que la validación decida si corresponde aplicar IVA.
Con ese esquema ya resuelto, pasá a las credenciales y a los endpoints.
Primero, confirmá que la API tenga al menos estos tres grupos de funciones:
Para cada endpoint, revisá el método HTTP, los campos obligatorios y el esquema de errores (útil para depurar problemas de integración API). También conviene confirmar que tenés acceso a un sandbox separado de producción, el mecanismo de autenticación - por lo general, Authorization: Bearer <token> - y los límites de llamadas por minuto. Sumá un timeout corto y un fallback que no frene el checkout si la API no responde.
Esto hay que definirlo antes de programar. Los campos que guardes acá van a ser los mismos que después lean los webhooks y el control postcompra.
Si trabajás con clientes B2B en Shopify, usá el perfil de empresa (Companies) con el campo nativo Tax ID / VAT number. Ese campo ya trae validación nativa del Tax ID para clientes B2B de la UE y del Reino Unido. Si tu operación es B2C o mixta, creá un metafield de cliente con namespace tax y clave vat_number desde Settings → Custom data → Customers.
En el pedido, guardá el resultado de la validación en metafields de orden - por ejemplo, vat.validation_status - y usá tags para marcar el estado operativo. Esos tags y metafields después alimentan de forma directa el checkout, los webhooks y la revisión de pedidos.
| Nivel | Campo sugerido | Ejemplo de valor |
|---|---|---|
| Cliente B2B | Company → Tax ID | valid |
| Cliente B2C/mixto | Metafield tax.vat_number | valid |
| Pedido | Metafield vat.validation_status | valid / invalid / review |
| Pedido | Tag de orden | iva-validado, revisar-IVA |
Con esta estructura ya definida, el paso siguiente es conectar la validación con el checkout y con la creación de pedidos.
Shopify calcula el impuesto en el checkout. La VAT API, en cambio, valida el dato fiscal y después corrige o marca lo que haga falta en el back-office.
El punto de entrada cambia según el mercado y el tipo de tienda. Si usás Shopify Tax para la UE o el Reino Unido, el campo "Company VAT number" se puede activar desde el admin y ya trae una validación básica. Para Argentina, o si necesitás controles más finos, conviene capturar el CUIT/CUIL con una Checkout UI Extension y mandar la verificación de forma asíncrona a tu backend o integrar WhatsApp con Shopify para notificar al cliente.
Acá hay una idea simple que suele funcionar bien: usá una validación no bloqueante. Devolvé válido, inválido o no encontrado, y mostrale el mensaje al usuario sin frenar la compra. Solo tiene sentido bloquear operaciones B2B cuando la exención fiscal sea obligatoria.
Si el dato pasa el checkout, el control no termina ahí. Sigue con orders/create y orders/paid.
Una vez creado el pedido, los webhooks pasan a ser la pieza central. Shopify cobra el importe; la VAT API solo define cómo etiquetar la orden y qué revisar después.
| Evento Shopify | Webhook / endpoint | Llamada a la VAT API | Momento |
|---|---|---|---|
orders/create | Webhook orders/create en tu app | Validación de CUIT (AR) o VAT ID (UE/UK) | Justo después de creado el pedido |
orders/paid | Webhook orders/paid | Conciliación fiscal final | Después de confirmado el pago |
orders/updated | Webhook orders/updated | Revalidar si cambia la dirección o los ítems | Asíncrono |
customers/update | Webhook customers/update | Revalidar CUIT o VAT ID cuando el comprador actualiza sus datos | En cualquier momento |
Cuando se dispara orders/create, leé tax_lines, customer, shipping_address, el VAT/CUIT guardado y tax_exempt. Después, etiquetá la orden y guardá el resultado.
Con el pedido ya creado, el siguiente paso es revisar las tax lines y dejar evidencia fiscal para la revisión postcompra.
El impuesto cobrado que aparece en tax_lines cuando se crea el pedido no lo tiene que reescribir la VAT API. Ese punto es CLAVE. Lo que sí puede hacer es comparar ese importe con la tasa correcta según el destino y la condición fiscal, y clasificar el pedido como correcto, sobrecobrado o subcobrado.
En pocas palabras: compará, etiquetá y derivá. No reescribas el impuesto cobrado. Ese etiquetado deja listo el terreno para la verificación de tax lines y los registros de compliance.
Con el pedido ya creado, toca hacer una revisión simple pero clave: confirmar que el IVA cobrado coincide con la regla fiscal aplicada y dejar respaldo para finanzas y auditoría. Después de clasificar el pedido, conviene chequear si el impuesto que figura en Shopify cierra con lo que debería haberse cobrado.
Leé tax_lines del pedido, de cada ítem y del envío, y revisá title, rate y price. Si el carrito mezcla productos o tratamientos fiscales distintos, no alcanza con mirar el total general: hay que revisar línea por línea y comparar esa suma con el monto esperado.
Desde 2024, Shopify devuelve tax_lines con valor cero en pedidos exentos. Eso sirve como prueba de auditoría, porque deja asentado que la exención se aplicó de manera explícita. Sumale a eso la lectura de order.tax_exempt, customer.taxExempt y customer.taxExemptions para entender por qué no se cobró impuesto.
En operaciones B2B, también conviene revisar los datos fiscales del cliente o de la empresa, como el VAT ID o el CUIT, junto con la dirección de facturación. Ahí podés confirmar si el tratamiento aplicado - gravado, exento, tasa reducida o reverse charge - coincide con el destino de envío y con el tipo de comprador. Si algo no cierra, marcá esa línea para revisión antes de dar el caso por cerrado.
Guardá un resumen en metafields del pedido - por ejemplo, vat.validation_status, validated_at y review_required - y almacená la respuesta completa fuera de Shopify para retención y auditoría. En UK y la UE, la evidencia de validación debe conservarse durante al menos 6 años.
Un esquema de etiquetas claro le ahorra idas y vueltas a finanzas y soporte:
| Situación | Etiqueta sugerida |
|---|---|
| VAT ID inválido o no encontrado | vat-invalid |
| Nombre o dirección no coinciden | vat-review |
| Exención verificada correctamente | vat-exempt-verified |
| Falta documentación de soporte | vat-docs-needed |
| Destino o exención inconsistente | vat-review |
En Argentina, si el CUIT no pasa la validación o la condición fiscal no coincide con el tipo de factura emitida, el pedido debería quedar marcado para revisión.
Esas etiquetas no sirven solo para ordenar. También permiten actuar sobre el pedido sin perder tiempo. Burbuxa puede leer esas etiquetas desde Shopify y enviar por WhatsApp o Instagram pedidos de documentación faltante o mensajes para confirmar el tratamiento fiscal con el cliente.
La VAT API usa tres datos clave - destino, tipo de comprador y valor de la operación - para definir el impuesto antes de confirmar la orden. Con eso resuelto, ya podés pasar a las reglas de cada país y al tratamiento fiscal de cada pedido.
En ventas B2C dentro de la UE, el umbral es de €10.000 anuales en ventas transfronterizas. Mientras no se supere ese monto, se puede seguir el esquema local que corresponda. Pero una vez pasado ese límite, hay que cobrar el IVA del país de destino. Ahí entra en juego el OSS, que permite declarar todo desde un solo Estado miembro, sin tener que darse de alta en cada país por separado.
Para envíos desde fuera de la UE con valor intrínseco de hasta €150, el IOSS hace el proceso bastante más simple. La idea es directa: se cobra el IVA del país de destino en el checkout y luego se declara en una sola ventanilla mensual. Eso evita fricción al momento de la entrega y ordena mejor el circuito fiscal. Además, reducir la fricción en el checkout es una de las mejores estrategias de recuperación de carritos.
Si un cliente solicita una exención B2B, no alcanza con marcar una casilla y seguir. Hay que validar el VAT ID, el país de facturación y la condición fiscal antes de aplicar la inversión del sujeto o dejar la orden exenta. En la UE y en UK, si ese número no se valida, no corresponde dar la exención y el impuesto se cobra de forma normal.
El caso del Reino Unido post-Brexit va por un carril propio. Para pedidos de £135 o menos, el vendedor tiene que estar registrado en UK VAT y cobrar el impuesto en el punto de venta dentro de Shopify. Si el pedido supera £135, ya entran el IVA de importación y los aranceles. En ese escenario, el cálculo en checkout se mezcla con duties e import taxes.
Para exportaciones fuera de la UE y UK, el tratamiento usual es tasa cero. Pero ojo: tasa cero no significa “sin respaldo”. Conviene dejar documentado el destino, el tipo de comprador y el motivo de la exención, y guardar esa evidencia junto con el pedido. Una etiqueta como export_zero_rated sirve para identificar al instante cómo fue tratada cada orden.
Después de eso, la misma lógica se puede bajar al frente local en Argentina.
Para tiendas que operan desde Argentina, la alícuota general de IVA es 21% para la mayoría de los bienes y servicios de e-commerce. Hay rubros que tributan 10,5%, pero el 21% sigue siendo la referencia más común.
Acá conviene separar desde el inicio los pedidos locales de los pedidos de exportación. No es un detalle menor: esa división impacta en la emisión del comprobante, en la contabilidad y en el control fiscal. Los pedidos domésticos requieren factura A, B o C según la condición fiscal del comprador, mientras que las exportaciones siguen otro tratamiento.
También suma mantener el dato fiscal bien armado antes de enviarlo al sistema que emite comprobantes. Si el flujo está prolijo desde el checkout, después evitás errores al facturar. Y en los ejemplos, usá siempre formato local, como AR$ 1.250.000,50, para que precios, reportes y validaciones hablen el mismo idioma.
Con estas reglas separadas, el flujo mínimo queda listo para pasar a implementación.
Después de definir las reglas por región, conviene cerrar el circuito con un flujo mínimo que funcione de punta a punta. Cuando ya tenés resueltos el checkout, la postcompra y los pedidos internacionales, la integración se apoya en cuatro capas: configuración, validación, trazabilidad y seguimiento. Si una falla, el flujo queda a medio hacer.
Shopify calcula, la VAT API valida, los webhooks registran y finanzas guarda la evidencia. Ese reparto de tareas deja claro qué hace cada parte y evita zonas grises. Si la API falla, la salida más segura es cobrar el impuesto estándar, marcar VAT-RETRY y reintentar en segundo plano.
Así, soporte puede intervenir caso por caso sin frenar la compra. Burbuxa usa etiquetas y metafields para pedir los datos que faltan y avisarle a soporte cuando hace falta.
Usá esta lista para chequear que la integración quedó lista para salir a producción.
| Área | Qué verificar |
|---|---|
| Configuración Shopify | Registros fiscales cargados y tasas verificadas en SKUs clave. |
| Captura en checkout | Campos de VAT/IVA visibles solo cuando corresponde. Mensajes de validación claros, en español. |
| Webhooks | orders/create y orders/paid activos, con idempotencia. |
| Evidencia y almacenamiento | Resultado de validación en metafields y base externa; indicadores de régimen e IDs consultables. Retención mínima: 10 años para OSS/IOSS y 6 años para UK. |
| Flujos por región | Checklists separados para UE/UK y para IVA argentino/AFIP. |
| Monitoreo | Alertas cuando falla la VAT API o cuando las órdenes con etiqueta VAT-REVIEW pasan el SLA definido. |
La aprobación técnica cubre la confiabilidad del flujo y cómo responde ante fallos. La aprobación de finanzas confirma que los datos capturados alcanzan para respaldar declaraciones y auditorías. Las dos tienen que estar antes del pase a producción.
No necesariamente. Si Shopify ya calcula los impuestos según tu configuración, no siempre necesitás una VAT API para aplicar IVA en el checkout.
Ahora bien, sí te puede servir si necesitás validaciones extra, como CUIT/CUIL, códigos fiscales o más consistencia en pedidos internacionales y procesos de postcompra.
En esos casos, una API de impuestos suma para:
Dicho simple: Shopify puede alcanzar para el cálculo base, pero una API externa te da una capa más de control cuando la operación se pone un poco más compleja.
Si la API de impuestos falla durante el checkout, lo primero es revisar si los datos que estás enviando son correctos, si cumplen con la normativa vigente y si el JSON tiene la estructura esperada. Después, mirá los logs para detectar de dónde viene el error. Muchas veces el problema no está en el checkout en sí, sino en un campo mal armado, un dato faltante o un formato que la API no acepta.
Como paso extra, podés validar la factura en AFIP y chequear los totales y los impuestos aplicados. Eso te ayuda a confirmar si el cálculo salió bien o si algo se desvió en el proceso.
Si el problema sigue, conviene aplicar reintentos con espera exponencial y sumar una cola de eventos fallidos. Así podés revisar los errores con calma, sin frenar el flujo de compra ni dejar al usuario clavado en el checkout.
Conviene bloquearla cuando no haya datos fiscales verificados de compradores no categorizados. Si esos datos no se validan, la AFIP puede aplicar de forma automática una percepción del 10,5% de IVA. Y eso después suele traer roces con clientes inscriptos a los que no les corresponde pagarla.
Para evitar ese problema, validá en tiempo real la CUIT, la condición fiscal y la jurisdicción contra registros oficiales antes de emitir el comprobante.