Un cliente pide una taza de regalo, escribe "¡Feliz cumpleaños, Sam!" en un campo de personalización y espera que ese mensaje llegue a la persona que imprime o empaqueta el pedido. El producto en sí no ha cambiado. No se creó ninguna variante o SKU nuevo. El mensaje pertenece a ese artículo comprado específico, y Shopify necesita un lugar confiable para transportarlo desde la página del producto hasta el carrito y el pedido.
Ese lugar es una propiedad de artículo de línea de Shopify. La función parece un campo personalizado simple, pero los problemas de producción suelen aparecer más tarde, cuando una integración actualiza una línea del carrito, un sistema de pedidos lee los datos, o los metadatos privados se vuelven inesperadamente visibles para el cliente. Entender el ciclo de vida completo, desde la captura hasta el procesamiento posterior, es más útil que tratar las propiedades como texto de personalización estático.
Tabla de contenidos
- Qué son realmente las propiedades de artículo de línea de Shopify
- Cómo se capturan las propiedades de artículo de línea en el carrito
- Dónde aparecen las propiedades de artículo de línea después del pago
- Casos de uso comunes y claves de propiedades de ejemplo
- Propiedades privadas y metadatos ocultos
- Comportamiento durante ediciones de pedidos posteriores a la compra
- Notas para desarrolladores y problemas de integración
- Mejores prácticas para comerciantes para datos de propiedades confiables
- Propiedades de artículo de línea en un flujo de trabajo posterior a la compra
- Errores comunes y cómo corregirlos
- Referencia rápida para propiedades de artículo de línea de Shopify
Qué son realmente las propiedades de artículo de línea de Shopify
Una propiedad de línea de artículo es metadatos personalizados de clave-valor asociados a una línea de carrito o línea de pedido. La clave identifica el campo, como Engraving, y el valor contiene los datos enviados o generados, como Happy Birthday, Sam!. Shopify documenta las propiedades como un objeto de pares clave-valor asociados a un artículo del carrito, y su documentación de temas describe la convención de nomenclatura de formulario de producto utilizada para enviarlos. La documentación de línea de artículo de Shopify también identifica la personalización, grabado, monogramas y cargas de archivos como usos prácticos.
La distinción importante es la propiedad. Una propiedad pertenece a la línea, no al registro del catálogo de productos ni al carrito en su totalidad. Si un cliente tiene dos copias de la misma taza con mensajes diferentes, cada línea necesita su propio conjunto de propiedades. Los metadatos viajan junto con el producto comprado en lugar de convertirse en una opción de producto.
Qué no son las propiedades
Las propiedades de línea de artículo no son variantes. Una variante representa una opción de catálogo como un tamaño o color oficial y puede afectar al inventario, precios y merchandising. Una propiedad captura información adicional que acompaña a un artículo seleccionado.
Tampoco son metacampos. Los metacampos son campos de datos estructurados asociados a recursos de Shopify como productos, clientes u pedidos. Una propiedad de línea de artículo está vinculada de forma más estrecha al elemento individual en la transacción.
En la representación del carrito de Shopify, los datos aparecen a través del campo properties. En los datos de pedidos, los desarrolladores trabajan con las propiedades o atributos de la línea de artículo correspondiente, según la superficie de la API. Esa distinción es importante al crear reglas de cumplimiento, pantallas de pedidos o integraciones.
Regla práctica: Si el valor describe lo que un cliente quiere que se haga con un artículo comprado, comienza evaluando una propiedad de línea de artículo. Si describe el registro del producto o cliente de forma más amplia, considera un modelo de datos de Shopify diferente.
Cómo se capturan las propiedades de línea de artículo en el carrito
Shopify admite dos patrones de captura comunes. Un tema puede enviar campos a través del formulario de producto, o un escaparate personalizado puede enviar datos de propiedad a través de una solicitud de carrito. Ambos enfoques adjuntan los valores enviados a la línea que se está añadiendo.
En un tema, el nombre del campo utiliza el patrón de corchetes de Shopify:
name="properties[Engraving]"
Una entrada de texto, área de texto, casilla de verificación u otro control de formulario puede utilizar esa convención de nomenclatura. Cuando el cliente envía el formulario del producto, Shopify interpreta Engraving como la clave de propiedad y almacena el valor enviado en la nueva línea del carrito. El valor podría ser un mensaje de grabado, una instrucción de regalo u otra información específica del artículo.
Una implementación personalizada puede enviar un objeto properties cuando añade o actualiza una línea de carrito a través de la API de carrito AJAX. El punto clave no es la interfaz utilizada para enviar el valor. Es la ubicación donde Shopify lo almacena, la línea de artículo específica que se está creando o modificando.

Lista de verificación de captura
- Mostrar el campo en el formulario de producto relevante: Una propiedad se recopila en el contexto del artículo que el cliente está añadiendo.
- Utilizar una clave estable:
EngravingyGift Messageson legibles en el carrito y en el pedido. Una etiqueta interna corta puede ser más difícil de interpretar para los equipos de operaciones. - Enviar el valor con la solicitud de añadir al carrito: Un campo que existe visualmente pero no se incluye en la solicitud no se convertirá en datos de pedido.
- Inspeccionar la línea de carrito resultante: Confirme tanto la clave como el valor antes de realizar el pago, especialmente cuando JavaScript modifica el carrito.
Para una visión más amplia de cómo los datos de la página de productos afectan al recorrido de compra, compare esta implementación con la orientación sobre optimización de pago de comercio electrónico. El mejor formulario es aquel que recopila solo la información que el cliente puede entender y que el equipo de cumplimiento puede utilizar.
Dónde aparecen las propiedades de artículos de línea después del pago
Después del pago, las propiedades se convierten en parte de los datos de la línea de pedido en lugar de permanecer como una entrada de página de producto temporal. La documentación de notificaciones de Shopify expone campos de artículos de línea incluyendo properties, line_price y quantity, mientras que su documentación de desarrollador continúa describiendo las propiedades como datos disponibles para flujos de pedidos e integraciones. La referencia de variables de notificación de Shopify es útil para verificar qué puede renderizar una plantilla de correo electrónico.
Diferentes superficies exponen la información de manera diferente. Un usuario de operaciones puede necesitar un valor legible en Shopify Admin, una integración de cumplimiento puede necesitar atributos legibles por máquina, y un cliente puede necesitar ver la personalización que envió. No asuma que un método de renderizado funciona en todas partes.
| Superficie | Cómo se exponen las propiedades |
|---|---|
| Carrito | La línea lleva sus datos de properties mientras el artículo permanece en el carrito. |
| Shopify Admin | Los datos de artículos de línea de pedido pueden exponer los valores a usuarios comerciales y de operaciones. |
| Notificaciones | Las variables de notificación Liquid pueden exponer propiedades de artículos de línea para plantillas compatibles. |
| GraphQL de Admin | Las propiedades se representan como atributos o propiedades de artículos de línea, dependiendo del recurso y el modelo de API. |
| Sistemas externos | Una integración lee los datos de propiedad de la línea de pedido y asigna las claves a sus propios campos de cumplimiento u operacionales. |
Diseñar para el lector de los datos
Un correo electrónico dirigido al cliente necesita etiquetas que tengan sentido para el comprador. Un sistema de producción puede necesitar claves estables que nunca cambien. Esas necesidades pueden coexistir, pero no deben confundirse.
Por ejemplo, Grabado es comprensible en una confirmación de pedido. Una aplicación de cumplimiento podría normalizar ese campo internamente como engraving.text. La aplicación debe asignar el valor deliberadamente en lugar de depender de una etiqueta de visualización que un comerciante pueda editar más tarde en el tema.
El mismo principio se aplica a las exportaciones y flujos de trabajo de pedidos. Prueba la superficie exacta donde se utilizará el valor. Una propiedad visible en el carrito Liquid puede requerir un manejo diferente en una respuesta de API o plantilla de notificación.
Casos de uso comunes y claves de propiedades de ejemplo
Las propiedades de artículos de línea funcionan mejor cuando la información pertenece a un artículo comprado y no necesita convertirse en una variante de catálogo. La personalización es el ejemplo más claro. Un cliente puede ingresar texto para un producto sin crear un registro de producto separado para cada mensaje posible.
Usa claves descriptivas que tengan sentido tanto para el cliente como para el equipo de cumplimiento. Los ejemplos a continuación son intencionalmente legibles en lugar de abreviados.
| Caso de uso | Clave de propiedad | Valor de ejemplo | Notas |
|---|---|---|---|
| Grabado | Texto de grabado |
¡Feliz cumpleaños, Sam! |
Usa un textarea cuando el mensaje puede contener varias líneas. |
| Envoltorio de regalo | Envoltorio de regalo |
Sí |
Una opción simple funciona bien para un servicio binario. |
| Mensaje de regalo | Mensaje de regalo |
Disfruta tu nuevo hogar. |
Mantén la etiqueta clara en las vistas de pedidos y correos electrónicos. |
| Archivo de cliente | Carga de archivo |
Una referencia de archivo o valor de carga enviado | Confirma que el flujo de trabajo receptor pueda resolver la referencia almacenada. |
| Selección personalizada | Acabado personalizado |
Negro mate |
Usa una variante cuando la opción afecta el inventario del catálogo o los precios. |
| Referencia comercial | Número de orden de compra |
PO-4581 |
Mantén el campo vinculado a la línea cuando artículos diferentes necesitan referencias diferentes. |
Elige el campo correcto para la respuesta
Un grabado corto puede usar una entrada de una sola línea. Una nota de regalo o instrucción de producción debe usar un textarea para que la interfaz refleje la respuesta esperada. Una casilla de verificación es apropiada para una opción sí o no, pero el valor enviado debe seguir siendo comprensible cuando aparezca en un pedido.
No uses una propiedad de artículo de línea para imitar una variante que Shopify necesita inventariar o fijar precios de forma independiente. Si seleccionar una opción cambia la gestión de inventario, la comercialización o el artículo realmente vendible, una variante puede ser un modelo más apropiado. Las propiedades son más fuertes para instrucciones, personalización, referencias y contexto operativo.
Las claves de propiedades también forman una interfaz práctica entre la tienda online y la oficina trasera. Cambiar Engraving Text a Message puede parecer inofensivo en un tema, pero una integración que lee la clave original puede dejar de encontrar el valor. Trata las claves importantes como parte de un pequeño contrato de datos.
Propiedades privadas y metadatos ocultos
Shopify admite propiedades de artículos de línea privadas prefijando la clave con un guion bajo. Por ejemplo, _vendor_sku y _cost_center comunican que el valor es metadatos operativos en lugar de una respuesta orientada al cliente. La documentación para desarrolladores de Shopify describe la convención del guion bajo para mantener tales valores fuera de la visualización orientada al cliente mientras se retienen para la lógica del sistema. La documentación de la API de artículos de línea del carrito también explica el comportamiento de objeto completo que los desarrolladores necesitan tener en cuenta al trabajar con estos atributos.

Usa el prefijo deliberadamente
Una propiedad visible debe responder a una pregunta del cliente o ayudar a un cliente a confirmar un pedido. Una propiedad privada debe respaldar un proceso interno, como una asignación de integración, instrucción de abastecimiento o referencia interna.
El guion bajo es parte de la clave. El código posterior debe solicitar _cost_center exactamente. No debe buscar cost_center y asumir que Shopify tratará los dos nombres como equivalentes.
Privado no significa "seguro para poner cualquier cosa aquí". Los controles de acceso, el manejo de webhooks y las integraciones de terceros merecen revisión. Mantén la información sensible fuera de las propiedades a menos que toda la ruta de datos haya sido evaluada. El prefijo controla la visibilidad orientada al cliente, no todas las rutas de acceso posibles.
Verificación de implementación: Crea una propiedad visible y una propiedad con prefijo de guion bajo en un pedido de prueba. Verifica qué ve el cliente, qué muestra el Admin y qué recibe tu integración antes de liberar el flujo de trabajo.
Comportamiento durante ediciones de pedidos post-compra
La edición post-compra es donde muchos flujos de trabajo de propiedades se vuelven ambiguos. Un comerciante o aplicación puede cambiar una línea, reemplazar un producto, ajustar una cantidad o crear una nueva línea. Cada acción debe evaluarse contra la carga útil de propiedades del artículo de línea actual, no contra la suposición de que la personalización original siempre seguirá.
El comportamiento de actualización documentado de Shopify es especialmente importante aquí. Cuando una actualización envía properties, el objeto enviado reemplaza el objeto existente en lugar de fusionar claves individuales. Eso significa que una solicitud destinada a cambiar un valor puede eliminar otros valores si la integración no los incluye en la carga útil de reemplazo.
Trata cada actualización como una reconciliación
Antes de cambiar una propiedad, una integración debe:
- Lee el conjunto de propiedades actual para la línea de destino.
- Aplica el cambio previsto a una representación local.
- Valida claves y valores requeridos.
- Envía el objeto completo resultante, incluidos los valores que no fueron modificados.
- Confirma que la respuesta contiene el conjunto esperado.
Este patrón es importante cuando un cliente cambia un grabado pero aún necesita el mensaje de regalo y la bandera de producción interna. Enviar solo el grabado nuevo puede borrar accidentalmente las otras claves.
Reemplazar una línea con una línea recién creada también merece un manejo explícito. Una nueva línea tiene su propio payload de propiedades. Si el flujo de trabajo necesita preservar la personalización, la aplicación debe copiar y validar deliberadamente los valores relevantes en lugar de asumir que Shopify inferirá esa relación.
Para comerciantes que evalúan la edición orientada al cliente, la guía de edición de pedidos de Shopify proporciona un contexto operativo útil. La pregunta de implementación sigue siendo específica: ¿qué línea se está cambiando, qué propiedades son requeridas y qué payload completo recibirá Shopify?
Notas para desarrolladores y trampas de integración
Los bugs de propiedades más perjudiciales generalmente no son causados por el formulario inicial. Ocurren durante actualizaciones, cuando una integración trata un payload parcial como un parche aunque Shopify trata el objeto properties como un reemplazo.
Supongamos que una línea actualmente contiene Engraving, Gift Message y _production_route. Una actualización que envía solo Engraving puede dejar la línea sin los otros dos valores. El enfoque seguro es recuperar el objeto actual, fusionar el cambio previsto en el código de la aplicación y enviar el resultado completo.
Construye actualizaciones alrededor del objeto completo
Usa un pequeño auxiliar con comportamiento explícito en lugar de dispersar actualizaciones de propiedades en scripts del carrito:
- Lee primero: Obtén la línea actual y sus propiedades.
- Normaliza claves: Aplica una convención de nomenclatura y preserva el guion bajo en claves privadas.
- Fusiona intencionalmente: Cambia solo el valor solicitado en memoria.
- Valida antes de enviar: Rechaza campos requeridos faltantes y valores inapropiados.
- Reemplaza conscientemente: Envía el objeto de propiedad completo porque Shopify no lo fusionará por ti.
No resuelvas esto copiando ciegamente cada valor para siempre. Una propiedad puede ser obsoleta, controlada por el cliente o ya no apropiada después de un cambio de producto. La integración debe definir qué claves se retienen, se eliminan o se regeneran.
Para implementaciones más grandes, un recurso de desarrollo de aplicaciones Shopify puede ayudar a los equipos a pensar en autenticación, webhooks, contratos de datos y manejo de actualizaciones como un sistema. Las agencias que trabajan en la capa de tienda y pedidos también pueden evaluar servicios Shopify cuando el flujo de trabajo necesita implementación personalizada más allá de campos de tema.
Valida lo que tu flujo de trabajo realmente admite
La documentación de Shopify suministrada confirma la semántica de reemplazo y el manejo de claves privadas. No establece un límite universal de recuento de propiedades o longitud de caracteres para cada superficie. No añadas límites no documentados a la validación solo porque una aplicación, punto de acceso o implementación de tema particular tenga su propia restricción.
En su lugar, prueba la ruta de solicitud exacta que utilizas. Comprueba valores vacíos, actualizaciones repetidas, caracteres Unicode, mensajes largos, referencias de archivos y claves privadas. Registra la solicitud y respuesta en un entorno de desarrollo, mientras eliminas datos sensibles de clientes de los registros de producción.
Buenas prácticas comerciales para datos de propiedades confiables
Trata las claves de propiedades como un esquema pequeño. Una clave como engraving.text o gift.wrap_message indica a los desarrolladores qué representa el campo, mientras que un nombre de máquina estable evita que las integraciones se rompan cuando la etiqueta visible cambia.
Mantén la etiqueta del cliente separada de la clave interna donde tu implementación lo permita. Los clientes pueden ver "Mensaje de grabado", mientras que el código continúa utilizando un identificador estable. Si una clave ya se utiliza en pedidos activos o asignaciones posteriores, no la cambies de nombre casualmente. Añade una clave nueva y define un plan de migración si el modelo de datos necesita cambiar.
Un estándar operativo práctico
- Valida antes de añadir al carrito: La personalización requerida no debe llegar al checkout como un valor vacío.
- Mantén los valores legibles: El personal de cumplimiento debe entender el pedido sin traducir abreviaturas.
- Separa la visibilidad de las operaciones: Utiliza una clave con prefijo de guion bajo para metadatos que no deberían aparecer en la vista del cliente.
- Muestra la opción enviada en el mensaje de confirmación: Los clientes deben poder verificar lo que solicitaron.
- Conserva la fuente de verdad: Si otro sistema copia la propiedad, retén el valor de línea de artículo original y documenta la asignación.
- Prueba ediciones, no solo el checkout inicial: Un flujo de propiedades no está completo hasta que sobrevive a las actualizaciones que tu equipo de soporte espera hacer.
Las propiedades de línea de artículo son datos de pedidos útiles, pero no son automáticamente un sustituto para cada estructura de datos de Shopify. Si un valor necesita ser consultado, reportado o mantenido independientemente de una línea comprada particular, evalúa si un metafield de pedido u otro recurso es más adecuado.
Propiedades de línea de artículo en un flujo de trabajo posterior a la compra
El uso más fuerte de propiedades de línea de artículo aparece después de que se coloca el pedido. Un valor de personalización puede informar el cumplimiento, una bandera interna puede enrutar la producción, y un valor visible para el cliente puede respaldar una revisión de pedido. La propiedad se convierte en una conexión entre la instrucción del comprador y los equipos o sistemas que actúan en consecuencia.
Una aplicación de edición de pedidos de autoservicio puede leer la personalización de una línea, presentar el valor existente al cliente y escribir el valor revisado bajo la misma clave. Ese flujo de trabajo solo funciona de forma confiable cuando la aplicación identifica la línea correcta y envía el objeto de propiedad completo durante la actualización.
El mismo principio se aplica a las recompras y ofertas posteriores a la compra. Una experiencia de reorden puede usar valores de propiedades anteriores como valores predeterminados, pero debe distinguir entre preferencias reutilizables e instrucciones puntuales. Un mensaje de cumpleaños puede ser específico de un pedido, mientras que un formato de grabado podría ser útil nuevamente.
Proporciona a cada usuario descendente un contrato claro
El cumplimiento necesita un valor procesable. El servicio al cliente necesita un valor legible. Un sistema externo necesita una clave predecible. Define esas expectativas antes de agregar más campos al formulario de producto.
Por ejemplo, un flujo de producción podría consumir Engraving Text, mientras que una propiedad privada _production_route le indica a un proceso interno dónde debe ir el artículo. La tienda no necesita exponer el detalle de enrutamiento, y el sistema de cumplimiento no debe depender únicamente de una etiqueta orientada al cliente.
Errores Comunes y Cómo Solucionarlos
La mayoría de los fallos se pueden rastrear en uno de tres lugares: el formulario de producto, la solicitud de actualización del carrito, o la plantilla o integración que lee el pedido.
| Síntoma de Error | Causa Probable | Solución Rápida |
|---|---|---|
| Una propiedad desaparece después de una actualización del carrito | La actualización envió solo la clave modificada, reemplazando el objeto completo | Lee las propiedades actuales, fusiona el cambio y envía el objeto completo. |
| Un campo aparece en la página pero no en el carrito | El nombre de entrada no usa el patrón properties[...] o JavaScript lo omitió |
Inspecciona la solicitud de añadir al carrito y confirma el nombre de campo enviado. |
| Un valor privado aparece en una vista orientada al cliente | La clave no tenía el prefijo _, o el código de visualización la renderiza sin filtrar |
Usa el prefijo de guion bajo para metadatos privados y filtra claves privadas en renderizado personalizado. |
| Una integración no puede encontrar una propiedad | Espera una ortografía de clave diferente o elimina el guion bajo | Define claves estables y referencia _key_name exactamente cuando la propiedad es privada. |
| Una notificación muestra una etiqueta en blanco | La plantilla lee el objeto incorrecto o asume que existe una propiedad en cada línea | Inspecciona la variable de artículo de línea de la notificación y maneja valores faltantes de forma segura. |
| Un artículo de reemplazo pierde personalización | La nueva línea se creó sin copiar la carga útil anterior | Reaplicar solo las propiedades requeridas y validarlas antes de que se guarde el reemplazo. |
Usa las herramientas de desarrollador del navegador para problemas de captura del carrito. Usa los datos del pedido y la carga útil del webhook para problemas descendentes. El diagnóstico más rápido proviene de comparar el valor en cada límite en lugar de depurar el correo electrónico final o la pantalla de cumplimiento de forma aislada.
Referencia Rápida para Propiedades de Artículos de Línea de Shopify
Usa esta tabla como una revisión compacta antes de cambiar un tema, script del carrito o integración de pedidos.
| Pregunta | Respuesta práctica |
|---|---|
| ¿Qué es una propiedad? | Metadatos clave-valor adjuntos a un artículo de línea de carrito u orden específico. |
| ¿Es una variante? | No. Acompaña al artículo comprado y no representa una variante del catálogo. |
| ¿Cómo se captura en un tema? | Utiliza un campo de formulario de producto nombrado con el patrón properties[Key]. |
| ¿Dónde se almacena en el carrito? | En el objeto properties del artículo de línea. |
| ¿Qué sucede durante una actualización? | Un objeto properties enviado reemplaza el objeto existente, así que envía el conjunto completo. |
| ¿Cómo oculto metadatos operacionales? | Antepón el prefijo _ a la clave, luego referencia esa clave exacta en el resto del flujo. |
| ¿Qué deben validar las integraciones? | Claves requeridas, valores esperados, reglas de visibilidad y el comportamiento de la ruta o API exacta en uso. |
| ¿Qué debo probar? | Agregación inicial al carrito, actualizaciones del carrito, visualización de pago, notificaciones, lecturas de orden y ediciones posteriores a la compra. |
La mentalidad de implementación duradera es simple: captura propiedades en la línea correcta, preserva el objeto completo durante las actualizaciones y proporciona a cada sistema descendente un contrato claro. Ese enfoque previene la pérdida de datos sutil que una demostración básica de personalización raramente expone.
Mayra ofrece herramientas para edición de pedidos posteriores a la compra y ventas adicionales, con cambios visibles para el cliente gestionados a través de la página de estado del pedido y cuentas de cliente mientras que Shopify sigue siendo el sistema de registro. Si tu flujo de trabajo de propiedades de artículos de línea necesita conectar con cambios de orden controlados, visita Mayra para revisar el enfoque disponible.

